agent-accelerator 0.5.2 → 0.5.3

package/src/agent/loop.ts

@@ -18,6 +18,7 @@ import {
   shouldBlockRepeat,
   toolCallFingerprint,
   traceToolEvent,
+  type ExecuteToolsOptions,
 } from "../tools/executor.ts";
 import { getModelFromCatalog, ensureModelCatalogFresh, validateModelThinking } from "../models/catalog.ts";
 import { enforceFileAccess } from "../utils/safe-io.ts";
@@ -70,6 +71,15 @@ export interface AgentLoopConfig {
   enforceBudget?: (usage?: TokenUsage) => void;
   /** Called after every turn for durable persistence checkpoints (never fails a turn). */
   onProgress?: () => void;
+  /** Called the moment each tool call finishes, before the rest of its batch (the crash-proof record of finished work). */
+  onToolResult?: (result: ToolResultRecord) => void;
+  /** Opens the log file of one tool call (see `ToolLogs`); unset when the Agent does not persist to a folder. */
+  openToolLog?: ExecuteToolsOptions["openToolLog"];
+  /**
+   * Continue a run that a crash cut off instead of starting from a new prompt: tool calls the last assistant turn made
+   * without a stored result are finished first (a result in `stored` is reused, anything else runs now), then the loop goes on.
+   */
+  resume?: { stored: Map<string, ToolResultRecord> };
   /**
    * Shared steer inbox for mid-session redirection. Entries are drained
    * between turns (after the current provider/tool work finishes) and
@@ -438,7 +448,7 @@ export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): Tok
 // This function never mutates `source` (Q-35): the priced cost is cloned
 // into a local before folding into the target.
 // ---------------------------------------------------------------------------
-function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec): void {
+export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec): void {
   target.inputTokens += source.inputTokens || 0;
   target.outputTokens += source.outputTokens || 0;
   target.totalTokens += source.totalTokens || 0;
@@ -506,6 +516,8 @@ function sanitizeToolResult(r: ToolResultRecord): { sanitized: ToolResultRecord;
 async function executeToolCallsWithRepeatGuard(options: {
   tools: Record<string, ToolDefinition>;
   toolCalls: ToolCallRecord[];
+  onResult?: (result: ToolResultRecord) => void;
+  openToolLog?: ExecuteToolsOptions["openToolLog"];
   previousFingerprints: Set<string>;
   repeatCounts: Map<string, number>;
   agentName?: string;
@@ -546,6 +558,8 @@ async function executeToolCallsWithRepeatGuard(options: {
         signal: options.signal,
         sessionId: options.sessionId,
         onSubagentEvent: options.onSubagentEvent,
+        onResult: options.onResult,
+        openToolLog: options.openToolLog,
       })
     : [];
   const byId = new Map<string, ToolResultRecord[]>();
@@ -572,6 +586,73 @@ async function executeToolCallsWithRepeatGuard(options: {
   };
 }
 
+/** Tool calls of the LAST assistant message that have no result in the conversation yet (a crash or interrupt cut them off). */
+export function unfinishedToolCalls(messages: AgentContext["messages"]): ToolCallRecord[] {
+  let lastAssistant = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]!.role === "assistant") {
+      lastAssistant = i;
+      break;
+    }
+  }
+  const calls = lastAssistant < 0 ? [] : messages[lastAssistant]!.content;
+  if (!Array.isArray(calls)) return [];
+  const answered = new Set<string>();
+  for (const m of messages.slice(lastAssistant + 1)) {
+    if (m.role !== "tool" || !Array.isArray(m.content)) continue;
+    for (const p of m.content) if (p.type === "tool_result") answered.add(p.id);
+  }
+  const open: ToolCallRecord[] = [];
+  for (const p of calls) {
+    if (p.type === "tool_call" && !answered.has(p.id)) {
+      open.push({ id: p.id, name: p.name, arguments: p.arguments, ...(p.rawArguments ? { rawArguments: p.rawArguments } : {}), ...(p.callId ? { callId: p.callId } : {}) });
+    }
+  }
+  return open;
+}
+
+/** True when the conversation ends with tool results of a batch in which a tool called `ctx.stop` (the run was meant to end there). */
+export function endsWithStop(messages: AgentContext["messages"]): boolean {
+  for (let i = messages.length - 1; i >= 0 && messages[i]!.role === "tool"; i--) {
+    const content = messages[i]!.content;
+    if (Array.isArray(content) && content.some((p) => p.type === "tool_result" && p.stopped === true)) return true;
+  }
+  return false;
+}
+
+// Finishes the tool calls a crash left open (stored result reused, anything else executed now) and records the results in the conversation; in: a resumed run's config, out: tool results in context + what the response should report.
+async function finishInterruptedTools(
+  config: AgentLoopConfig
+): Promise<{ calls: ToolCallRecord[]; results: ToolResultRecord[]; subagents: SubAgentExecutionMetadata[] }> {
+  const open = unfinishedToolCalls(config.context.messages);
+  const none = { calls: [], results: [], subagents: [] };
+  if (open.length === 0 || !config.resume) return none;
+  const stored = config.resume.stored;
+  const toRun = open.filter((c) => !stored.has(c.id));
+  const executed = toRun.length
+    ? await executeToolCalls({
+        tools: config.tools,
+        toolCalls: toRun,
+        agentName: config.agentName,
+        parallel: true,
+        signal: config.runOptions?.signal,
+        sessionId: config.runOptions?.sessionId || config.options?.sessionId,
+        onResult: config.onToolResult,
+        openToolLog: config.openToolLog,
+      })
+    : [];
+  const ran = new Map(executed.map((r) => [r.id, r]));
+  const subagents: SubAgentExecutionMetadata[] = [];
+  const results = open.map((call) => {
+    const { sanitized, metas } = sanitizeToolResult(ran.get(call.id) ?? stored.get(call.id)!);
+    subagents.push(...metas);
+    return sanitized;
+  });
+  config.context.addToolResults(results);
+  emitProgress(config);
+  return { calls: open, results, subagents };
+}
+
 /**
  * Runs a single non-streaming agent turn or multi-turn loop
  */
