@open-code-review/cli 1.10.4 → 2.0.0

package/dist/lib/db/index.js

@@ -1,10 +1,88 @@
-import { createRequire as _cjsReq } from "module"; const require = _cjsReq(import.meta.url);
-
 // src/lib/db/index.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname2, join as join2 } from "node:path";
-import { createRequire } from "node:module";
-import initSqlJs from "sql.js";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, copyFileSync, statSync } from "node:fs";
+import { dirname as dirname3, join as join3 } from "node:path";
+
+// src/lib/db/engine.ts
+import BetterSqlite3 from "better-sqlite3";
+var BUSY_RETRY_ATTEMPTS = 5;
+var BUSY_RETRY_BACKOFF_MS = 50;
+function isBusyError(e) {
+  if (e instanceof BetterSqlite3.SqliteError) {
+    return e.code === "SQLITE_BUSY" || e.code === "SQLITE_BUSY_SNAPSHOT";
+  }
+  const code = e?.code;
+  return code === "SQLITE_BUSY" || code === "SQLITE_BUSY_SNAPSHOT";
+}
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+var BetterSqliteAdapter = class {
+  raw;
+  constructor(db) {
+    this.raw = db;
+  }
+  exec(sql, params) {
+    const stmt = this.raw.prepare(sql);
+    if (!stmt.reader) {
+      stmt.run(...params ?? []);
+      return [];
+    }
+    const columns = stmt.columns().map((c) => c.name);
+    const values = stmt.raw().all(...params ?? []);
+    return values.length > 0 ? [{ columns, values }] : [];
+  }
+  run(sql, params) {
+    if (params !== void 0) {
+      this.raw.prepare(sql).run(...params);
+      return;
+    }
+    this.raw.exec(sql);
+  }
+  prepare(sql) {
+    return this.raw.prepare(sql);
+  }
+  transaction(fn) {
+    const tx = this.raw.transaction(fn);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return tx.immediate();
+      } catch (e) {
+        if (!isBusyError(e) || attempt >= BUSY_RETRY_ATTEMPTS - 1) throw e;
+        sleepSync(BUSY_RETRY_BACKOFF_MS);
+      }
+    }
+  }
+  pragma(source) {
+    return this.raw.pragma(source);
+  }
+  close() {
+    try {
+      this.raw.pragma("wal_checkpoint(TRUNCATE)");
+    } catch {
+    }
+    this.raw.close();
+  }
+};
+function probeEngine() {
+  try {
+    const db = new BetterSqlite3(":memory:");
+    db.pragma("journal_mode = WAL");
+    db.exec("CREATE TABLE _probe(x); INSERT INTO _probe VALUES (1);");
+    const row = db.prepare("SELECT sqlite_version() AS v").get();
+    db.close();
+    return { ok: true, version: row.v };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+function openEngine(dbPath) {
+  const native = new BetterSqlite3(dbPath);
+  native.pragma("journal_mode = WAL");
+  native.pragma("foreign_keys = ON");
+  native.pragma("busy_timeout = 5000");
+  native.pragma("synchronous = NORMAL");
+  return new BetterSqliteAdapter(native);
+}
 
 // src/lib/db/migrations.ts
 var MIGRATIONS = [
@@ -261,8 +339,224 @@ var MIGRATIONS = [
       ALTER TABLE command_executions ADD COLUMN uid TEXT;
       CREATE UNIQUE INDEX idx_command_executions_uid ON command_executions(uid);
     `
+  },
+  {
+    version: 10,
+    description: "Add agent_sessions journal for per-instance lifecycle tracking",
+    sql: `
+      CREATE TABLE agent_sessions (
+        id TEXT PRIMARY KEY,
+        workflow_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE RESTRICT,
+        vendor TEXT NOT NULL,
+        vendor_session_id TEXT,
+        persona TEXT,
+        instance_index INTEGER,
+        name TEXT,
+        resolved_model TEXT,
+        phase TEXT,
+        status TEXT NOT NULL CHECK(status IN ('spawning', 'running', 'done', 'crashed', 'cancelled', 'orphaned')),
+        pid INTEGER,
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        last_heartbeat_at TEXT NOT NULL DEFAULT (datetime('now')),
+        ended_at TEXT,
+        exit_code INTEGER,
+        notes TEXT
+      );
+      CREATE INDEX idx_agent_sessions_workflow ON agent_sessions(workflow_id);
+      CREATE INDEX idx_agent_sessions_status_heartbeat ON agent_sessions(status, last_heartbeat_at);
+    `
+  },
+  {
+    version: 11,
+    description: "Unify agent_sessions into command_executions \u2014 every spawned process is one execution row",
+    sql: `
+      -- Extend command_executions with the journaling fields previously on agent_sessions.
+      -- A NULL workflow_id is allowed because some commands (e.g. sync-reviewers,
+      -- create-reviewer) don't tie to a review workflow. Existing rows get NULL by default.
+      ALTER TABLE command_executions ADD COLUMN workflow_id TEXT REFERENCES sessions(id) ON DELETE RESTRICT;
+      -- parent_id = the dashboard-spawn that's the "Tech Lead" parent of an AI-spawned
+      -- session-instance row. NULL for top-level dashboard spawns.
+      ALTER TABLE command_executions ADD COLUMN parent_id INTEGER REFERENCES command_executions(id);
+      -- Vendor metadata (claude | opencode | gemini | \u2026). NULL for non-AI commands.
+      ALTER TABLE command_executions ADD COLUMN vendor TEXT;
+      -- The underlying CLI's own session id, captured from stream events.
+      -- Used for resume / handoff. Hidden from users (ocr exposes its own id only).
+      ALTER TABLE command_executions ADD COLUMN vendor_session_id TEXT;
+      -- Persona/instance metadata for AI sub-agents (set when the AI calls
+      -- ocr session start-instance). NULL for the parent dashboard spawn.
+      ALTER TABLE command_executions ADD COLUMN persona TEXT;
+      ALTER TABLE command_executions ADD COLUMN instance_index INTEGER;
+      ALTER TABLE command_executions ADD COLUMN name TEXT;
+      -- Resolved model string passed to --model post-alias-expansion.
+      ALTER TABLE command_executions ADD COLUMN resolved_model TEXT;
+      -- Liveness heartbeat. Bumped on every state event the AI emits.
+      -- Stale rows past the threshold are reclassified to orphaned (exit_code=-3).
+      ALTER TABLE command_executions ADD COLUMN last_heartbeat_at TEXT;
+      -- Free-form annotations (sweep notes, host-CLI capability warnings, etc).
+      ALTER TABLE command_executions ADD COLUMN notes TEXT;
+      CREATE INDEX idx_command_executions_workflow ON command_executions(workflow_id);
+      CREATE INDEX idx_command_executions_parent ON command_executions(parent_id);
+      CREATE INDEX idx_command_executions_heartbeat ON command_executions(last_heartbeat_at);
+
+      -- The agent_sessions table is retired. Phase 1 was a parallel journal that
+      -- this migration consolidates. We drop the table outright \u2014 the only existing
+      -- consumers are the cli helpers and tests, which are updated alongside this
+      -- migration. No production deployments have agent_sessions data worth migrating.
+      DROP INDEX IF EXISTS idx_agent_sessions_workflow;
+      DROP INDEX IF EXISTS idx_agent_sessions_status_heartbeat;
+      DROP TABLE IF EXISTS agent_sessions;
+    `
+  },
+  {
+    version: 12,
+    description: "Event-sourced lifecycle hardening: event_type taxonomy guard, sweep indexes, session_completeness view",
+    sql: `
+      -- \u2500\u2500 Indexes for the now-periodic stale-session sweep + round derivation \u2500\u2500
+      -- The sweep filters sessions by status and rolls up MAX(created_at) per
+      -- session over the event log; deriveNextRound does MAX(round). Index both.
+      CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
+      CREATE INDEX IF NOT EXISTS idx_events_session_created
+        ON orchestration_events(session_id, created_at);
+
+      -- \u2500\u2500 Event-type taxonomy guard \u2500\u2500
+      -- orchestration_events.event_type is the spine of all lifecycle
+      -- derivation. A typo (e.g. 'round_complete' vs 'round_completed') would
+      -- silently break deriveNextRound and the completeness view. SQLite cannot
+      -- add a CHECK to an existing column without a table rebuild, so enforce
+      -- the closed vocabulary with a BEFORE INSERT trigger instead.
+      CREATE TRIGGER IF NOT EXISTS trg_events_known_type
+      BEFORE INSERT ON orchestration_events
+      WHEN NEW.event_type NOT IN (
+        'session_created', 'session_resumed', 'round_started', 'phase_transition',
+        'round_completed', 'map_completed', 'session_closed', 'session_aborted',
+        'session_auto_closed_stale', 'session_synced', 'session_legacy_import'
+      )
+      BEGIN
+        SELECT RAISE(ABORT, 'unknown orchestration_events.event_type');
+      END;
+
+      -- \u2500\u2500 Close-guard (DB backstop for the completion invariant) \u2500\u2500
+      -- A session cannot transition active \u2192 closed unless its current
+      -- round/run has a terminal artifact event, OR an explicit reason event
+      -- (abort / auto-close-stale / sync / legacy-import) is present. Only a
+      -- *silent* premature close is banned \u2014 every legitimate non-artifact
+      -- close carries a reason event and passes. App-level guards in
+      -- stateClose/finish are the primary check; this makes the illegal state
+      -- unrepresentable even via raw SQL.
+      --
+      -- DEFENCE-IN-DEPTH NOTE (intentional, documented gap): the reason-event
+      -- branch below (event_type IN (...)) is NOT round-scoped \u2014 a reason event
+      -- recorded for an earlier round would also satisfy a later close. The
+      -- app-level guards ARE round-scoped (hasCompletionInvariant checks the
+      -- current round/run), so the precise check lives in the application; this
+      -- trigger is a coarse backstop against a *silent* premature close via raw
+      -- SQL. Tightening it to be round-scoped would require a new migration
+      -- (this v12 trigger is append-only and already shipped); the residual
+      -- risk is a non-artifact close carrying a stale reason event, which is
+      -- still an explicit, audited terminal \u2014 not the failure mode this guards.
+      CREATE TRIGGER IF NOT EXISTS trg_sessions_close_guard
+      BEFORE UPDATE OF status ON sessions
+      WHEN NEW.status = 'closed' AND OLD.status <> 'closed'
+        AND NOT EXISTS (
+          SELECT 1 FROM orchestration_events e
+           WHERE e.session_id = NEW.id
+             AND (
+               (NEW.workflow_type = 'review' AND e.event_type = 'round_completed' AND e.round = NEW.current_round)
+               OR (NEW.workflow_type = 'map' AND e.event_type = 'map_completed'   AND e.round = NEW.current_map_run)
+               OR e.event_type IN ('session_aborted','session_auto_closed_stale','session_synced','session_legacy_import')
+             )
+        )
+      BEGIN
+        SELECT RAISE(ABORT, 'cannot close session without a completed round/run or an explicit reason event');
+      END;
+
+      -- \u2500\u2500 session_completeness view \u2500\u2500
+      -- The published contract for "is this session actually complete, and if
+      -- not, what's missing". Completion is DERIVED from the event log, never a
+      -- mutable flag: a session is complete iff it is closed AND a terminal
+      -- artifact event exists for its current round/run. The dashboard's
+      -- outcome derivation and the agent 'status' command read this view, so
+      -- they cannot disagree.
+      --
+      -- completeness_state is an INTENTIONAL HYBRID: it combines the mutable
+      -- status column (marked_closed) with append-only event evidence (the
+      -- terminal artifact event). This is sound precisely because the
+      -- close-guard trigger above makes the status column trustworthy \u2014 a row
+      -- can only reach status='closed' with a completed round/run or an
+      -- explicit reason event \u2014 so reading the column is not a regression to
+      -- the old "mutable flag that could lie" model.
+      --
+      --   completeness_state:
+      --     'complete'                \u2014 closed + terminal artifact for current round/run
+      --     'closed_without_artifact' \u2014 closed but no terminal artifact (the
+      --                                 "completed too soon" condition)
+      --     'in_flight'               \u2014 open with a dependent process still running
+      --     'open_no_artifact'        \u2014 open, no in-flight dependents
+      CREATE VIEW IF NOT EXISTS session_completeness AS
+      SELECT
+        s.id              AS session_id,
+        s.workflow_type   AS workflow_type,
+        s.status          AS status,
+        s.current_round   AS current_round,
+        s.current_map_run AS current_map_run,
+        CASE WHEN EXISTS (
+          SELECT 1 FROM orchestration_events e
+           WHERE e.session_id = s.id
+             AND (
+               (s.workflow_type = 'review' AND e.event_type = 'round_completed' AND e.round = s.current_round)
+               OR (s.workflow_type = 'map' AND e.event_type = 'map_completed'   AND e.round = s.current_map_run)
+             )
+        ) THEN 1 ELSE 0 END AS has_terminal_artifact,
+        CASE WHEN s.status = 'closed' THEN 1 ELSE 0 END AS marked_closed,
+        CASE WHEN NOT EXISTS (
+          SELECT 1 FROM command_executions ce
+           WHERE ce.workflow_id = s.id AND ce.finished_at IS NULL
+        ) THEN 1 ELSE 0 END AS dependents_settled,
+        CASE
+          WHEN s.status = 'closed' AND EXISTS (
+            SELECT 1 FROM orchestration_events e
+             WHERE e.session_id = s.id
+               AND (
+                 (s.workflow_type = 'review' AND e.event_type = 'round_completed' AND e.round = s.current_round)
+                 OR (s.workflow_type = 'map' AND e.event_type = 'map_completed'   AND e.round = s.current_map_run)
+               )
+          ) THEN 'complete'
+          WHEN s.status = 'closed' THEN 'closed_without_artifact'
+          WHEN EXISTS (
+            SELECT 1 FROM command_executions ce
+             WHERE ce.workflow_id = s.id AND ce.finished_at IS NULL
+          ) THEN 'in_flight'
+          ELSE 'open_no_artifact'
+        END AS completeness_state
+      FROM sessions s;
+    `
+  },
+  {
+    version: 13,
+    description: "Retire dead parent_id column on command_executions (never written; row kind is derived from command)",
+    // parent_id was reserved for an AI-instance → dashboard-spawn lineage link
+    // that was never wired (no writer, no reader). A process's KIND (supervisor
+    // / reviewer-instance / utility) is derived from columns that are always
+    // present (command + last_heartbeat_at), so the dead lineage column and its
+    // all-NULL index are removed. Re-add a wired parent_id alongside a real
+    // consumer (e.g. a parent→child tree view) if lineage is ever needed.
+    //
+    // Imperative + guarded so the DROP COLUMN (which SQLite can't express as
+    // IF EXISTS) is idempotent under re-application.
+    run: (db) => {
+      if (!columnExists(db, "command_executions", "parent_id")) return;
+      db.run("DROP INDEX IF EXISTS idx_command_executions_parent;");
+      db.run("ALTER TABLE command_executions DROP COLUMN parent_id;");
+    }
   }
 ];
+function columnExists(db, table, column) {
+  const result = db.exec(`PRAGMA table_info(${table})`);
+  const first = result[0];
+  if (!first) return false;
+  const nameIdx = first.columns.indexOf("name");
+  return first.values.some((row) => row[nameIdx] === column);
+}
 function ensureSchemaVersionTable(db) {
   db.run(`
     CREATE TABLE IF NOT EXISTS schema_version (
@@ -272,6 +566,10 @@ function ensureSchemaVersionTable(db) {
     );
   `);
 }
+function getSchemaVersion(db) {
+  ensureSchemaVersionTable(db);
+  return getCurrentVersion(db);
+}
 function getCurrentVersion(db) {
   const result = db.exec(
     "SELECT MAX(version) as v FROM schema_version"
@@ -289,9 +587,10 @@ function runMigrations(db) {
     if (migration.version <= currentVersion) {
       continue;
     }
-    db.run("BEGIN TRANSACTION;");
+    db.run("BEGIN IMMEDIATE;");
     try {
-      db.run(migration.sql);
+      if (migration.sql) db.run(migration.sql);
+      migration.run?.(db);
       db.run(
         "INSERT INTO schema_version (version, description) VALUES (?, ?);",
         [migration.version, migration.description]
@@ -304,6 +603,10 @@ function runMigrations(db) {
   }
 }
 
+// src/lib/db/reconcile.ts
+import { existsSync } from "node:fs";
+import { isAbsolute, join, dirname } from "node:path";
+
 // src/lib/db/result-mapper.ts
 function resultToRows(result) {
   if (result.length === 0 || !result[0]) {
@@ -431,10 +734,553 @@ function getLatestEventId(db) {
   const val = result[0]?.values[0]?.[0];
   return typeof val === "number" ? val : 0;
 }
+function commitReasonClose(db, sessionId, reasonEvent, projectionUpdates) {
+  db.transaction(() => {
+    insertEvent(db, { session_id: sessionId, ...reasonEvent });
+    updateSession(db, sessionId, projectionUpdates);
+  });
+}
+
+// src/lib/db/reconcile.ts
+var DEFAULT_STALE_THRESHOLD_SECONDS = 7 * 24 * 60 * 60;
+function hasTerminalArtifactEvent(db, sessionId, workflowType, currentRound, currentMapRun) {
+  const eventType = workflowType === "map" ? "map_completed" : "round_completed";
+  const round = workflowType === "map" ? currentMapRun : currentRound;
+  const r = db.exec(
+    `SELECT 1 FROM orchestration_events
+       WHERE session_id = ? AND event_type = ? AND round = ? LIMIT 1`,
+    [sessionId, eventType, round]
+  );
+  return (r[0]?.values.length ?? 0) > 0;
+}
+function hasReasonEvent(db, sessionId) {
+  const r = db.exec(
+    `SELECT 1 FROM orchestration_events
+       WHERE session_id = ?
+         AND event_type IN ('session_aborted','session_auto_closed_stale','session_synced','session_legacy_import')
+       LIMIT 1`,
+    [sessionId]
+  );
+  return (r[0]?.values.length ?? 0) > 0;
+}
+function lastEventAgeSeconds(db, sessionId) {
+  const r = db.exec(
+    `SELECT (julianday('now') - julianday(MAX(created_at))) * 86400
+       FROM orchestration_events WHERE session_id = ?`,
+    [sessionId]
+  );
+  const v = r[0]?.values[0]?.[0];
+  return typeof v === "number" ? v : null;
+}
+function hasInFlightDependents(db, sessionId) {
+  const r = db.exec(
+    `SELECT 1 FROM command_executions
+       WHERE workflow_id = ? AND finished_at IS NULL LIMIT 1`,
+    [sessionId]
+  );
+  return (r[0]?.values.length ?? 0) > 0;
+}
+function resolveSessionDir(ocrDir, sessionDir) {
+  if (!sessionDir) return null;
+  if (isAbsolute(sessionDir)) return sessionDir;
+  return join(dirname(ocrDir), sessionDir);
+}
+function reconcileLegacyState(db, ocrDir, opts = {}) {
+  const dryRun = opts.dryRun ?? false;
+  const threshold = opts.staleThresholdSeconds ?? DEFAULT_STALE_THRESHOLD_SECONDS;
+  const actions = [];
+  for (const s of getAllSessions(db)) {
+    const dir = resolveSessionDir(ocrDir, s.session_dir);
+    if (s.status === "closed") {
+      if (hasTerminalArtifactEvent(db, s.id, s.workflow_type, s.current_round, s.current_map_run) || hasReasonEvent(db, s.id)) {
+        continue;
+      }
+      const reviewFinal = s.workflow_type === "review" && dir ? existsSync(join(dir, "rounds", `round-${s.current_round}`, "final.md")) : false;
+      const mapFinal = s.workflow_type === "map" && dir ? existsSync(join(dir, "map", "runs", `run-${s.current_map_run}`, "map.md")) : false;
+      if (reviewFinal) {
+        actions.push({
+          sessionId: s.id,
+          kind: "synthesize-round-completed",
+          detail: `final.md present for round ${s.current_round}; synthesizing round_completed`
+        });
+        if (!dryRun) {
+          insertEvent(db, {
+            session_id: s.id,
+            event_type: "round_completed",
+            phase: "synthesis",
+            phase_number: 7,
+            round: s.current_round,
+            metadata: JSON.stringify({ source: "reconciled", synthesized_from: "final.md" })
+          });
+        }
+      } else if (mapFinal) {
+        actions.push({
+          sessionId: s.id,
+          kind: "synthesize-map-completed",
+          detail: `map.md present for run ${s.current_map_run}; synthesizing map_completed`
+        });
+        if (!dryRun) {
+          insertEvent(db, {
+            session_id: s.id,
+            event_type: "map_completed",
+            phase: "synthesis",
+            phase_number: 5,
+            round: s.current_map_run,
+            metadata: JSON.stringify({ source: "reconciled", synthesized_from: "map.md" })
+          });
+        }
+      } else {
+        actions.push({
+          sessionId: s.id,
+          kind: "grandfather",
+          detail: "no provable artifact; recording session_legacy_import"
+        });
+        if (!dryRun) {
+          insertEvent(db, {
+            session_id: s.id,
+            event_type: "session_legacy_import",
+            phase: "complete",
+            metadata: JSON.stringify({ source: "reconciled" })
+          });
+        }
+      }
+      continue;
+    }
+    const age = lastEventAgeSeconds(db, s.id);
+    const stale = (age === null || age > threshold) && !hasInFlightDependents(db, s.id);
+    if (stale) {
+      actions.push({
+        sessionId: s.id,
+        kind: "stale-close",
+        detail: age === null ? "active with no events and no in-flight dependents" : `active, last event ${Math.round(age / 86400)}d ago, no in-flight dependents`
+      });
+      if (!dryRun) {
+        commitReasonClose(
+          db,
+          s.id,
+          {
+            event_type: "session_auto_closed_stale",
+            phase: "complete",
+            metadata: JSON.stringify({ source: "reconciled", threshold_seconds: threshold })
+          },
+          { status: "closed", current_phase: "complete" }
+        );
+      }
+    }
+  }
+  return { dryRun, actions };
+}
+
+// src/lib/db/liveness.ts
+var PID_REUSE_GUARD_MS = 24 * 60 * 60 * 1e3;
+function defaultIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return !(err instanceof Error && "code" in err && err.code === "ESRCH");
+  }
+}
+function sqliteUtcMs(ts) {
+  const sqliteShape = ts.includes(" ");
+  return new Date(sqliteShape ? ts.replace(" ", "T") + "Z" : ts).getTime();
+}
+
+// src/lib/state/exit-codes.ts
+var STATE_EXIT = {
+  OK: 0,
+  USAGE: 2,
+  AMBIGUOUS: 3,
+  NOT_FOUND: 4,
+  ILLEGAL_TRANSITION: 5,
+  INVARIANT_UNMET: 6,
+  SCHEMA_INVALID: 7,
+  /** Database was locked past the bounded retry budget (SQLITE_BUSY). */
+  BUSY: 8
+};
+var StateError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "StateError";
+  }
+};
+var CANCELLED_EXIT_CODE = -2;
+var ORPHAN_EXIT_CODE = -3;
+var CASCADE_CLOSE_EXIT_CODE = -4;
+
+// src/lib/db/agent-sessions.ts
+var NOTE_ORPHAN_PREFIX = "orphaned by liveness sweep";
+var INSTANCE_COMMAND = "session-instance";
+function cascadeTerminateExecutions(db, workflowId, exitCode, note) {
+  db.run(
+    `UPDATE command_executions
+       SET finished_at = datetime('now'),
+           exit_code   = ?,
+           pid         = NULL,
+           notes       = COALESCE(notes || char(10), '') || ?
+     WHERE workflow_id = ?
+       AND finished_at IS NULL`,
+    [exitCode, note, workflowId]
+  );
+}
+function rowToAgentSession(row) {
+  return {
+    // The OCR-owned id is the `uid` column. Fall back to the integer
+    // primary key for legacy command_executions rows without a uid.
+    id: row.uid ?? String(row.id),
+    workflow_id: row.workflow_id ?? "",
+    vendor: row.vendor ?? "",
+    vendor_session_id: row.vendor_session_id,
+    persona: row.persona,
+    instance_index: row.instance_index,
+    name: row.name,
+    resolved_model: row.resolved_model,
+    phase: null,
+    status: deriveStatus(row),
+    kind: rowKind(row),
+    pid: row.pid,
+    started_at: row.started_at,
+    last_heartbeat_at: row.last_heartbeat_at ?? row.started_at,
+    ended_at: row.finished_at,
+    exit_code: row.exit_code,
+    notes: row.notes
+  };
+}
+function deriveStatus(row) {
+  if (row.finished_at === null) {
+    return "running";
+  }
+  if (row.exit_code === ORPHAN_EXIT_CODE) return "orphaned";
+  if (row.exit_code === CANCELLED_EXIT_CODE || row.exit_code === CASCADE_CLOSE_EXIT_CODE) {
+    return "cancelled";
+  }
+  if (row.exit_code === 0) return "done";
+  return "crashed";
+}
+function insertAgentSession(db, params) {
+  const {
+    id,
+    workflow_id,
+    vendor,
+    persona = null,
+    instance_index = null,
+    name = null,
+    resolved_model = null,
+    pid = null,
+    notes = null
+  } = params;
+  const command = persona && instance_index !== null ? `${INSTANCE_COMMAND}:${persona}-${instance_index}` : INSTANCE_COMMAND;
+  db.run(
+    `INSERT INTO command_executions
+       (uid, command, args, workflow_id, vendor, persona, instance_index, name,
+        resolved_model, pid, notes, last_heartbeat_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))`,
+    [
+      id,
+      command,
+      null,
+      workflow_id,
+      vendor,
+      persona,
+      instance_index,
+      name,
+      resolved_model,
+      pid,
+      notes
+    ]
+  );
+}
+function getAgentSession(db, id) {
+  const row = resultToRow(
+    db.exec(
+      `SELECT * FROM command_executions WHERE uid = ? AND last_heartbeat_at IS NOT NULL`,
+      [id]
+    )
+  );
+  return row ? rowToAgentSession(row) : void 0;
+}
+function listAgentSessionsForWorkflow(db, workflowId) {
+  const rows = resultToRows(
+    db.exec(
+      `SELECT * FROM command_executions
+       WHERE workflow_id = ? AND last_heartbeat_at IS NOT NULL
+       ORDER BY started_at ASC, id ASC`,
+      [workflowId]
+    )
+  );
+  return rows.map(rowToAgentSession);
+}
+function getLatestAgentSessionWithVendorId(db, workflowId) {
+  const row = resultToRow(
+    db.exec(
+      `SELECT * FROM command_executions
+       WHERE workflow_id = ? AND vendor_session_id IS NOT NULL
+       ORDER BY started_at DESC, id DESC
+       LIMIT 1`,
+      [workflowId]
+    )
+  );
+  return row ? rowToAgentSession(row) : void 0;
+}
+function bumpAgentSessionHeartbeat(db, id) {
+  db.run(
+    `UPDATE command_executions
+       SET last_heartbeat_at = datetime('now')
+       WHERE uid = ?`,
+    [id]
+  );
+}
+function setAgentSessionVendorId(db, id, vendorSessionId) {
+  const existing = getAgentSession(db, id);
+  if (!existing) {
+    throw new Error(`Agent session not found: ${id}`);
+  }
+  if (existing.vendor_session_id && existing.vendor_session_id !== vendorSessionId) {
+    throw new Error(
+      `Agent session ${id} already bound to vendor session ${existing.vendor_session_id}; refusing to rebind to ${vendorSessionId}`
+    );
+  }
+  db.run(
+    `UPDATE command_executions
+       SET vendor_session_id = ?,
+           last_heartbeat_at = datetime('now')
+       WHERE uid = ?`,
+    [vendorSessionId, id]
+  );
+}
+function bindVendorSessionIdOpportunistically(db, vendorSessionId) {
+  const alreadyBound = resultToRow(
+    db.exec(
+      `SELECT c.uid FROM command_executions c
+       INNER JOIN sessions s ON s.id = c.workflow_id
+       WHERE c.vendor_session_id = ?
+       LIMIT 1`,
+      [vendorSessionId]
+    )
+  );
+  if (alreadyBound?.uid) return alreadyBound.uid;
+  const candidate = resultToRow(
+    db.exec(
+      `SELECT c.uid, c.id FROM command_executions c
+       INNER JOIN sessions s ON s.id = c.workflow_id
+       WHERE c.finished_at IS NULL
+         AND c.vendor_session_id IS NULL
+         AND c.last_heartbeat_at IS NOT NULL
+         AND s.status = 'active'
+       ORDER BY c.started_at DESC, c.id DESC
+       LIMIT 1`
+    )
+  );
+  if (!candidate) return null;
+  db.run(
+    `UPDATE command_executions
+       SET vendor_session_id = ?,
+           last_heartbeat_at = datetime('now')
+       WHERE id = ?`,
+    [vendorSessionId, candidate.id]
+  );
+  return candidate.uid ?? String(candidate.id);
+}
+function recordVendorSessionIdForExecution(db, executionId, vendorSessionId) {
+  db.run(
+    `UPDATE command_executions
+        SET vendor_session_id = COALESCE(vendor_session_id, ?),
+            last_heartbeat_at = datetime('now')
+      WHERE id = ?`,
+    [vendorSessionId, executionId]
+  );
+}
+function linkDashboardInvocationToWorkflow(db, dashboardUid, workflowId) {
+  db.run(
+    `UPDATE command_executions
+        SET workflow_id = COALESCE(workflow_id, ?),
+            last_heartbeat_at = COALESCE(last_heartbeat_at, datetime('now'))
+      WHERE uid = ?`,
+    [workflowId, dashboardUid]
+  );
+}
+function setAgentSessionStatus(db, id, status, options = {}) {
+  const { exitCode, note, setEndedAt } = options;
+  const isTerminal = status === "done" || status === "crashed" || status === "cancelled" || status === "orphaned";
+  const stampEnded = setEndedAt ?? isTerminal;
+  let resolvedExit;
+  if (exitCode !== void 0) {
+    resolvedExit = exitCode;
+  } else if (status === "done") {
+    resolvedExit = 0;
+  } else if (status === "cancelled") {
+    resolvedExit = CANCELLED_EXIT_CODE;
+  } else if (status === "orphaned") {
+    resolvedExit = ORPHAN_EXIT_CODE;
+  } else if (status === "crashed") {
+    resolvedExit = 1;
+  } else {
+    resolvedExit = null;
+  }
+  const finishedClause = stampEnded ? ", finished_at = datetime('now')" : "";
+  if (note !== void 0) {
+    db.run(
+      `UPDATE command_executions
+         SET exit_code = ?,
+             notes = COALESCE(notes || char(10), '') || ?
+             ${finishedClause}
+         WHERE uid = ?`,
+      [resolvedExit, note, id]
+    );
+  } else {
+    db.run(
+      `UPDATE command_executions
+         SET exit_code = ?
+             ${finishedClause}
+         WHERE uid = ?`,
+      [resolvedExit, id]
+    );
+  }
+}
+function updateAgentSession(db, id, params) {
+  const setClauses = [];
+  const values = [];
+  if (params.vendor_session_id !== void 0) {
+    setClauses.push("vendor_session_id = ?");
+    values.push(params.vendor_session_id);
+  }
+  if (params.status !== void 0) {
+    setAgentSessionStatus(db, id, params.status, {
+      exitCode: params.exit_code ?? void 0,
+      note: params.notes ?? void 0
+    });
+    return;
+  }
+  if (params.pid !== void 0) {
+    setClauses.push("pid = ?");
+    values.push(params.pid);
+  }
+  if (params.ended_at !== void 0) {
+    setClauses.push("finished_at = ?");
+    values.push(params.ended_at);
+  }
+  if (params.exit_code !== void 0) {
+    setClauses.push("exit_code = ?");
+    values.push(params.exit_code);
+  }
+  if (params.notes !== void 0) {
+    setClauses.push("notes = ?");
+    values.push(params.notes);
+  }
+  if (setClauses.length === 0) return;
+  values.push(id);
+  db.run(
+    `UPDATE command_executions SET ${setClauses.join(", ")} WHERE uid = ?`,
+    values
+  );
+}
+function sweepStaleAgentSessions(db, thresholdSeconds, isAlive = defaultIsAlive) {
+  const candidates = resultToRows(
+    db.exec(
+      `SELECT uid, id, pid, started_at, workflow_id, command, last_heartbeat_at
+         FROM command_executions
+        WHERE finished_at IS NULL
+          AND pid IS NOT NULL
+          AND last_heartbeat_at IS NOT NULL
+          AND (julianday('now') - julianday(last_heartbeat_at)) * 86400 > ?`,
+      [thresholdSeconds]
+    )
+  );
+  if (candidates.length === 0) {
+    return { orphanedIds: [], cascadedWorkflowIds: [] };
+  }
+  const reuseCutoffMs = Date.now() - PID_REUSE_GUARD_MS;
+  const dead = candidates.filter((row) => {
+    if (row.pid === null) return false;
+    if (sqliteUtcMs(row.started_at) < reuseCutoffMs) return false;
+    return !isAlive(row.pid);
+  });
+  if (dead.length === 0) {
+    return { orphanedIds: [], cascadedWorkflowIds: [] };
+  }
+  const note = `${NOTE_ORPHAN_PREFIX} (threshold ${thresholdSeconds}s)`;
+  const placeholders = dead.map(() => "?").join(", ");
+  const cascadedWorkflowIds = [];
+  db.transaction(() => {
+    db.run(
+      `UPDATE command_executions
+          SET finished_at = datetime('now'),
+              exit_code = ?,
+              pid = NULL,
+              notes = COALESCE(notes || char(10), '') || ?
+        WHERE id IN (${placeholders})
+          AND finished_at IS NULL`,
+      [ORPHAN_EXIT_CODE, note, ...dead.map((r) => r.id)]
+    );
+    for (const row of dead) {
+      if (row.workflow_id && rowKind(row) === "supervisor") {
+        cascadeTerminateExecutions(
+          db,
+          row.workflow_id,
+          CASCADE_CLOSE_EXIT_CODE,
+          "cascade-closed: workflow process orphaned by liveness sweep"
+        );
+        cascadedWorkflowIds.push(row.workflow_id);
+      }
+    }
+  });
+  return {
+    orphanedIds: dead.map((r) => r.uid ?? String(r.id)),
+    cascadedWorkflowIds
+  };
+}
+function rowKind(row) {
+  if (row.command === INSTANCE_COMMAND || row.command.startsWith(`${INSTANCE_COMMAND}:`)) {
+    return "instance";
+  }
+  return row.last_heartbeat_at == null ? "utility" : "supervisor";
+}
+function sweepStaleSessions(db, thresholdSeconds) {
+  const sql = `
+    SELECT s.id
+      FROM sessions s
+      LEFT JOIN (
+        SELECT session_id, MAX(created_at) AS last_event_at
+          FROM orchestration_events
+         GROUP BY session_id
+      ) e ON e.session_id = s.id
+     WHERE s.status = 'active'
+       AND (
+         e.last_event_at IS NULL
+         OR (julianday('now') - julianday(e.last_event_at)) * 86400 > ?
+       )
+       AND NOT EXISTS (
+         SELECT 1 FROM command_executions ce
+          WHERE ce.workflow_id = s.id
+            AND ce.finished_at IS NULL
+       )
+  `;
+  const rows = resultToRows(db.exec(sql, [thresholdSeconds]));
+  if (rows.length === 0) {
+    return { closedSessionIds: [] };
+  }
+  for (const row of rows) {
+    commitReasonClose(
+      db,
+      row.id,
+      {
+        event_type: "session_auto_closed_stale",
+        phase: "complete",
+        metadata: JSON.stringify({
+          reason: "no events past threshold; no in-flight dependents",
+          threshold_seconds: thresholdSeconds
+        })
+      },
+      { status: "closed", current_phase: "complete" }
+    );
+  }
+  return { closedSessionIds: rows.map((r) => r.id) };
+}
 
 // src/lib/db/command-log.ts
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { appendFileSync, existsSync as existsSync2, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
 import { randomUUID } from "node:crypto";
 var CACHE_DIR = ".cache";
 var FILENAME = "command-history.jsonl";
@@ -445,16 +1291,16 @@ function generateCommandUid() {
   return randomUUID();
 }
 function cacheDir(ocrDir) {
-  return join(ocrDir, "data", CACHE_DIR);
+  return join2(ocrDir, "data", CACHE_DIR);
 }
 function commandLogPath(ocrDir) {
-  return join(cacheDir(ocrDir), FILENAME);
+  return join2(cacheDir(ocrDir), FILENAME);
 }
 function appendCommandLog(ocrDir, entry) {
   try {
     const filePath = commandLogPath(ocrDir);
-    const dir = dirname(filePath);
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const dir = dirname2(filePath);
+    if (!existsSync2(dir)) mkdirSync(dir, { recursive: true });
     const line = JSON.stringify(entry) + "\n";
     appendFileSync(filePath, line, { encoding: "utf-8" });
     if (approxLineCount >= 0) approxLineCount++;
@@ -464,7 +1310,7 @@ function appendCommandLog(ocrDir, entry) {
 }
 function readCommandLog(ocrDir) {
   const filePath = commandLogPath(ocrDir);
-  if (!existsSync(filePath)) return [];
+  if (!existsSync2(filePath)) return [];
   const content = readFileSync(filePath, "utf-8");
   const entries = [];
   for (const line of content.split("\n")) {
@@ -530,66 +1376,119 @@ function rotateIfNeeded(filePath) {
 }
 
 // src/lib/db/index.ts
-var connections = /* @__PURE__ */ new Map();
-function locateWasm() {
-  const require2 = createRequire(import.meta.url);
-  const sqlJsPath = require2.resolve("sql.js");
-  return join2(dirname2(sqlJsPath), "sql-wasm.wasm");
+var V2_SCHEMA_VERSION = 12;
+function maybeSnapshotBeforeUpgrade(db, dbPath, fromVersion) {
+  if (fromVersion < 1 || fromVersion >= V2_SCHEMA_VERSION) return null;
+  const bakPath = `${dbPath}.bak.v${fromVersion}`;
+  if (existsSync3(bakPath)) return bakPath;
+  try {
+    if (!existsSync3(dbPath) || statSync(dbPath).size === 0) return null;
+    db.pragma("wal_checkpoint(TRUNCATE)");
+    copyFileSync(dbPath, bakPath);
+    return bakPath;
+  } catch {
+    return null;
+  }
 }
-function applyPragmas(db) {
-  db.run("PRAGMA foreign_keys = ON;");
-  db.run("PRAGMA journal_mode = WAL;");
-  db.run("PRAGMA busy_timeout = 5000;");
+function formatUpgradeNotice(bakPath, reconcile) {
+  const lines = [
+    "Storage upgraded to v2.0 \u2014 durable SQLite engine (WAL), event-sourced lifecycle."
+  ];
+  if (bakPath) {
+    lines.push(`  A backup of your previous database was saved to: ${bakPath}`);
+  }
+  const repairs = (reconcile?.actions ?? []).filter((a) => a.kind !== "ok");
+  if (repairs.length > 0) {
+    const n = (kind) => repairs.filter((a) => a.kind === kind).length;
+    const parts = [];
+    const finalized = n("synthesize-round-completed") + n("synthesize-map-completed");
+    if (finalized > 0) parts.push(`${finalized} finalized from artifacts`);
+    if (n("grandfather") > 0) parts.push(`${n("grandfather")} grandfathered`);
+    if (n("stale-close") > 0) parts.push(`${n("stale-close")} stale closed`);
+    lines.push(
+      `  Reconciled ${repairs.length} legacy session(s): ${parts.join(", ")}.`
+    );
+  }
+  lines.push("  Run `ocr doctor` to verify the storage engine.");
+  return lines.map((l) => `[ocr] ${l}`).join("\n");
 }
+var connections = /* @__PURE__ */ new Map();
 async function openDatabase(dbPath) {
   const cached = connections.get(dbPath);
   if (cached) {
     return cached;
   }
-  const wasmBuffer = readFileSync2(locateWasm());
-  const wasmBinary = wasmBuffer.buffer.slice(
-    wasmBuffer.byteOffset,
-    wasmBuffer.byteOffset + wasmBuffer.byteLength
-  );
-  const SQL = await initSqlJs({
-    wasmBinary
-  });
-  let db;
-  if (existsSync2(dbPath)) {
-    const fileBuffer = readFileSync2(dbPath);
-    db = new SQL.Database(fileBuffer);
-  } else {
-    db = new SQL.Database();
+  const dir = dirname3(dbPath);
+  if (!existsSync3(dir)) {
+    mkdirSync2(dir, { recursive: true });
   }
-  applyPragmas(db);
+  const db = openEngine(dbPath);
   connections.set(dbPath, db);
   return db;
 }
-function saveDatabase(db, dbPath) {
-  const data = db.export();
-  const dir = dirname2(dbPath);
-  if (!existsSync2(dir)) {
-    mkdirSync2(dir, { recursive: true });
-  }
-  const tmpPath = `${dbPath}.${process.pid}.tmp`;
-  writeFileSync2(tmpPath, Buffer.from(data));
-  renameSync2(tmpPath, dbPath);
-}
 async function getDb(ocrDir) {
-  const dbPath = join2(ocrDir, "data", "ocr.db");
+  const dbPath = join3(ocrDir, "data", "ocr.db");
   return openDatabase(dbPath);
 }
 async function ensureDatabase(ocrDir) {
-  const dataDir = join2(ocrDir, "data");
-  if (!existsSync2(dataDir)) {
+  const dataDir = join3(ocrDir, "data");
+  if (!existsSync3(dataDir)) {
     mkdirSync2(dataDir, { recursive: true });
   }
-  const dbPath = join2(dataDir, "ocr.db");
+  const dbPath = join3(dataDir, "ocr.db");
   const db = await openDatabase(dbPath);
+  let before = 0;
+  try {
+    before = getSchemaVersion(db);
+  } catch {
+    before = 0;
+  }
+  const isLegacyUpgrade = before >= 1 && before < V2_SCHEMA_VERSION;
+  const bakPath = maybeSnapshotBeforeUpgrade(db, dbPath, before);
   runMigrations(db);
-  saveDatabase(db, dbPath);
+  let reconcile;
+  if (before < V2_SCHEMA_VERSION) {
+    try {
+      reconcile = reconcileLegacyState(db, ocrDir);
+    } catch (err) {
+      console.error(
+        `[ocr] legacy reconciliation skipped: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  if (isLegacyUpgrade) {
+    const notice = formatUpgradeNotice(bakPath, reconcile);
+    if (notice) console.error(notice);
+  }
   return db;
 }
+function walCheckpointTruncate(dbPath) {
+  if (!existsSync3(dbPath)) {
+    return "skipped";
+  }
+  const cached = connections.get(dbPath);
+  if (cached) {
+    try {
+      cached.pragma("wal_checkpoint(TRUNCATE)");
+      return "checkpointed";
+    } catch {
+      return "failed";
+    }
+  }
+  let transient;
+  try {
+    transient = openEngine(dbPath);
+    transient.pragma("wal_checkpoint(TRUNCATE)");
+    return "checkpointed";
+  } catch {
+    return "failed";
+  } finally {
+    try {
+      transient?.raw.close();
+    } catch {
+    }
+  }
+}
 function closeDatabase(dbPath) {
   const db = connections.get(dbPath);
   if (db) {
@@ -604,30 +1503,57 @@ function closeAllDatabases() {
   }
 }
 export {
+  CANCELLED_EXIT_CODE,
+  CASCADE_CLOSE_EXIT_CODE,
   MIGRATIONS,
+  ORPHAN_EXIT_CODE,
+  PID_REUSE_GUARD_MS,
+  STATE_EXIT,
+  StateError,
   appendCommandLog,
-  applyPragmas,
+  bindVendorSessionIdOpportunistically,
+  bumpAgentSessionHeartbeat,
   cacheDir,
+  cascadeTerminateExecutions,
   closeAllDatabases,
   closeDatabase,
   commandLogPath,
+  commitReasonClose,
+  defaultIsAlive,
   ensureDatabase,
+  formatUpgradeNotice,
   generateCommandUid,
+  getAgentSession,
   getAllSessions,
   getDb,
   getEventsForSession,
   getLatestActiveSession,
+  getLatestAgentSessionWithVendorId,
   getLatestEventId,
+  getSchemaVersion,
   getSession,
+  insertAgentSession,
   insertEvent,
   insertSession,
-  locateWasm,
+  isBusyError,
+  linkDashboardInvocationToWorkflow,
+  listAgentSessionsForWorkflow,
   openDatabase,
+  probeEngine,
   readCommandLog,
+  reconcileLegacyState,
+  recordVendorSessionIdForExecution,
   replayCommandLog,
   resultToRow,
   resultToRows,
+  rowKind,
   runMigrations,
-  saveDatabase,
-  updateSession
+  setAgentSessionStatus,
+  setAgentSessionVendorId,
+  sqliteUtcMs,
+  sweepStaleAgentSessions,
+  sweepStaleSessions,
+  updateAgentSession,
+  updateSession,
+  walCheckpointTruncate
 };