feat(runtime): durable run loop — wire supervisor resume + journal the kernel loop

[drewstone]

Durable run loop

Makes an agent run survive a worker crash or restart by wiring the run loop onto durable journals, reusing the runtime's existing resume primitives.

• Supervisor resume — createSupervisor().run() loads an existing tree and rehydrates settled children (replaySpawnTree / materializeTreeView) instead of always starting fresh. These primitives were already built and tested; this wires them in.
• Durable journal by default — the run context uses the file-backed SpawnJournal instead of the in-memory one, so a run's progress is durable without the caller opting in.
• Kernel loop journal — each committed iteration is journaled; a restart resumes from the last committed offset rather than re-running from the start.

Verification

A run killed mid-flight and reloaded resumes from the last committed step and does not redo committed work.

Relationship to the shared package

The kernel journal and tool-call repair are the agent-runtime consumer of the shared durability primitives (@tangle-network/sdk-core/durability); once that package publishes, this re-points onto the shared contract so the runtime and the sandbox/cli-bridge paths share one recovery story.

[tangletools]

✅ Auto-approved PR — 3e0c0f49

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-20T14:05:37Z}

[tangletools]

🟠 Value Audit — better-approach-exists

Verdict	better-approach-exists
Concerns	2 (1 medium-concern, 1 low)
Heuristic	0.0s
Duplication	0.0s
Interrogation	417.1s (2 bridge agents)
Total	417.1s

💰 Value — better-approach-exists

Adds coherent crash-resume durability to runLoop and supervised runs, but LoopJournal duplicates the existing ConversationJournal adapter layer instead of reusing a shared substrate.

• What it does: Wires durable crash-resume into two runtime paths. (1) runLoop gains a LoopJournal interface (InMemoryLoopJournal + FileLoopJournal) that loads prior iterations on start, appends each committed round before planning the next, and records end on finalization; resumed runs skip committed iterations and ended runs short-circuit to the recorded result. (2) Supervisor.run now loads the spawn journal tr
• Goals it achieves: Make agent runs survive a worker or driver process crash/restart without redoing already-committed work; give real (non-test) supervised runs a durable-by-directory context; align the kernel loop with the existing ConversationJournal durability pattern and the supervisor with its own already-built replay primitives.
• Assessment: Good change that achieves its stated goal coherently. The commit boundary is well-placed (after workers drain and outputs fold), file appends fsync, ended runs are idempotent, and the tests in tests/loops/run-loop-durability.test.ts prove no-redo resume for both kernel and supervisor paths. The Supervisor wiring correctly reuses existing tested primitives rather than inventing new replay logic.
• Better / existing approach: LoopJournal's InMemoryLoopJournal and FileLoopJournal are near-identical structural clones of InMemoryConversationJournal and FileConversationJournal in src/conversation/journal.ts (compare journal.ts:58-194 with loop-journal.ts:58-193). Both use the same Map-with-defensive-copy, JSONL line-per-record, fsync-on-append, begin/append/end record shapes, isNoEntError helper, and startedAt-mismatch gua
• Model: kimi-code/kimi-for-coding
• Bridge attempts: 3
• Bridge warning: opencode/deepseek/deepseek-v4-pro: bridge stream ended without value-audit content; opencode/zai-coding-plan/glm-5.1: bridge stream ended without value-audit content

🎯 Usefulness — sound

Wires crash-durability into both the supervised run and kernel loop using the codebase's existing journal patterns — reload recovers committed work without redoing it.

• Integration: Reachable through two paths. (1) Supervisor: createFileRunContext(dir) or createInMemoryRunContext({dir}) → spread into SupervisorOpts → supervisor.ts:102-116 loads prior tree, rehydrates via replaySpawnTree/materializeTreeView, passes resumeFrom to scope → scope exposes scope.resume (scope.ts:433-438, types.ts:332) consumable by any Agent.act. The examples/supervisor-loop/loop.ts:208 caller alrea
• Fit with existing patterns: Mirrors the codebase's two existing journal patterns precisely: ConversationJournal (src/conversation/journal.ts — begin/append/load shape, in-memory+JSONL+SQL impls) and SpawnJournal (src/durable/spawn-journal.ts:132-250 — same shape, same fsync-per-append). The LoopJournal file adapter (loop-journal.ts:127-217) is a structural clone of FileSpawnJournal (same JSONL format, same isNoEntError guard
• Real-world viability: 339-line test (tests/loops/run-loop-durability.test.ts) proves end-to-end: file journal round-trips across instances (L160-197), in-memory resume skips committed rounds and only executes un-committed ones (L81-124, creates=2 not 3), ended run short-circuits to recorded result with zero boxes (L126-158), supervisor file-context resume rehydrates children from disk and does not re-execute (L274-338,
• Model: opencode/deepseek/deepseek-v4-pro
• Bridge attempts: 1

🔎 Heuristic Signals

🟡 Cruft: magic number added tests/loops/run-loop-durability.test.ts

•        budget: { maxIterations: 1, maxTokens: 1000 },
  

💰 Value Audit

🟠 LoopJournal adapters duplicate ConversationJournal adapters [duplication] ``

src/runtime/loop-journal.ts:58-193 mirrors src/conversation/journal.ts:58-194 almost line-for-line: Map storage, defensive copy, JSONL file adapter with fsync, record kind shapes, corruption guards, and isNoEntError. Better approach: extract a generic append-only journal substrate in this repo, or move directly to the shared durability package the PR says will replace this. This also closes the SQL-adapter gap: ConversationJournal has SqlConversationJournal (src/conversation/journal-sql.ts) w

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260620T141416Z}