agent-accelerator 0.5.2 → 0.5.4

package/src/session/journal.ts

@@ -0,0 +1,212 @@
+/**
+ * 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;
+  /** JSON of the last journaled spending totals. */
+  private usage = "";
+  /** 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}}`);
+    const usage = this.usageOf(agent);
+    if (usage !== this.usage) records.push(`{"t":"usage","u":${usage}}`);
+    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.usage = usage;
+    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.usage = this.usageOf(agent); // the snapshot holds it
+    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 the agent's spending totals (`null` before its first model call); in: the live agent, out: change detection + the `usage` record.
+  private usageOf(agent: SessionAgentLike): string {
+    return agent.usageTotals && agent.usageTotals.turns > 0 ? JSON.stringify(agent.usageTotals) : "null";
+  }
+
+  // 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, usage: _u, ...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;
+  }
+}

package/src/session/store.ts

@@ -32,6 +32,8 @@ import { getModelFromCatalog } from "../models/catalog.ts";
 import type { SubAgentStep } from "../types/response.ts";
 import { SessionLoadError } from "../types/errors.ts";
 import { createSessionId } from "../utils/session.ts";
+import { writeFileDurable, readWithBackup } from "../utils/durable.ts";
+import type { UsageTotals } from "./usage.ts";
 
 /** Cumulative per-session token + cost totals (JSON-safe). */
 export interface SessionTotals {
@@ -61,6 +63,40 @@ export interface PersistedSubAgentTrace {
   error?: string;
 }
 
+/** How a run ended; a run with no ending was cut off (a crash). `abandoned` = a newer run started instead of resuming it. */
+export type SessionRunEnd = "done" | "failed" | "aborted" | "stopped" | "abandoned";
+
+/** Where one run began: `i` is the index of its user message in `messages` (turn boundaries for later phases). */
+export interface SessionRunMark {
+  id: string;
+  i: number;
+  at: number;
+  /** Unset while the run is active or when it was cut off. */
+  end?: SessionRunEnd;
+}
+
+/** The result of a tool call that finished, saved the moment it finished so a crash never repeats it. */
+export interface SessionToolRecord {
+  id: string;
+  name: string;
+  result: unknown;
+  isError?: boolean;
+  /** The tool ended the run with `ctx.stop`. */
+  stopped?: boolean;
+}
+
+/** A prompt that was waiting when the process stopped (its options other than `additionalContext` are not saved). */
+export interface SessionPendingPrompt {
+  prompt: string | ContentPart[];
+  additionalContext?: string;
+}
+
+/** Steers not yet injected into the active run, and queued follow-ups, as last journaled. */
+export interface SessionPending {
+  steer: SessionPendingPrompt[];
+  queue: SessionPendingPrompt[];
+}
+
 /** Single-file session snapshot (v1). Written as one JSON object. */
 export interface PersistedAgentSession {
   version: 1;
@@ -79,6 +115,16 @@ export interface PersistedAgentSession {
   parentSessionId?: string;
   /** Dedicated sub-agent traces, keyed by worker TrackingID (32-char hex). */
   subagents?: Record<string, PersistedSubAgentTrace>;
+  /** Written with a journal (dir mode): only a `journal.ndjson` whose header names this id belongs to this snapshot. */
+  epoch?: string;
+  /** Where each run began, oldest first. */
+  runs?: SessionRunMark[];
+  /** What this agent spent on its own model calls (see `usage.ts`); the journal keeps it current with `usage` records. */
+  usage?: UsageTotals;
+  /** Read from the journal only (never in `session.json`): prompts that were still waiting. */
+  pending?: SessionPending;
+  /** Read from the journal only: results of tool calls finished in the current run (used to resume without repeating them). */
+  tools?: SessionToolRecord[];
 }
 
 export function emptyTotals(): SessionTotals {
@@ -286,6 +332,14 @@ export interface SessionAgentLike {
   instructions?: string;
   parentSessionId?: unknown;
   subagentTraces?: Record<string, PersistedSubAgentTrace>;
+  /** Run boundaries (see {@link SessionRunMark}). */
+  runMarks?: SessionRunMark[];
+  /** Prompts waiting in the steer inbox / follow-up queue; called by the journal on every sync. */
+  pendingPrompts?: () => SessionPending;
+  /** Tool calls finished in the current run (cleared when the next run starts). */
+  toolRecords?: SessionToolRecord[];
+  /** What this agent spent on its own model calls. */
+  usageTotals?: UsageTotals;
   context: { systemPrompt?: string; messages: Message[] };
 }
 
@@ -354,7 +408,7 @@ function stableStringify(value: unknown): string {
  * stored `arguments` (pure duplicate, the common case). Divergent or
  * unparseable wire strings are kept — they carry info parsing lost.
  */
-function stripRedundantRawArguments(messages: Message[]): Message[] {
+export function stripRedundantRawArguments(messages: Message[]): Message[] {
   return messages.map((m) => {
     if (!Array.isArray((m as Message).content)) return m;
     let changed = false;
@@ -432,6 +486,8 @@ export function buildSessionData(agent: SessionAgentLike, telemetry?: SessionTel
     messages,
     ...(parentSessionId ? { parentSessionId } : {}),
     ...(subagents ? { subagents } : {}),
+    ...(agent.runMarks && agent.runMarks.length > 0 ? { runs: agent.runMarks.map((r) => ({ ...r })) } : {}),
+    ...(agent.usageTotals && agent.usageTotals.turns > 0 ? { usage: JSON.parse(JSON.stringify(agent.usageTotals)) as UsageTotals } : {}),
   };
 }
 
@@ -619,6 +675,9 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
       totals: obj.totals,
       parentSessionId: obj.parentSessionId,
       subagents: obj.subagents,
+      ...(typeof obj.epoch === "string" ? { epoch: obj.epoch } : {}),
+      ...(Array.isArray(obj.runs) ? { runs: obj.runs as SessionRunMark[] } : {}),
+      ...(obj.usage && typeof obj.usage === "object" ? { usage: obj.usage as UsageTotals } : {}),
     };
   } catch {
     return null;
@@ -654,14 +713,14 @@ export function inspectSessionPayload(
 /** Loads a session file (pretty `.json` or legacy `.jsonl`). Returns null when missing/corrupt. */
 export function loadSessionFile(filePath: string, limits?: SessionLimits): PersistedAgentSession | null {
   const resolved = path.resolve(filePath);
-  let raw: string;
-  try {
-    if (!fs.existsSync(resolved)) return null;
-    raw = fs.readFileSync(resolved, "utf8");
-  } catch {
-    return null;
-  }
-  return sessionFromPayload(raw, resolved, limits);
+  const read = readWithBackup(resolved, isLoadableSession);
+  return read ? sessionFromPayload(read.text, resolved, limits) : null;
+}
+
+// True when a stored payload is a usable snapshot (a valid one over the load limits counts); in: raw file text, out: readWithBackup's fallback decision.
+function isLoadableSession(raw: string): boolean {
+  const status = inspectSessionPayload(raw).status;
+  return status === "ok" || status === "over_limit";
 }
 
 /**
@@ -680,25 +739,8 @@ function sessionFromPayload(raw: string, file: string, limits?: SessionLimits):
   return res.session ?? null;
 }
 
-/** Atomic file write (temp + rename) so a crash never leaves half-written JSON. */
-export function writeFileAtomic(filePath: string, content: string): void {
-  const dir = path.dirname(filePath);
-  try {
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  } catch {}
-  let tag = "tmp";
-  try {
-    const pid = (globalThis as any)?.process?.pid;
-    const rand = (globalThis as any)?.crypto?.randomUUID?.().slice(0, 8) ?? Math.random().toString(36).slice(2, 8);
-    tag = `${typeof pid === "number" ? pid : "np"}-${rand}`;
-  } catch {
-    tag = Math.random().toString(36).slice(2, 8);
-  }
-  const tmp = `${filePath}.tmp-${tag}`;
-  fs.writeFileSync(tmp, content, { encoding: "utf8", mode: 0o600 });
-  try { fs.chmodSync(tmp, 0o600); } catch {}
-  fs.renameSync(tmp, filePath);
-}
+/** Public name of the durable writer (temp file, fsync, `.bak`, atomic rename): a crash or power cut never leaves half-written JSON. */
+export const writeFileAtomic = writeFileDurable;
 
 /** Session id grammar: no traversal, no slashes, no hidden files. */
 export function assertValidSessionId(sessionId: string): void {
@@ -707,6 +749,15 @@ export function assertValidSessionId(sessionId: string): void {
   }
 }
 
+/** Renames a genuinely corrupt snapshot to `*.corrupt-<ts>` before it is overwritten (a healthy one over the load limits is our own prior save and is just rewritten). */
+export function quarantineIfCorrupt(file: string): void {
+  try {
+    if (inspectSessionPayload(fs.readFileSync(file, "utf8")).status === "corrupt") fs.renameSync(file, `${file}.corrupt-${Date.now()}`);
+  } catch {
+    // why: no file yet, or it cannot be read: nothing to quarantine.
+  }
+}
+
 /** Saves an agent + telemetry snapshot as a pretty-printed `.json` document (2-space indent). */
 export function saveSessionFile(
   filePath: string,
@@ -714,20 +765,7 @@ export function saveSessionFile(
   telemetry?: SessionTelemetry | SessionTotals | null
 ): void {
   const resolved = path.resolve(filePath);
-  // Q-28-partial: never overwrite a corrupt file in place — quarantine it
-  // as `*.corrupt-<ts>` first (load returns null for corrupt payloads).
-  try {
-    if (fs.existsSync(resolved)) {
-      try {
-        const raw = fs.readFileSync(resolved, "utf8");
-        // Only genuinely corrupt payloads are quarantined; a healthy snapshot
-        // over the load limits is simply rewritten (it is our own prior save).
-        if (inspectSessionPayload(raw).status === "corrupt") {
-          try { fs.renameSync(resolved, `${resolved}.corrupt-${Date.now()}`); } catch {}
-        }
-      } catch {}
-    }
-  } catch {}
+  quarantineIfCorrupt(resolved);
   const data = buildSessionData(agent, telemetry);
   try {
     writeFileAtomic(resolved, serializeSession(data) + "\n");
@@ -790,6 +828,28 @@ function extForMedia(mimeType?: string, filename?: string): string {
   return "bin";
 }
 
+// Finds embedded media bytes in a part (binary, `data:` URL or raw base64); remote URLs and local paths are references and give undefined; in: any content part, out: extractMediaToDir and the session journal.
+export function embeddedMedia(part: ContentPart): { key: (typeof MEDIA_PART_KEYS)[number]; bytes: Uint8Array; mimeType?: string; ext: string } | undefined {
+  const p = part as unknown as Record<string, unknown> | null;
+  if (!p || typeof p["type"] !== "string" || !(MEDIA_PART_KEYS as readonly string[]).includes(p["type"])) return undefined;
+  const key = p["type"] as (typeof MEDIA_PART_KEYS)[number];
+  const raw = p[key];
+  let bytes: Uint8Array;
+  let mimeType = typeof p["mimeType"] === "string" ? (p["mimeType"] as string) : undefined;
+  if (raw instanceof Uint8Array) bytes = raw;
+  else if (raw instanceof ArrayBuffer) bytes = new Uint8Array(raw);
+  else if (typeof raw === "string") {
+    if (isHttpRef(raw)) return undefined; // remote reference: the provider fetches it per turn
+    const dataUrl = raw.startsWith("data:") ? parseDataUrl(raw) : undefined;
+    if (dataUrl) {
+      bytes = base64ToBytes(dataUrl.base64);
+      mimeType = mimeType ?? dataUrl.mimeType;
+    } else if (looksLikeEmbeddedBase64(raw)) bytes = base64ToBytes(raw.replace(/\s/g, ""));
+    else return undefined; // local path or short label: keep as reference
+  } else return undefined;
+  return { key, bytes, ...(mimeType ? { mimeType } : {}), ext: extForMedia(mimeType, typeof p["filename"] === "string" ? (p["filename"] as string) : undefined) };
+}
+
 function cloneMessages(messages: Message[]): Message[] {
   try {
     const g: any = globalThis as any;
@@ -830,35 +890,15 @@ export function extractMediaToDir(
   } catch {}
   const wrote: string[] = [];
   const counters: Record<string, number> = {};
-  let hasBinary = false;
 
   for (const msg of cloned) {
     if (!Array.isArray((msg as Message).content)) continue;
     for (const part of (msg as Message).content as ContentPart[]) {
-      const p: any = part as any;
-      if (!p || typeof p.type !== "string") continue;
-      if (!(MEDIA_PART_KEYS as readonly string[]).includes(p.type)) continue;
-      const key = p.type as (typeof MEDIA_PART_KEYS)[number];
-      const raw = p[key] as unknown;
-      let bytes: Uint8Array | undefined;
-      let mimeType: string | undefined = typeof p.mimeType === "string" ? p.mimeType : undefined;
-      if (raw instanceof Uint8Array) bytes = raw;
-      else if (raw instanceof ArrayBuffer) bytes = new Uint8Array(raw);
-      else if (typeof raw === "string") {
-        if (isHttpRef(raw)) continue; // remote reference — provider fetches per turn
-        const dataUrl = raw.startsWith("data:") ? parseDataUrl(raw) : undefined;
-        if (dataUrl) {
-          bytes = base64ToBytes(dataUrl.base64);
-          mimeType = mimeType ?? dataUrl.mimeType;
-        } else if (looksLikeEmbeddedBase64(raw)) {
-          bytes = base64ToBytes(raw.replace(/\s/g, ""));
-        } else continue; // local path or short label — keep as reference
-      } else continue;
-
-      hasBinary = true;
+      const found = embeddedMedia(part);
+      if (!found) continue;
+      const { key, bytes, mimeType } = found;
       const n = (counters[key] = (counters[key] ?? 0) + 1);
-      const ext = extForMedia(mimeType, typeof p.filename === "string" ? p.filename : undefined);
-      const file = `${key}-${String(n).padStart(3, "0")}.${ext}`;
+      const file = `${key}-${String(n).padStart(3, "0")}.${found.ext}`;
       try {
         fs.mkdirSync(mediaDir, { recursive: true, mode: 0o700 });
         const dest = path.resolve(mediaDir, file);
@@ -868,8 +908,9 @@ export function extractMediaToDir(
       } catch {
         continue;
       }
+      const p = part as unknown as Record<string, unknown>;
       p[key] = `media/${file}`;
-      if (mimeType) p.mimeType = mimeType;
+      if (mimeType) p["mimeType"] = mimeType;
       wrote.push(`media/${file}`);
     }
   }
@@ -937,17 +978,7 @@ export function saveSessionDir(
   );
   try {
     const target = path.join(sessionDir, "session.json");
-    // Q-28-partial: quarantine corrupt targets instead of overwriting.
-    try {
-      if (fs.existsSync(target)) {
-        try {
-          const raw = fs.readFileSync(target, "utf8");
-          if (inspectSessionPayload(raw).status === "corrupt") {
-            try { fs.renameSync(target, `${target}.corrupt-${Date.now()}`); } catch {}
-          }
-        } catch {}
-      }
-    } catch {}
+    quarantineIfCorrupt(target);
     writeFileAtomic(target, serializeSession(data) + "\n");
   } catch {
     // persistence must never crash a chat turn
@@ -955,6 +986,69 @@ export function saveSessionDir(
   return sessionDir;
 }
 
+/** Name of the append-only step log next to `session.json` (see `session/journal.ts`). */
+export const JOURNAL_FILE = "journal.ndjson";
+
+// Snapshot fields a `meta` journal record replaces (everything except messages, identity and totals).
+const JOURNAL_META_KEYS = ["model", "subagentModel", "thinkingLevel", "cache", "systemPrompt", "parentSessionId", "subagents"] as const;
+
+// Applies a journal to its snapshot: records of the snapshot's own epoch only, `msg` by index (already-present ones skipped), `run` adds a run boundary, `end` closes one, `usage` replaces the agent's spending totals, `tool` keeps a finished tool result, `pending` replaces the waiting prompts, `meta` replaces config fields, unknown record types ignored; a torn last line is dropped, damage earlier stops the replay with a bus warning; in: the parsed snapshot + journal text, out: loadSessionDir.
+function replayJournal(snapshot: PersistedAgentSession, text: string, file: string): PersistedAgentSession {
+  if (!snapshot.epoch) return snapshot;
+  const lines = text.split("\n");
+  const session: PersistedAgentSession = { ...snapshot, messages: [...snapshot.messages] };
+  let sawHeader = false;
+  const stop = (reason: string, line: number): void => {
+    telemetryBus.emitWarning("session.journal_corrupt", `[Agent Accelerator] ${path.basename(file)} line ${line + 1}: ${reason}; the rest of the journal is ignored.`, { file, line: line + 1 });
+  };
+  for (let k = 0; k < lines.length; k++) {
+    const line = lines[k]!.trim();
+    if (!line) continue;
+    let rec: { t?: unknown; e?: unknown; i?: unknown; m?: unknown; p?: unknown; id?: unknown; at?: unknown; u?: unknown; status?: unknown; call?: unknown; name?: unknown; result?: unknown; isError?: unknown; stopped?: unknown };
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      if (lines.slice(k + 1).some((l) => l.trim())) stop("not valid JSON", k); // a torn LAST line is just a cut-off write
+      break;
+    }
+    if (!sawHeader) {
+      sawHeader = true;
+      if (rec.t !== "base" || rec.e !== snapshot.epoch) return snapshot; // a journal from before this snapshot
+      continue;
+    }
+    if (rec.t === "msg" && typeof rec.i === "number") {
+      if (rec.i < session.messages.length) continue; // already in the snapshot
+      if (rec.i > session.messages.length || findInvalidMessage([rec.m]) !== -1) {
+        stop(rec.i > session.messages.length ? "a message is missing before this one" : "invalid message", k);
+        break;
+      }
+      session.messages.push(rec.m as Message);
+    } else if (rec.t === "run" && typeof rec.id === "string" && typeof rec.i === "number" && typeof rec.at === "number") {
+      if (!session.runs?.some((r) => r.id === rec.id)) session.runs = [...(session.runs ?? []), { id: rec.id, i: rec.i, at: rec.at }];
+    } else if (rec.t === "end" && typeof rec.id === "string" && typeof rec.status === "string") {
+      const mark = session.runs?.find((r) => r.id === rec.id);
+      if (mark) session.runs = session.runs!.map((r) => (r === mark ? { ...r, end: rec.status as SessionRunEnd } : r));
+    } else if (rec.t === "tool" && typeof rec.call === "string" && typeof rec.name === "string") {
+      session.tools = [...(session.tools ?? []).filter((x) => x.id !== rec.call), { id: rec.call, name: rec.name, result: rec.result, ...(rec.isError ? { isError: true } : {}), ...(rec.stopped ? { stopped: true } : {}) }];
+    } else if (rec.t === "usage" && rec.u && typeof rec.u === "object") {
+      session.usage = rec.u as UsageTotals; // latest record wins
+    } else if (rec.t === "pending" && rec.p && typeof rec.p === "object") {
+      const p = rec.p as SessionPending; // latest record wins
+      if (Array.isArray(p.steer) && Array.isArray(p.queue)) {
+        if (p.steer.length + p.queue.length > 0) session.pending = p;
+        else delete session.pending;
+      }
+    } else if (rec.t === "meta" && rec.m && typeof rec.m === "object") {
+      const meta = rec.m as Record<string, unknown>;
+      for (const key of JOURNAL_META_KEYS) {
+        if (key in meta) (session as unknown as Record<string, unknown>)[key] = meta[key];
+        else delete session[key];
+      }
+    }
+  }
+  return session;
+}
+
 /** A loaded session folder: snapshot (media paths resolved) + folder location. */
 export interface LoadedSessionDir {
   session: PersistedAgentSession;
@@ -985,9 +1079,17 @@ export function loadSessionDir(sessionPath: string, limits?: SessionLimits): Loa
       // path does not exist yet — fall through to session.json lookup
     }
     const file = path.join(dir, "session.json");
-    if (!fs.existsSync(file)) return null;
-    const data = sessionFromPayload(fs.readFileSync(file, "utf8"), file, limits);
-    if (!data) return null;
+    const read = readWithBackup(file, isLoadableSession);
+    if (!read) return null;
+    const snapshot = sessionFromPayload(read.text, file, limits);
+    if (!snapshot) return null;
+    let journal: string | undefined;
+    try {
+      journal = fs.readFileSync(path.join(dir, JOURNAL_FILE), "utf8");
+    } catch {
+      journal = undefined; // no journal: the snapshot is the whole session
+    }
+    const data = journal ? replayJournal(snapshot, journal, path.join(dir, JOURNAL_FILE)) : snapshot;
     data.messages = resolveMediaPaths(data.messages, dir);
     return { session: data, dir };
   } catch (err) {
@@ -1007,7 +1109,13 @@ export function findLatestSessionDir(rootDir: string): string | null {
       try {
         const st = fs.statSync(file);
         if (!st.isFile()) continue;
-        if (!best || st.mtimeMs > best.mtime) best = { dir: path.join(root, entry), mtime: st.mtimeMs };
+        let mtime = st.mtimeMs;
+        try {
+          mtime = Math.max(mtime, fs.statSync(path.join(root, entry, JOURNAL_FILE)).mtimeMs); // steps land in the journal
+        } catch {
+          // why: no journal yet.
+        }
+        if (!best || mtime > best.mtime) best = { dir: path.join(root, entry), mtime };
       } catch {
         continue;
       }
@@ -1229,15 +1337,16 @@ function toDollars(microUSD: number): number {
  * `cost.context_over_200k`, the over-200k tier prices apply; otherwise base
  * `pricing.*` (falling back to legacy `cost.*`) applies.
  */
+// Cache prices stay undefined when the catalog has none: priceUsage then bills those tokens at the input rate (never free).
 function resolveEffectivePricing(
   spec: ModelSpec | undefined,
   inputTokens: number
-): { input: number; output: number; cacheRead: number; cacheWrite: number; audio: number; tier: string } {
+): { input: number; output: number; cacheRead: number | undefined; cacheWrite: number | undefined; audio: number; tier: string } {
   const base = {
     input: spec?.pricing?.inputPerMillion ?? (spec?.cost?.input as number | undefined) ?? 0,
     output: spec?.pricing?.outputPerMillion ?? (spec?.cost?.output as number | undefined) ?? 0,
-    cacheRead: spec?.pricing?.cacheReadPerMillion ?? (spec?.cost?.cache_read as number | undefined) ?? 0,
-    cacheWrite: spec?.pricing?.cacheWritePerMillion ?? (spec?.cost?.cache_write as number | undefined) ?? 0,
+    cacheRead: spec?.pricing?.cacheReadPerMillion ?? (spec?.cost?.cache_read as number | undefined),
+    cacheWrite: spec?.pricing?.cacheWritePerMillion ?? (spec?.cost?.cache_write as number | undefined),
     audio:
       spec?.pricing?.inputAudioPerMillion ?? (spec?.cost as { input_audio?: number } | undefined)?.input_audio ?? 0,
   };
@@ -1289,8 +1398,9 @@ function resolveEffectivePricing(
  * - Audio tokens (`usage.audioTokens` / `usage.inputAudioTokens` when present)
  *   price at `pricing.inputAudioPerMillion` / `cost.input_audio` and fold into
  *   the total (separately itemized in `breakdown.audioMicroUSD`).
- * - `opts.serviceTier` (`flex` ~0.5x, `priority` ~1.5x, estimates) scales the
+ * - `opts.serviceTier` (`flex` 0.5x, `priority` 2x, estimates) scales the
  *   catalog total; provider-reported costs are never rescaled.
+ * - Cache reads and writes are subsets of the input tokens; a missing cache price bills at the input rate.
  */
 export function priceUsage(
   usage: TokenUsage,
@@ -1339,12 +1449,15 @@ export function priceUsage(
     return undefined;
   }
   const { multiplier, tier: serviceTier } = serviceTierMultiplier(opts?.serviceTier, opts?.modelId ?? spec?.id);
-  const nonCachedInput = Math.max(0, inputTokens - cachedTokens);
+  // Cache reads and writes are both a SUBSET of the input tokens (OpenRouter `prompt_tokens` includes them), so the
+  // plain input rate applies only to what is neither read from nor written to the cache.
+  const freshInput = Math.max(0, inputTokens - cachedTokens - cacheWriteTokens);
   // Integer micro-USD accumulation: microUSD = tokens * pricePerMillion
   // ($P per 1M tokens == $P/1e6 per token == P micro-USD per token).
-  const inputMicroUSD = Math.round(nonCachedInput * pricing.input * multiplier);
-  const cacheReadMicroUSD = Math.round(cachedTokens * pricing.cacheRead * multiplier);
-  const cacheWriteMicroUSD = Math.round(cacheWriteTokens * pricing.cacheWrite * multiplier);
+  // A catalog entry without a cache price bills those tokens at the input rate: cache reads/writes are never free.
+  const inputMicroUSD = Math.round(freshInput * pricing.input * multiplier);
+  const cacheReadMicroUSD = Math.round(cachedTokens * (pricing.cacheRead ?? pricing.input) * multiplier);
+  const cacheWriteMicroUSD = Math.round(cacheWriteTokens * (pricing.cacheWrite ?? pricing.input) * multiplier);
   const outputMicroUSD = Math.round(outputTokens * pricing.output * multiplier);
   const audioMicroUSD = Math.round(audioCount * pricing.audio * multiplier);
   const totalMicroUSD = inputMicroUSD + cacheReadMicroUSD + cacheWriteMicroUSD + outputMicroUSD + audioMicroUSD;