@@ -614,13 +695,28 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   let finalResult: any = null;
   let turns = 0;
   let toolsExecuted = false;
+  let stoppedByTool = false;
   let previousToolCallFingerprints = new Set<string>();
   const repeatCounts = new Map<string, number>();
 
   try {
   const standardTools = toStandardToolDeclarations(tools);
 
-  while (turns < maxTurns) {
+  if (config.resume) {
+    const finished = await finishInterruptedTools(config);
+    stoppedByTool = finished.results.some((r) => r.stopped) || endsWithStop(context.messages);
+    if (finished.calls.length > 0) {
+      toolsExecuted = true;
+      allToolCalls.push(...finished.calls);
+      allToolResults.push(...finished.results);
+      for (const meta of finished.subagents) {
+        allSubagents.push(meta);
+        accumulateUsage(accumulatedUsage, meta.usage, getModelFromCatalog(meta.provider, meta.model));
+      }
+    }
+  }
+
+  while (!stoppedByTool && turns < maxTurns) {
     // Q-21: fail fast on abort (throws AbortError with partial).
     throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: finalResult?.text });
     checkDeadline(startTime, limits.deadlineMs);
@@ -758,6 +854,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     // Execute tool calls — always parallel (model-driven, bloatfree DX7)
     // Q-21: check abort before tools (throws AbortError with partial).
     throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: genResult.text });
+    emitProgress(config); // the calls are on record BEFORE they run, so a crash can finish them instead of forgetting them
     allToolCalls.push(...genResult.toolCalls);
     // Q-22: per-run tool-call budget.
     if (allToolCalls.length > limits.maxToolCallsPerRun) {
@@ -774,6 +871,8 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       agentName,
       signal: runOptions?.signal,
       sessionId: runOptions?.sessionId || options?.sessionId,
+      onResult: config.onToolResult,
+      openToolLog: config.openToolLog,
     });
     const results = guarded.results;
     previousToolCallFingerprints = guarded.fingerprints;
