muonroi-cli 1.2.2 → 1.3.1

package/src/storage/db.ts

@@ -1,4 +1,4 @@
-import { Database } from "bun:sqlite";
+import { createRequire } from "node:module";
 import fs from "fs";
 import os from "os";
 import path from "path";
@@ -20,16 +20,52 @@ export interface SQLiteDatabase {
 
 let db: SQLiteDatabase | null = null;
 
+// Sync-loadable require for runtime driver selection. We need sync because
+// getDatabase() is sync and propagates through ~50 call sites; making it
+// async would be a much larger refactor.
+const requireSync = createRequire(import.meta.url);
+
 export function getDatabasePath(): string {
   const dir = path.join(os.homedir(), ".muonroi-cli");
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   return path.join(dir, "muonroi.db");
 }
 
+/**
+ * Pick the SQLite driver at runtime so the same bundle runs on both Bun and
+ * bare Node:
+ *   - Bun ≥ 1.x exposes `bun:sqlite` as a built-in.
+ *   - Node falls back to `better-sqlite3` (npm pkg with prebuilt binaries).
+ * Loaded lazily — neither module is touched until the first DB call.
+ */
+function loadDriver(filename: string): SQLiteDatabase {
+  const isBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+  if (isBun) {
+    try {
+      const { Database } = requireSync("bun:sqlite") as {
+        Database: new (file: string, opts?: { create?: boolean; strict?: boolean }) => import("bun:sqlite").Database;
+      };
+      return new BunSqliteDatabase(filename, Database);
+    } catch {
+      /* fall through to better-sqlite3 */
+    }
+  }
+  try {
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic driver shape
+    const BetterSqlite3 = requireSync("better-sqlite3") as any;
+    return new BetterSqlite3Database(filename, BetterSqlite3);
+  } catch (e) {
+    throw new Error(
+      "No SQLite driver available. Install better-sqlite3 (npm) or run muonroi-cli under Bun.\n" +
+        `Underlying error: ${(e as Error).message}`,
+    );
+  }
+}
+
 export function getDatabase(): SQLiteDatabase {
   if (db) return db;
 
-  const database = new BunSqliteDatabase(getDatabasePath());
+  const database = loadDriver(getDatabasePath());
   database.pragma("journal_mode = WAL");
   database.pragma("foreign_keys = ON");
   database.pragma("busy_timeout = 5000");
@@ -49,10 +85,16 @@ export function closeDatabase(): void {
   db = null;
 }
 
+// biome-ignore lint/suspicious/noExplicitAny: shape varies per driver
+type BunDatabaseCtor = new (file: string, opts?: { create?: boolean; strict?: boolean }) => any;
+// biome-ignore lint/suspicious/noExplicitAny: shape varies per driver
+type BetterSqlite3Ctor = new (file: string) => any;
+
 class BunSqliteDatabase implements SQLiteDatabase {
-  private readonly db: Database;
+  // biome-ignore lint/suspicious/noExplicitAny: bun:sqlite driver instance
+  private readonly db: any;
 
-  constructor(filename: string) {
+  constructor(filename: string, Database: BunDatabaseCtor) {
     this.db = new Database(filename, { create: true, strict: true });
   }
 
@@ -89,7 +131,54 @@ class BunSqliteDatabase implements SQLiteDatabase {
   }
 }
 
+/**
+ * better-sqlite3 adapter — used when running on bare Node.
+ * API note: better-sqlite3 puts run/get/all on the Statement (returned by
+ * .prepare()), not on the DB. .pragma() is built-in. Otherwise compatible.
+ */
+class BetterSqlite3Database implements SQLiteDatabase {
+  // biome-ignore lint/suspicious/noExplicitAny: better-sqlite3 driver instance
+  private readonly db: any;
+
+  constructor(filename: string, BetterSqlite3: BetterSqlite3Ctor) {
+    this.db = new BetterSqlite3(filename);
+  }
+
+  exec(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  prepare(sql: string): SQLiteStatement {
+    const stmt = this.db.prepare(sql);
+    return {
+      run: (...params: unknown[]) => stmt.run(...spreadBinding(params)),
+      get: (...params: unknown[]) => stmt.get(...spreadBinding(params)),
+      all: (...params: unknown[]) => stmt.all(...spreadBinding(params)),
+    };
+  }
+
+  pragma(query: string, options?: { simple?: boolean }): unknown {
+    return this.db.pragma(query, { simple: !!options?.simple });
+  }
+
+  transaction<T>(fn: () => T): () => T {
+    return this.db.transaction(fn);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+// Bun's .run(sql, X) takes a single value or an object; better-sqlite3 spreads
+// positional bindings. Normalize the inbound `params` array for each driver.
 function normalizeBinding(params: unknown[]): unknown {
   if (params.length === 0) return undefined;
   return params.length === 1 ? params[0] : params;
 }
+
+function spreadBinding(params: unknown[]): unknown[] {
+  // If the caller passed a single object/array as the only arg, treat as
+  // named/positional bindings respectively (better-sqlite3 accepts both).
+  return params;
+}

package/src/storage/index.ts

@@ -1,7 +1,8 @@
 // Muonroi-specific storage: cap state (atomic IO, config, usage)
-export { atomicReadJSON, atomicWriteJSON } from "./atomic-io.js";
+export { atomicReadJSON, atomicWriteJSON, sweepStaleAtomicTemps } from "./atomic-io.js";
 export { loadConfig, type MuonroiConfig } from "./config.js";
 export { getDatabasePath } from "./db";
+export { type InteractionEventType, logInteraction } from "./interaction-log.js";
 export { SessionStore } from "./sessions";
 export {
   appendCompaction,
@@ -13,7 +14,13 @@ export {
   loadRawTranscript,
   loadTranscript,
   loadTranscriptState,
+  markMessageCompleted,
+  markMessageErrored,
+  markToolCallErrored,
+  persistMessageWriteAhead,
+  persistToolCallWriteAhead,
 } from "./transcript";
 export { buildEffectiveTranscript, type LoadedTranscriptState, type PersistedCompaction } from "./transcript-view";
+export { logUIInteraction, type UIInteractionSubtype } from "./ui-interaction-log.js";
 export { getSessionTotalTokens, listSessionUsage, recordUsageEvent, type TokenUsageLike } from "./usage";
 export { loadUsage, saveUsage, type UsageState } from "./usage-cap.js";

package/src/storage/interaction-log.ts

@@ -0,0 +1,121 @@
+/**
+ * src/storage/interaction-log.ts
+ *
+ * Fire-and-forget interaction logging for detailed user-agent event tracking.
+ * All calls are fail-open — logging never breaks the main flow.
+ */
+
+import { getDatabase } from "./db.js";
+
+export type InteractionEventType =
+  | "user_message"
+  | "agent_response"
+  | "tool_call"
+  | "tool_result"
+  | "compaction"
+  | "routing"
+  | "pil"
+  | "error"
+  | "model_switch"
+  | "council"
+  | "ee_intercept"
+  | "ee_judge"
+  | "ee_injection"
+  | "ui_interaction"
+  | "stream_retry";
+
+// Retention: keep ~14 days of detail logs. Override via env if a workspace
+// needs longer history (e.g. forensic post-mortems).
+const RETENTION_DAYS = (() => {
+  const raw = Number(process.env.MUONROI_INTERACTION_LOG_RETENTION_DAYS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 14;
+})();
+// Probabilistic prune: ~1 in 200 inserts triggers a delete sweep. With ~3-5
+// log writes per turn this lands roughly every 40-70 user turns — frequent
+// enough to keep the table bounded, cheap enough not to hurt hot path.
+const PRUNE_PROBABILITY = 1 / 200;
+let _pruneInflight = false;
+
+function maybePruneOld(): void {
+  if (_pruneInflight) return;
+  if (Math.random() >= PRUNE_PROBABILITY) return;
+  _pruneInflight = true;
+  try {
+    const cutoff = new Date(Date.now() - RETENTION_DAYS * 86_400_000).toISOString();
+    getDatabase().prepare(`DELETE FROM interaction_logs WHERE created_at < ?`).run(cutoff);
+  } catch {
+    // Fail-open
+  } finally {
+    _pruneInflight = false;
+  }
+}
+
+export interface EEInjectionRow {
+  session_id: string;
+  event_subtype: string | null;
+  duration_ms: number | null;
+  metadata_json: string | null;
+  created_at: string;
+}
+
+/**
+ * Query ee_injection rows for a specific run (session_id = runId).
+ * Returns both PIL Layer 3 injection rows (event_subtype IS NULL or "injected"/"no_match"/"filtered_noise"/"error")
+ * and extract rows (event_subtype = "extract"). Capped at `limit` rows, ordered by created_at DESC.
+ * Fail-open: returns [] on any DB error.
+ */
+export function selectEEInjectionsForRun(runId: string, limit = 20): EEInjectionRow[] {
+  try {
+    const db = getDatabase();
+    return db
+      .prepare(
+        `SELECT session_id, event_subtype, duration_ms, metadata_json, created_at
+         FROM interaction_logs
+         WHERE session_id = ? AND event_type = 'ee_injection'
+         ORDER BY created_at DESC
+         LIMIT ?`,
+      )
+      .all(runId, limit) as EEInjectionRow[];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Log a single interaction event to the database.
+ * Synchronous SQLite insert — no await needed. Wrapped in try-catch to be fail-open.
+ */
+export function logInteraction(
+  sessionId: string,
+  eventType: InteractionEventType,
+  metadata?: {
+    eventSubtype?: string;
+    model?: string;
+    durationMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    data?: Record<string, unknown>;
+  },
+): void {
+  try {
+    const db = getDatabase();
+    const metadataJson = metadata?.data ? JSON.stringify(metadata.data) : null;
+    db.prepare(
+      `INSERT INTO interaction_logs (session_id, event_type, event_subtype, model, duration_ms, input_tokens, output_tokens, metadata_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      sessionId,
+      eventType,
+      metadata?.eventSubtype ?? null,
+      metadata?.model ?? null,
+      metadata?.durationMs ?? null,
+      metadata?.inputTokens ?? null,
+      metadata?.outputTokens ?? null,
+      metadataJson,
+      new Date().toISOString(),
+    );
+    maybePruneOld();
+  } catch {
+    // Fail-open: logging must never break the main flow
+  }
+}

package/src/storage/migrations.ts

@@ -1,6 +1,6 @@
 import type { SQLiteDatabase } from "./db";
 
-const LATEST_DB_VERSION = 4;
+const LATEST_DB_VERSION = 7;
 
 export function applyMigrations(db: SQLiteDatabase): void {
   const version = Number(db.pragma("user_version", { simple: true })) || 0;
@@ -23,11 +23,72 @@ export function applyMigrations(db: SQLiteDatabase): void {
       db.pragma("user_version = 3");
     }
     if (version < 4) {
+      // cache_read_tokens / cache_creation_tokens may already exist if the DB
+      // was created with the v1 schema that includes them inline.  Only add
+      // when missing to avoid "duplicate column name" errors.
+      const cols = db.prepare("PRAGMA table_info(usage_events)").all() as Array<{ name: string }>;
+      const colNames = new Set(cols.map((c) => c.name));
+      if (!colNames.has("cache_read_tokens")) {
+        db.exec("ALTER TABLE usage_events ADD COLUMN cache_read_tokens INTEGER NOT NULL DEFAULT 0");
+      }
+      if (!colNames.has("cache_creation_tokens")) {
+        db.exec("ALTER TABLE usage_events ADD COLUMN cache_creation_tokens INTEGER NOT NULL DEFAULT 0");
+      }
+      db.pragma("user_version = 4");
+    }
+    if (version < 5) {
       db.exec(`
-        ALTER TABLE usage_events ADD COLUMN cache_read_tokens INTEGER NOT NULL DEFAULT 0;
-        ALTER TABLE usage_events ADD COLUMN cache_creation_tokens INTEGER NOT NULL DEFAULT 0;
+        CREATE TABLE IF NOT EXISTS interaction_logs (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+          event_type TEXT NOT NULL,
+          event_subtype TEXT,
+          model TEXT,
+          duration_ms INTEGER,
+          input_tokens INTEGER,
+          output_tokens INTEGER,
+          metadata_json TEXT,
+          created_at TEXT NOT NULL
+        ) STRICT;
+
+        CREATE INDEX IF NOT EXISTS idx_interaction_logs_session
+          ON interaction_logs(session_id, created_at DESC);
+        CREATE INDEX IF NOT EXISTS idx_interaction_logs_event_type
+          ON interaction_logs(event_type, created_at DESC);
       `);
-      db.pragma("user_version = 4");
+      db.pragma("user_version = 5");
+    }
+    if (version < 6) {
+      // Phase O1 — record the SHAPE (not values) of providerOptions sent
+      // to streamText alongside each usage event. Enables post-mortem of
+      // "did this call carry store=true / promptCacheKey?" without
+      // leaking key material into the DB.
+      const cols = db.prepare("PRAGMA table_info(usage_events)").all() as Array<{ name: string }>;
+      const colNames = new Set(cols.map((c) => c.name));
+      if (!colNames.has("provider_options_shape")) {
+        db.exec("ALTER TABLE usage_events ADD COLUMN provider_options_shape TEXT");
+      }
+      db.pragma("user_version = 6");
+    }
+    if (version < 7) {
+      // Phase A5 — write-ahead persistence for assistant/user messages.
+      //
+      // `messages.status` carries the lifecycle of a row:
+      //   - 'pending'    — write-ahead INSERT before streamText fires; lets
+      //                    `recordUsage` resolve a real message_seq even when
+      //                    invoked mid-stream (was NULL → forensics anomaly).
+      //   - 'completed'  — turn settled, full message_json materialized.
+      //   - 'errored'    — stream threw mid-flight; row left with whatever
+      //                    partial content was captured.
+      //
+      // Nullable for back-compat: pre-A5 rows (legacy 'completed' state) read
+      // back as NULL and forensics treats NULL as 'completed'.
+      const cols = db.prepare("PRAGMA table_info(messages)").all() as Array<{ name: string }>;
+      const colNames = new Set(cols.map((c) => c.name));
+      if (!colNames.has("status")) {
+        db.exec("ALTER TABLE messages ADD COLUMN status TEXT");
+      }
+      db.pragma("user_version = 7");
     }
   });
 
@@ -64,6 +125,7 @@ function createInitialSchema(db: SQLiteDatabase): void {
       role TEXT NOT NULL,
       message_json TEXT NOT NULL,
       created_at TEXT NOT NULL,
+      status TEXT,
       PRIMARY KEY (session_id, seq)
     ) STRICT;
 

package/src/storage/sessions.ts

@@ -71,6 +71,23 @@ export class SessionStore {
     return this.getRequiredSession(id);
   }
 
+  /**
+   * List recent sessions in this workspace (most recently updated first).
+   * Used by the `/sessions` slash command for resume picking.
+   */
+  listRecentSessions(limit = 20): SessionInfo[] {
+    const rows = getDatabase()
+      .prepare(`
+      SELECT id, workspace_id, title, model, mode, cwd_at_start, cwd_last, status, created_at, updated_at
+      FROM sessions
+      WHERE workspace_id = ?
+      ORDER BY updated_at DESC
+      LIMIT ?
+    `)
+      .all(this.workspace.id, limit) as SessionRow[];
+    return rows.map(toSessionInfo);
+  }
+
   getLatestSession(): SessionInfo | null {
     const row = getDatabase()
       .prepare(`
@@ -105,6 +122,17 @@ export class SessionStore {
     return session;
   }
 
+  setStatus(id: string, status: SessionStatus): void {
+    const now = new Date().toISOString();
+    getDatabase()
+      .prepare(`
+      UPDATE sessions
+      SET status = ?, updated_at = ?
+      WHERE id = ?
+    `)
+      .run(status, now, id);
+  }
+
   setTitle(id: string, title: string | null): void {
     const now = new Date().toISOString();
     getDatabase()

package/src/storage/transcript.ts

@@ -39,8 +39,50 @@ interface EffectiveMessageRecord {
   timestamp: Date;
 }
 
+/**
+ * On resume, scrub raw base64 image payloads from historical tool results.
+ * Older sessions may have multi-MB Playwright screenshots inlined in tool
+ * outputs (the vision bridge used to leave them in place when the proxy
+ * failed). Loading them back into context causes provider calls to overflow
+ * the model's max context. We replace each oversized base64 blob with a
+ * stable placeholder so the resumed conversation stays under the limit.
+ */
+function sanitizeBase64InMessageJson(json: string): string {
+  if (json.length < 50_000) return json;
+  // Strip data URIs first (`data:image/png;base64,...`).
+  let scrubbed = json.replace(
+    /data:image\/[a-z+]+;base64,[A-Za-z0-9+/]{1000,}={0,2}/g,
+    "[image data removed on resume]",
+  );
+  // Then strip any remaining oversized base64 string literals — likely raw
+  // image payloads in MCP tool result fields (e.g. {"data":"iVBORw0KGgo..."}).
+  scrubbed = scrubbed.replace(/"[A-Za-z0-9+/]{2000,}={0,2}"/g, '"[image data removed on resume]"');
+  return scrubbed;
+}
+
+/**
+ * System messages with these prefixes are internal context markers used by
+ * the council layer for follow-up rehydration. They MUST NOT render in the
+ * TUI or chat export — they leak structured JSON / raw transcripts to the
+ * user and bloat exports. Council still relies on them being persisted; only
+ * the rendered view filters them out.
+ */
+const INTERNAL_COUNCIL_MARKER_PREFIXES = [
+  "[Debate Transcript]",
+  "[Council Round ",
+  "[Council Outcome]",
+  "[Council Memory]",
+  "[Council Tool Trace]",
+  "[NEEDS HUMAN REVIEW]",
+] as const;
+
+function isInternalCouncilMarker(content: string): boolean {
+  const head = content.trimStart();
+  return INTERNAL_COUNCIL_MARKER_PREFIXES.some((p) => head.startsWith(p));
+}
+
 function loadMessageRows(sessionId: string): MessageRow[] {
-  return getDatabase()
+  const rows = getDatabase()
     .prepare(`
     SELECT session_id, seq, role, message_json, created_at
     FROM messages
@@ -48,6 +90,10 @@ function loadMessageRows(sessionId: string): MessageRow[] {
     ORDER BY seq ASC
   `)
     .all(sessionId) as MessageRow[];
+  for (const row of rows) {
+    row.message_json = sanitizeBase64InMessageJson(row.message_json);
+  }
+  return rows;
 }
 
 function toPersistedCompaction(row: CompactionRow | undefined): PersistedCompaction | null {
@@ -116,9 +162,18 @@ export function appendMessages(sessionId: string, messages: ModelMessage[]): num
   const insertedSeqs: number[] = [];
   withTransaction((db) => {
     const nextSeq = getNextSequence(db, sessionId);
+    // Phase A5 — `INSERT OR REPLACE` so a pre-existing write-ahead row
+    // (status='pending', placeholder message_json) is finalized atomically
+    // with `status='completed'` and the full message_json. Pre-A5 callers
+    // hit this path identically: there is no pending row so the IGNORE
+    // branch is unused and the INSERT wins.
     const insertMessage = db.prepare(`
-      INSERT INTO messages (session_id, seq, role, message_json, created_at)
-      VALUES (?, ?, ?, ?, ?)
+      INSERT INTO messages (session_id, seq, role, message_json, created_at, status)
+      VALUES (?, ?, ?, ?, ?, 'completed')
+      ON CONFLICT(session_id, seq) DO UPDATE SET
+        role = excluded.role,
+        message_json = excluded.message_json,
+        status = 'completed'
     `);
     const insertToolCall = db.prepare(`
       INSERT OR IGNORE INTO tool_calls (
@@ -207,6 +262,154 @@ export function appendSystemMessage(sessionId: string, content: string): number
   return appendMessages(sessionId, [{ role: "system", content }])[0] ?? null;
 }
 
+/**
+ * Phase A4 — Write-ahead persistence for tool_calls.
+ *
+ * The orchestrator's streamText loop sees a `tool-call` part *before* the
+ * assistant message is finalized. If the stream throws between this point
+ * and `appendCompletedTurn(...)`, the row that the post-stream
+ * `appendMessages(...)` path would have written never materializes — and
+ * `usage forensics <prefix>` has no record of what input the model passed.
+ *
+ * This helper writes a `pending` row immediately. The downstream
+ * `appendMessages(...)` path uses `INSERT OR IGNORE` + `UPDATE` keyed on
+ * `(session_id, tool_call_id)`, so the same row is finalized to `completed`
+ * once the turn settles. On mid-stream failure the row stays as `pending`,
+ * giving forensics + recovery a recoverable trail.
+ *
+ * `messageSeq` is the predicted assistant seq (typically
+ * `getNextMessageSequence(sessionId) + 1` if the user message is also being
+ * inserted as part of the same turn). It is corrected by the post-stream
+ * UPDATE if the prediction was off.
+ */
+export function persistToolCallWriteAhead(
+  sessionId: string,
+  messageSeq: number,
+  toolCallId: string,
+  toolName: string,
+  argsJson: string,
+): void {
+  const now = new Date().toISOString();
+  try {
+    getDatabase()
+      .prepare(`
+        INSERT OR IGNORE INTO tool_calls (
+          session_id, message_seq, tool_call_id, tool_name, args_json, status, started_at, completed_at
+        ) VALUES (?, ?, ?, ?, ?, 'pending', ?, NULL)
+      `)
+      .run(sessionId, messageSeq, toolCallId, toolName, argsJson, now);
+  } catch {
+    // Fail-open: write-ahead is best-effort. The post-stream UPDATE path
+    // will still finalize the row from `appendMessages(...)`.
+  }
+}
+
+/**
+ * Phase A4 — Mark a write-ahead tool_call row as `errored` when the AI SDK
+ * surfaces a `tool-error` stream part (tool execution threw/aborted before
+ * a tool-result was emitted). The post-stream `appendMessages(...)` path
+ * does NOT see tool-error parts in the assistant message content, so without
+ * this update the row would stay `pending` forever.
+ */
+/**
+ * Phase A5 — Write-ahead persistence for `messages`.
+ *
+ * Mirrors {@link persistToolCallWriteAhead} for the assistant/user row that
+ * `streamText` will accumulate. The orchestrator's `onStepFinish` callback
+ * fires `recordUsage` while the stream is in-flight; without a pre-existing
+ * row, `lastPersistedSeq(this.messageSeqs)` returns the previous turn's seq
+ * (or NULL for the first turn → exactly the anomaly forensics surfaces).
+ *
+ * Strategy:
+ *   1. Caller computes the next seq via `getNextMessageSequence(sessionId)`.
+ *   2. Caller invokes this helper just before pushing the message into
+ *      `this.messages` and BEFORE calling streamText.
+ *   3. Caller stores the seq into `this.messageSeqs` so subsequent
+ *      `recordUsage` calls resolve `message_seq` to a non-NULL value.
+ *   4. After the turn settles, `appendMessages(...)` upserts the same row
+ *      via `ON CONFLICT(session_id, seq) DO UPDATE` — finalizing
+ *      `status='completed'` and overwriting the placeholder `message_json`.
+ *
+ * `message_json` is initially a placeholder so the column's NOT NULL
+ * constraint is satisfied; the post-stream UPDATE overwrites it.
+ *
+ * Fail-open: callers are inside the orchestrator hot path, so a SQL
+ * exception here MUST NOT propagate. The downstream `appendMessages(...)`
+ * still writes the row (just without a write-ahead trail in forensics).
+ */
+export function persistMessageWriteAhead(sessionId: string, seq: number, role: string, messageJson: string): void {
+  const now = new Date().toISOString();
+  try {
+    getDatabase()
+      .prepare(`
+        INSERT OR IGNORE INTO messages (
+          session_id, seq, role, message_json, created_at, status
+        ) VALUES (?, ?, ?, ?, ?, 'pending')
+      `)
+      .run(sessionId, seq, role, messageJson, now);
+  } catch {
+    /* fail-open */
+  }
+}
+
+/**
+ * Phase A5 — Finalize a write-ahead message row from `status='pending'`
+ * to `status='completed'`. Called by `appendCompletedTurn(...)` after the
+ * stream settles successfully. The row's `message_json` already contains
+ * the final payload (written by `persistMessageWriteAhead(...)`), so this
+ * is a cheap status flip.
+ */
+export function markMessageCompleted(sessionId: string, seq: number): void {
+  try {
+    getDatabase()
+      .prepare(`
+        UPDATE messages
+        SET status = 'completed'
+        WHERE session_id = ? AND seq = ? AND status = 'pending'
+      `)
+      .run(sessionId, seq);
+  } catch {
+    /* fail-open */
+  }
+}
+
+/**
+ * Phase A5 — Mark a write-ahead message row as `errored` when the stream
+ * throws between `persistMessageWriteAhead(...)` and the post-stream
+ * `appendMessages(...)` finalize step.
+ *
+ * Without this, a crashed turn would leave the row stuck at `pending`
+ * forever, indistinguishable from "stream still in-flight" in forensics.
+ */
+export function markMessageErrored(sessionId: string, seq: number): void {
+  try {
+    getDatabase()
+      .prepare(`
+        UPDATE messages
+        SET status = 'errored'
+        WHERE session_id = ? AND seq = ? AND status = 'pending'
+      `)
+      .run(sessionId, seq);
+  } catch {
+    /* fail-open */
+  }
+}
+
+export function markToolCallErrored(sessionId: string, toolCallId: string, errorMessage: string): void {
+  const now = new Date().toISOString();
+  try {
+    getDatabase()
+      .prepare(`
+        UPDATE tool_calls
+        SET status = 'errored', completed_at = ?, args_json = COALESCE(args_json, ?)
+        WHERE session_id = ? AND tool_call_id = ?
+      `)
+      .run(now, JSON.stringify({ error: errorMessage.slice(0, 500) }), sessionId, toolCallId);
+  } catch {
+    /* fail-open */
+  }
+}
+
 export function appendCompaction(sessionId: string, firstKeptSeq: number, summary: string, tokensBefore: number): void {
   withTransaction((db) => {
     db.prepare(`
@@ -241,7 +444,7 @@ export function buildChatEntries(sessionId: string): ChatEntry[] {
     if (message.role === "system") {
       const content =
         getCompactionSummaryText(message) ?? (typeof message.content === "string" ? message.content.trim() : "");
-      if (content) {
+      if (content && !isInternalCouncilMarker(content)) {
         entries.push({ type: "assistant", content, timestamp });
       }
       continue;