@@ -811,6 +910,12 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       toolCalls: genResult.toolCalls,
       toolResults: sanitizedResults,
     });
+    // A tool ended the run (`ctx.stop`): the whole batch has finished, so stop here. Waiting steers become follow-ups.
+    if (sanitizedResults.some((r) => r.stopped)) {
+      stoppedByTool = true;
+      emitProgress(config);
+      break;
+    }
     // Steer drain AFTER tool results so call/result pairs stay adjacent.
     // The next loop iteration sends the injected user message to the model
     // within the same run (same usage/turn budget).
@@ -829,7 +934,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   // results above were never sent back, so the run is truncated — surface
   // it via finishReason + warning instead of silently returning.
   const truncatedByMaxTurns =
-    turns >= maxTurns && !!finalResult?.toolCalls && finalResult.toolCalls.length > 0;
+    !stoppedByTool && turns >= maxTurns && !!finalResult?.toolCalls && finalResult.toolCalls.length > 0;
   if (truncatedByMaxTurns) {
     warnMaxTurnsHit(
       agentName,
@@ -841,7 +946,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   // Structured outputs: validate final text only (tool turns skip this).
   // Strict-fail throws ValidationError with partial attached via catch below.
   let parsedOutput: unknown | undefined;
-  if (loopOutput.raw !== undefined && !truncatedByMaxTurns) {
+  if (loopOutput.raw !== undefined && !truncatedByMaxTurns && !stoppedByTool) {
     parsedOutput = parseFinalStructuredOutput(finalResult?.text || "", loopOutput.raw, loopOutput.spec);
   }
 
@@ -858,7 +963,9 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     model: modelId,
     provider: provider.id,
     // Q-04: canonical finish reason + raw vendor passthrough.
-    ...canonicalFinishReason(finalResult?.finishReason, truncatedByMaxTurns),
+    ...(stoppedByTool
+      ? { finishReason: "stopped" as const, ...(finalResult?.finishReason ? { rawFinishReason: finalResult.finishReason } : {}) }
+      : canonicalFinishReason(finalResult?.finishReason, truncatedByMaxTurns)),
     durationMs: Date.now() - startTime,
     raw: applyCaptureRaw(finalResult?.raw, config.captureRaw) as ProviderRawData,
     turns,
@@ -1016,6 +1123,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
       turns = 0;
       let previousToolCallFingerprints = new Set<string>();
       const repeatCounts = new Map<string, number>();
+      let stoppedByTool = false;
 
       while (turns < maxTurns) {
         throwIfCancelled({ usage: accumulatedUsage, turns, text: lastResponse?.text });
@@ -1198,6 +1306,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         }
 
         throwIfCancelled({ usage: accumulatedUsage, turns, text: turnResponse.text });
+        emitProgress(config); // the calls are on record BEFORE they run, so a crash can finish them instead of forgetting them
         allToolCalls.push(...turnResponse.toolCalls);
         if (allToolCalls.length > streamLimits.maxToolCallsPerRun) {
           throw new Error(
@@ -1219,6 +1328,8 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           agentName,
           signal: linked.signal,
           sessionId: runOptions?.sessionId || options?.sessionId,
+          onResult: config.onToolResult,
+          openToolLog: config.openToolLog,
           onSubagentEvent: (ev) => {
             try {
               outerStream.push({
@@ -1284,6 +1395,12 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           toolCalls: turnResponse.toolCalls,
           toolResults: sanitizedResults,
         });
+        // A tool ended the run (`ctx.stop`): the whole batch has finished, so stop here. Waiting steers become follow-ups.
+        if (sanitizedResults.some((r) => r.stopped)) {
+          stoppedByTool = true;
+          emitProgress(config);
+          break;
+        }
         const toolSteered = drainSteerInbox(context, config.steerInbox);
         if (toolSteered.length > 0) {
           for (const preview of toolSteered) {
@@ -1301,7 +1418,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
       }
 
       const truncatedByMaxTurns =
-        turns >= maxTurns && !!lastResponse?.toolCalls && lastResponse.toolCalls.length > 0;
+        !stoppedByTool && turns >= maxTurns && !!lastResponse?.toolCalls && lastResponse.toolCalls.length > 0;
       if (truncatedByMaxTurns) {
         warnMaxTurnsHit(
           agentName,
@@ -1309,10 +1426,12 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           lastResponse!.toolCalls.map((c) => c.name)
         );
       }
-      const truncatedFinish = canonicalFinishReason(lastResponse?.finishReason, truncatedByMaxTurns);
+      const truncatedFinish = stoppedByTool
+        ? { finishReason: "stopped" as const, ...(lastResponse?.finishReason ? { rawFinishReason: lastResponse.finishReason } : {}) }
+        : canonicalFinishReason(lastResponse?.finishReason, truncatedByMaxTurns);
 
       let streamParsed: unknown | undefined;
-      if (streamOutputRaw !== undefined && !truncatedByMaxTurns) {
+      if (streamOutputRaw !== undefined && !truncatedByMaxTurns && !stoppedByTool) {
         try {
           streamParsed = parseFinalStructuredOutput(lastResponse?.text || "", streamOutputRaw, streamOutputSpec);
         } catch (err) {

package/src/index.ts

@@ -317,7 +317,7 @@ export {
   formatSessionBanner,
   emptyTotals,
 } from "./session/store.ts";
-export type { SessionLimits, SessionPayloadStatus, PersistedAgentSession, SessionTotals, SessionAgentLike, LoadedSessionDir, PersistedSubAgentTrace } from "./session/store.ts";
+export type { SessionLimits, SessionPayloadStatus, PersistedAgentSession, SessionTotals, SessionAgentLike, LoadedSessionDir, PersistedSubAgentTrace, SessionRunMark, SessionRunEnd, SessionPending, SessionPendingPrompt, SessionToolRecord } from "./session/store.ts";
 
 // Utilities
 /**
@@ -414,6 +414,7 @@ export type {
   Budget,
   BudgetState,
   SubAgentRunIds,
+  InterruptedRun,
 } from "./types/agent.ts";
 
 // Minimalist core: harness modules (RLM/RSI, OTel, testing, CLI doctor, hooks,

package/src/models/catalog-cache.ts

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
 import { getEnv } from "../utils/env.ts";
 import { telemetryBus } from "../telemetry.ts";
 import { onHomeChange, resolveHome } from "../utils/home.ts";
+import { writeFileDurable } from "../utils/durable.ts";
 
 /** Default TTL: 12 Hours (in milliseconds). */
 export const DEFAULT_CATALOG_TTL_MS = 12 * 60 * 60 * 1000;
@@ -102,17 +103,9 @@ function readJsonFileSync(filePath: string): any {
   }
 }
 
+// Writes the catalog cache durably but without a `.bak` (it is re-downloadable); in: path + payload from refreshModelCatalog, out: the cache file.
 function writeJsonFileSync(filePath: string, data: any): void {
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  // Atomic tmp+rename with 0600 so a crash never leaves half-written JSON (Q-16a).
-  const rand = Math.random().toString(36).slice(2, 10);
-  const tmp = `${filePath}.tmp-${process.pid}-${rand}`;
-  fs.writeFileSync(tmp, JSON.stringify(data), { encoding: "utf-8", mode: 0o600 });
-  try { fs.chmodSync(tmp, 0o600); } catch {}
-  fs.renameSync(tmp, filePath);
+  writeFileDurable(filePath, JSON.stringify(data), { backup: false });
 }
 
 /** Verifies optional sha256 pin from MODELS_DEV_SHA256 (Q-16a). Returns false on mismatch. */

package/src/scheduler/scheduler.ts

@@ -16,6 +16,7 @@ import type { Agent } from "../agent/agent.ts";
 import { createChildSessionId } from "../agent/delegation.ts";
 import { buildDynamicWorkerConfig, grantWorkerTools, normalizeWorkerTimeoutValue } from "../agent/worker.ts";
 import { telemetryBus } from "../telemetry.ts";
+import { lockFolder } from "../utils/durable.ts";
 import { ConfigError, ValidationError } from "../types/errors.ts";
 import type { ToolDefinition } from "../types/tool.ts";
 import type { AgentResponse } from "../types/response.ts";
@@ -649,6 +650,7 @@ const schedulers = new Map<string, Scheduler>();
 export function getScheduler(home: string): Scheduler {
   let s = schedulers.get(home);
   if (!s) {
+    lockFolder(home); // every scheduler function goes through here: one process per home
     migrateLegacyFolder(home);
     schedulers.set(home, (s = new Scheduler(home)));
   }

package/src/scheduler/store.ts

@@ -6,13 +6,13 @@
  *   <home>/scheduled_actions/<id>/<date>.md     one file per run
  *
  * The files are the source of truth: every write re-reads first (never writes
- * from a stale copy) and goes through `writeFileAtomic` (temp file + rename).
+ * from a stale copy) and goes through `writeFileDurable` (temp file, fsync, `.bak`, rename).
  * Sync `fs`, like the session store.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { z } from "zod";
-import { writeFileAtomic } from "../session/store.ts";
+import { readWithBackup, writeFileDurable } from "../utils/durable.ts";
 import { telemetryBus } from "../telemetry.ts";
 import { resolveHome } from "../utils/home.ts";
 export { resolveHome };
@@ -73,36 +73,49 @@ export function migrateLegacyFolder(home: string): void {
 
 type Raw = Record<string, unknown>;
 
-/** Reads a `{ version, <key>: [...] }` file. Missing = empty; corrupt = quarantined (`*.corrupt-<ts>`) + empty. */
-function readList(file: string, key: "tasks" | "pending"): Raw[] {
-  let text: string;
+// Parses a `{ version, <key>: [...] }` file into its object entries; undefined when the text is not that shape; in: raw file text, out: readList.
+function parseList(text: string, key: "tasks" | "pending"): Raw[] | undefined {
   try {
-    text = fs.readFileSync(file, "utf8");
+    const list = (JSON.parse(text) as Raw | null)?.[key];
+    if (!Array.isArray(list)) return undefined;
+    return list.filter((x): x is Raw => !!x && typeof x === "object" && !Array.isArray(x));
   } catch {
-    return [];
+    return undefined;
   }
+}
+
+/**
+ * Reads a `{ version, <key>: [...] }` file. Missing = empty. A damaged file is renamed `*.corrupt-<ts>`; if its `.bak`
+ * (the last good version) is valid it is restored, else the list starts empty.
+ */
+function readList(file: string, key: "tasks" | "pending"): Raw[] {
+  const read = readWithBackup(file, (t) => parseList(t, key) !== undefined);
+  if (!read) return [];
+  const list = parseList(read.text, key);
+  if (list && !read.fromBackup) return list;
+  const moved = `${file}.corrupt-${Date.now()}`;
   try {
-    const list = (JSON.parse(text) as Raw | null)?.[key];
-    if (!Array.isArray(list)) throw new Error(`"${key}" is not an array`);
-    return list.filter((x): x is Raw => !!x && typeof x === "object" && !Array.isArray(x));
+    fs.renameSync(file, moved);
   } catch {
-    const moved = `${file}.corrupt-${Date.now()}`;
+    // why: quarantine is best-effort; the file is ignored either way.
+  }
+  if (list) {
     try {
-      fs.renameSync(file, moved);
+      writeFileDurable(file, read.text, { backup: false }); // keep the good .bak where it is
     } catch {
-      // why: quarantine is best-effort; the file is ignored either way.
+      // why: the backup content is still returned for this read.
     }
-    telemetryBus.emitWarning(
-      "scheduled_action.store_corrupt",
-      `[Agent Accelerator] ${path.basename(file)} is not valid; moved to ${path.basename(moved)} and starting empty.`,
-      { file: moved }
-    );
-    return [];
   }
+  telemetryBus.emitWarning(
+    "scheduled_action.store_corrupt",
+    `[Agent Accelerator] ${path.basename(file)} is not valid; moved to ${path.basename(moved)} and ${list ? "restored from its backup" : "starting empty"}.`,
+    { file: moved, restored: !!list }
+  );
+  return list ?? [];
 }
 
 function writeList(file: string, key: "tasks" | "pending", list: Raw[]): void {
-  writeFileAtomic(file, JSON.stringify({ version: 1, [key]: list }, null, 2) + "\n");
+  writeFileDurable(file, JSON.stringify({ version: 1, [key]: list }, null, 2) + "\n");
 }
 
 /** Every record as stored. Records may be invalid: check with {@link validateRecord} before acting on one. */
@@ -212,7 +225,7 @@ export function writeRunFile(home: string, id: string, deliverAt: Date, header:
   const base = runFileName(deliverAt);
   let name = `${base}.md`;
   for (let n = 2; fs.existsSync(path.join(dir, name)); n++) name = `${base}-${n}.md`;
-  writeFileAtomic(path.join(dir, name), renderRun(header, body));
+  writeFileDurable(path.join(dir, name), renderRun(header, body), { backup: false }); // written once, never rewritten
   return `${id}/${name}`;
 }
 

package/src/session/journal.ts

@@ -0,0 +1,201 @@
+/**
+ * Append-only step log for a persisted session (dir mode). `session.json` stays the snapshot; every step after it
+ * adds ONE short line to `journal.ndjson` instead of rewriting the whole file, so a long chat costs the same per step
+ * as a short one. When history changes any other way (rollback, repair, reset, import) or the journal grows past a
+ * limit, a fresh snapshot replaces both. The snapshot carries an `epoch` id and the journal header repeats it, so a
+ * journal left over from before a snapshot is ignored on load (see `replayJournal` in `store.ts`).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import type { Message, ContentPart } from "../types/message.ts";
+import { writeFileDurable } from "../utils/durable.ts";
+import {
+  JOURNAL_FILE,
+  buildSessionData,
+  embeddedMedia,
+  quarantineIfCorrupt,
+  serializeSession,
+  stripRedundantRawArguments,
+  type SessionAgentLike,
+  type SessionPending,
+  type SessionPendingPrompt,
+  type SessionToolRecord,
+} from "./store.ts";
+
+/** A journal past this many lines is folded into a fresh snapshot. */
+const MAX_JOURNAL_LINES = 500;
+/** A journal past this many bytes is folded into a fresh snapshot. */
+const MAX_JOURNAL_BYTES = 4 * 1024 * 1024;
+
+const EMPTY_PENDING = JSON.stringify({ steer: [], queue: [] });
+
+// One `tool` journal line; the result is saved as given (tool results are JSON-safe by the time the executor returns them); in: a finished tool call, out: the journal.
+function toolLine(t: SessionToolRecord): string {
+  return JSON.stringify({ t: "tool", call: t.id, name: t.name, result: t.result, ...(t.isError ? { isError: true } : {}), ...(t.stopped ? { stopped: true } : {}) });
+}
+
+/** Persists one session folder (`sessions/<id>/`) step by step. */
+export class SessionJournal {
+  /** Epoch of the snapshot the journal belongs to; unset until the first snapshot (and after a failed append). */
+  private epoch: string | undefined;
+  /** How many messages are on disk, and the last one (identity check: history only grew since the last sync). */
+  private count = 0;
+  private last: Message | undefined;
+  private lines = 0;
+  private bytes = 0;
+  /** JSON of the last written non-message state (config, system prompt, worker traces). */
+  private meta = "";
+  /** How many run marks are on disk, and the last one. */
+  private runCount = 0;
+  private lastRun: unknown;
+  /** JSON of the last journaled waiting prompts. */
+  private pending = EMPTY_PENDING;
+  /** Run ids whose ending is on disk. */
+  private readonly endsOnDisk = new Set<string>();
+  /** How many of the current run's finished tool results are on disk, and the last one. */
+  private toolCount = 0;
+  private lastTool: unknown;
+  /** Disk form of each message already prepared (media replaced by `media/` files, redundant raw arguments dropped). */
+  private readonly onDisk = new WeakMap<Message, Message>();
+  /** Same for waiting prompts made of content parts. */
+  private readonly promptOnDisk = new WeakMap<ContentPart[], ContentPart[]>();
+
+  constructor(readonly dir: string) {}
+
+  // Brings the folder up to date with the agent: appends new messages and changed state, or writes a fresh snapshot when history changed another way; in: Agent.doPersist after every step, out: files in this.dir.
+  sync(agent: SessionAgentLike): void {
+    const messages = agent.context.messages;
+    const runs = agent.runMarks ?? [];
+    const grew =
+      this.epoch !== undefined &&
+      messages.length >= this.count &&
+      (this.count === 0 || messages[this.count - 1] === this.last) &&
+      runs.length >= this.runCount &&
+      (this.runCount === 0 || runs[this.runCount - 1] === this.lastRun);
+    if (!grew) {
+      this.snapshot(agent);
+      return;
+    }
+    const records: string[] = [];
+    for (let i = this.count; i < messages.length; i++) records.push(JSON.stringify({ t: "msg", i, m: this.toDisk(messages[i]!) }));
+    for (let r = this.runCount; r < runs.length; r++) records.push(JSON.stringify({ t: "run", id: runs[r]!.id, i: runs[r]!.i, at: runs[r]!.at }));
+    for (const mark of runs) {
+      if (mark.end && !this.endsOnDisk.has(mark.id)) records.push(JSON.stringify({ t: "end", id: mark.id, status: mark.end }));
+    }
+    const tools = agent.toolRecords ?? [];
+    const firstNewTool = this.toolCount > 0 && tools[this.toolCount - 1] === this.lastTool ? this.toolCount : 0; // a new run starts the list over
+    for (let k = firstNewTool; k < tools.length; k++) records.push(toolLine(tools[k]!));
+    const meta = this.metaOf(agent);
+    if (meta !== this.meta) records.push(`{"t":"meta","m":${meta}}`);
+    const pending = this.pendingOf(agent);
+    if (pending !== this.pending) records.push(`{"t":"pending","p":${pending}}`);
+    if (records.length === 0) return;
+    const text = records.join("\n") + "\n";
+    try {
+      const fd = fs.openSync(path.join(this.dir, JOURNAL_FILE), "a", 0o600);
+      try {
+        fs.writeFileSync(fd, text);
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch (err) {
+      this.epoch = undefined; // a half-written line may be on disk: the next sync starts over with a snapshot
+      throw err;
+    }
+    this.count = messages.length;
+    this.last = messages[messages.length - 1];
+    this.meta = meta;
+    this.runCount = runs.length;
+    this.lastRun = runs[runs.length - 1];
+    this.pending = pending;
+    this.toolCount = tools.length;
+    this.lastTool = tools[tools.length - 1];
+    for (const mark of runs) if (mark.end) this.endsOnDisk.add(mark.id);
+    this.lines += records.length;
+    this.bytes += text.length;
+    if (this.lines >= MAX_JOURNAL_LINES || this.bytes >= MAX_JOURNAL_BYTES) this.snapshot(agent);
+  }
+
+  // Writes `session.json` (new epoch) and then restarts the journal under that epoch; a crash in between leaves a journal with the old epoch, which load ignores; in: sync, out: both files.
+  private snapshot(agent: SessionAgentLike): void {
+    const messages = agent.context.messages;
+    const epoch = randomUUID();
+    const target = path.join(this.dir, "session.json");
+    if (this.epoch === undefined) quarantineIfCorrupt(target);
+    const data = buildSessionData({ ...agent, context: { ...agent.context, messages: messages.map((m) => this.toDisk(m)) } }, null);
+    writeFileDurable(target, serializeSession({ ...data, epoch }) + "\n");
+    const pending = this.pendingOf(agent);
+    const tools = agent.toolRecords ?? [];
+    // Waiting prompts and the current run's finished tool results live only in the journal, so a new journal starts with them.
+    const header =
+      JSON.stringify({ t: "base", e: epoch }) + "\n" + (pending === EMPTY_PENDING ? "" : `{"t":"pending","p":${pending}}\n`) + tools.map((t) => toolLine(t) + "\n").join("");
+    writeFileDurable(path.join(this.dir, JOURNAL_FILE), header, { backup: false });
+    this.epoch = epoch;
+    this.pending = pending;
+    this.runs(agent);
+    this.count = messages.length;
+    this.last = messages[messages.length - 1];
+    this.lines = (pending === EMPTY_PENDING ? 0 : 1) + tools.length;
+    this.toolCount = tools.length;
+    this.lastTool = tools[tools.length - 1];
+    this.endsOnDisk.clear();
+    for (const mark of agent.runMarks ?? []) if (mark.end) this.endsOnDisk.add(mark.id); // the snapshot holds them
+    this.bytes = 0;
+    this.meta = this.metaOf(agent);
+  }
+
+  // Remembers which run marks the snapshot already holds; in: snapshot, out: the next sync's "which marks are new".
+  private runs(agent: SessionAgentLike): void {
+    const runs = agent.runMarks ?? [];
+    this.runCount = runs.length;
+    this.lastRun = runs[runs.length - 1];
+  }
+
+  // JSON of the waiting prompts with media moved to files; in: the agent's steer inbox + follow-up queue, out: change detection + the `pending` record.
+  private pendingOf(agent: SessionAgentLike): string {
+    const waiting = agent.pendingPrompts?.();
+    if (!waiting || waiting.steer.length + waiting.queue.length === 0) return EMPTY_PENDING;
+    const parts = (prompt: ContentPart[]): ContentPart[] => {
+      let disk = this.promptOnDisk.get(prompt);
+      if (!disk) this.promptOnDisk.set(prompt, (disk = this.toDisk({ role: "user", content: prompt }).content as ContentPart[]));
+      return disk;
+    };
+    const slim = (list: SessionPendingPrompt[]): SessionPendingPrompt[] =>
+      list.map((w) => ({ ...w, prompt: typeof w.prompt === "string" ? w.prompt : parts(w.prompt) }));
+    return JSON.stringify({ steer: slim(waiting.steer), queue: slim(waiting.queue) } satisfies SessionPending);
+  }
+
+  // JSON of everything in the snapshot that is not a message, identity or totals; in: the live agent, out: change detection + the `meta` record.
+  private metaOf(agent: SessionAgentLike): string {
+    const { version: _v, sessionId: _s, messages: _m, totals: _t, runs: _r, ...rest } = buildSessionData(
+      { ...agent, context: { ...agent.context, messages: [] } },
+      null
+    );
+    return JSON.stringify(rest);
+  }
+
+  // The form of a message that goes to disk: embedded media written once as `media/<kind>-h<hash>.<ext>` (content-addressed, never deleted or renumbered), redundant raw arguments dropped; in: a live message, out: journal lines and snapshots.
+  private toDisk(message: Message): Message {
+    const known = this.onDisk.get(message);
+    if (known) return known;
+    const slim = stripRedundantRawArguments([message])[0]!;
+    let out = slim;
+    if (Array.isArray(slim.content)) {
+      let changed = false;
+      const content = (slim.content as ContentPart[]).map((part) => {
+        const found = embeddedMedia(part);
+        if (!found) return part;
+        const file = `${found.key}-h${createHash("sha256").update(found.bytes).digest("hex").slice(0, 16)}.${found.ext}`;
+        const dest = path.join(this.dir, "media", file);
+        if (!fs.existsSync(dest)) writeFileDurable(dest, found.bytes, { backup: false });
+        changed = true;
+        return { ...(part as unknown as Record<string, unknown>), [found.key]: `media/${file}`, ...(found.mimeType ? { mimeType: found.mimeType } : {}) } as unknown as ContentPart;
+      });
+      if (changed) out = { ...slim, content };
+    }
+    this.onDisk.set(message, out);
+    return out;
+  }
+}