@open-code-review/cli 1.11.0 → 2.1.0

package/dist/index.js

@@ -39,6 +39,30 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/lib/runtime-checks.ts
+function isSupportedNode(version) {
+  const [major = 0, minor = 0] = version.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  return major > NODE_FLOOR.major || major === NODE_FLOOR.major && minor >= NODE_FLOOR.minor;
+}
+function nodeVersionGuardMessage(version) {
+  return `
+Open Code Review requires Node.js >= ${NODE_FLOOR.major}.${NODE_FLOOR.minor} (it uses Node's built-in SQLite, \`node:sqlite\`).
+You have Node ${version}. Upgrade Node (e.g. \`nvm install 22 && nvm use 22\`) and re-run.
+
+`;
+}
+function isSuppressibleSqliteWarning(warning) {
+  const message = typeof warning === "string" ? warning : warning?.message;
+  return typeof message === "string" && message.includes("SQLite is an experimental feature");
+}
+var NODE_FLOOR;
+var init_runtime_checks = __esm({
+  "src/lib/runtime-checks.ts"() {
+    "use strict";
+    NODE_FLOOR = { major: 22, minor: 5 };
+  }
+});
+
 // ../../node_modules/.pnpm/commander@13.1.0/node_modules/commander/lib/error.js
 var require_error = __commonJS({
   "../../node_modules/.pnpm/commander@13.1.0/node_modules/commander/lib/error.js"(exports) {
@@ -23319,7 +23343,195 @@ var init_result_mapper = __esm({
   }
 });
 
+// src/lib/db/engine.ts
+import { createRequire as createRequire2 } from "node:module";
+function applyEnginePreconditions() {
+  if (_preconditionsApplied) return;
+  _preconditionsApplied = true;
+  const originalEmitWarning = process.emitWarning.bind(process);
+  process.emitWarning = (warning, ...args) => {
+    if (isSuppressibleSqliteWarning(warning)) return;
+    originalEmitWarning(warning, ...args);
+  };
+}
+function newDatabase(path2) {
+  if (!_DatabaseSyncCtor) {
+    applyEnginePreconditions();
+    try {
+      _DatabaseSyncCtor = nodeRequire("node:sqlite").DatabaseSync;
+    } catch (e) {
+      if (!isSupportedNode(process.versions.node)) {
+        throw new Error(nodeVersionGuardMessage(process.versions.node).trim());
+      }
+      throw e;
+    }
+  }
+  return new _DatabaseSyncCtor(path2);
+}
+function isBusyError(e) {
+  const errcode = e?.errcode;
+  return errcode === SQLITE_BUSY || errcode === SQLITE_BUSY_SNAPSHOT;
+}
+function sleepSync(ms) {
+  Atomics.wait(SLEEP_BUF, 0, 0, ms);
+}
+function probeEngine() {
+  try {
+    const db = newDatabase(":memory:");
+    db.exec("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 = newDatabase(dbPath);
+  native.exec("PRAGMA journal_mode = WAL");
+  native.exec("PRAGMA foreign_keys = ON");
+  native.exec("PRAGMA busy_timeout = 5000");
+  native.exec("PRAGMA synchronous = NORMAL");
+  return new NodeSqliteAdapter(native);
+}
+var SQLITE_BUSY, SQLITE_BUSY_SNAPSHOT, BUSY_RETRY_ATTEMPTS, BUSY_RETRY_BACKOFF_MS, savepointName, nodeRequire, _preconditionsApplied, _DatabaseSyncCtor, SLEEP_BUF, NodeSqliteAdapter;
+var init_engine = __esm({
+  "src/lib/db/engine.ts"() {
+    "use strict";
+    init_runtime_checks();
+    SQLITE_BUSY = 5;
+    SQLITE_BUSY_SNAPSHOT = 261;
+    BUSY_RETRY_ATTEMPTS = 5;
+    BUSY_RETRY_BACKOFF_MS = 50;
+    savepointName = (depth) => `ocr_sp_${depth}`;
+    nodeRequire = createRequire2(import.meta.url);
+    _preconditionsApplied = false;
+    SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+    NodeSqliteAdapter = class {
+      raw;
+      /**
+       * Transaction nesting depth. `node:sqlite` has no transaction helper, so we
+       * drive `BEGIN IMMEDIATE` ourselves and use SAVEPOINTs for nested calls
+       * (better-sqlite3 did this automatically). 0 = no transaction open.
+       */
+      txnDepth = 0;
+      constructor(db) {
+        this.raw = db;
+      }
+      exec(sql, params) {
+        const stmt = this.raw.prepare(sql);
+        const cols = stmt.columns();
+        if (cols.length === 0) {
+          stmt.run(...params ?? []);
+          return [];
+        }
+        stmt.setReturnArrays(true);
+        const values = stmt.all(...params ?? []);
+        return values.length > 0 ? [{ columns: cols.map((c) => c.name), 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) {
+        return this.txnDepth > 0 ? this.runNested(fn) : this.runOuter(fn);
+      }
+      /**
+       * Nested call: a SAVEPOINT within the outer transaction's write lock. No
+       * busy-retry — the outer transaction already holds the lock. The savepoint
+       * lets the inner block roll back independently while the outer continues.
+       */
+      runNested(fn) {
+        const name = savepointName(this.txnDepth);
+        this.raw.exec(`SAVEPOINT ${name}`);
+        this.txnDepth++;
+        try {
+          const result = fn();
+          this.raw.exec(`RELEASE ${name}`);
+          return result;
+        } catch (e) {
+          try {
+            this.raw.exec(`ROLLBACK TO ${name}`);
+            this.raw.exec(`RELEASE ${name}`);
+          } catch {
+          }
+          throw e;
+        } finally {
+          this.txnDepth--;
+        }
+      }
+      /**
+       * Outer transaction: `BEGIN IMMEDIATE` acquires the write lock up front so
+       * cross-process writers serialize cleanly under WAL instead of failing late
+       * on upgrade. `busy_timeout` covers most contention; a bounded synchronous
+       * retry absorbs the residual SQLITE_BUSY (another connection holds the lock
+       * past the timeout, or BUSY_SNAPSHOT). Non-busy errors and the final attempt
+       * re-throw so genuine failures propagate.
+       */
+      runOuter(fn) {
+        for (let attempt = 0; attempt < BUSY_RETRY_ATTEMPTS; attempt++) {
+          try {
+            return this.runOnce(fn);
+          } catch (e) {
+            if (!isBusyError(e) || attempt === BUSY_RETRY_ATTEMPTS - 1) throw e;
+            sleepSync(BUSY_RETRY_BACKOFF_MS);
+          }
+        }
+        throw new Error("transaction retry budget exhausted");
+      }
+      /** One `BEGIN IMMEDIATE` / `COMMIT` / `ROLLBACK` lifecycle. */
+      runOnce(fn) {
+        this.raw.exec("BEGIN IMMEDIATE");
+        this.txnDepth = 1;
+        try {
+          const result = fn();
+          this.raw.exec("COMMIT");
+          return result;
+        } catch (e) {
+          try {
+            this.raw.exec("ROLLBACK");
+          } catch {
+          }
+          throw e;
+        } finally {
+          this.txnDepth = 0;
+        }
+      }
+      pragma(source) {
+        this.raw.exec(`PRAGMA ${source}`);
+        return void 0;
+      }
+      close() {
+        try {
+          this.raw.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+        } catch {
+        }
+        try {
+          this.raw.close();
+        } catch (e) {
+          const message = e?.message ?? "";
+          if (!/database is not open/i.test(message)) throw e;
+        }
+      }
+    };
+  }
+});
+
 // src/lib/db/migrations.ts
+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 (
@@ -23329,6 +23541,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"
@@ -23346,9 +23562,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]
@@ -23685,6 +23902,148 @@ var init_migrations = __esm({
       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;");
+        }
       }
     ];
   }
@@ -23798,6 +24157,12 @@ 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);
+  });
+}
 var init_queries = __esm({
   "src/lib/db/queries.ts"() {
     "use strict";
@@ -23805,7 +24170,208 @@ var init_queries = __esm({
   }
 });
 
+// src/lib/db/reconcile.ts
+import { existsSync as existsSync10 } from "node:fs";
+import { isAbsolute as isAbsolute2, join as join12, dirname as dirname4 } from "node:path";
+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 (isAbsolute2(sessionDir)) return sessionDir;
+  return join12(dirname4(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 ? existsSync10(join12(dir, "rounds", `round-${s.current_round}`, "final.md")) : false;
+      const mapFinal = s.workflow_type === "map" && dir ? existsSync10(join12(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 };
+}
+var DEFAULT_STALE_THRESHOLD_SECONDS;
+var init_reconcile = __esm({
+  "src/lib/db/reconcile.ts"() {
+    "use strict";
+    init_queries();
+    DEFAULT_STALE_THRESHOLD_SECONDS = 7 * 24 * 60 * 60;
+  }
+});
+
+// src/lib/db/liveness.ts
+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();
+}
+var PID_REUSE_GUARD_MS;
+var init_liveness = __esm({
+  "src/lib/db/liveness.ts"() {
+    "use strict";
+    PID_REUSE_GUARD_MS = 24 * 60 * 60 * 1e3;
+  }
+});
+
+// src/lib/state/exit-codes.ts
+var STATE_EXIT, StateError, CANCELLED_EXIT_CODE, ORPHAN_EXIT_CODE, CASCADE_CLOSE_EXIT_CODE;
+var init_exit_codes = __esm({
+  "src/lib/state/exit-codes.ts"() {
+    "use strict";
+    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
+    };
+    StateError = class extends Error {
+      constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "StateError";
+      }
+    };
+    CANCELLED_EXIT_CODE = -2;
+    ORPHAN_EXIT_CODE = -3;
+    CASCADE_CLOSE_EXIT_CODE = -4;
+  }
+});
+
 // src/lib/db/agent-sessions.ts
+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
@@ -23820,6 +24386,7 @@ function rowToAgentSession(row) {
     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,
@@ -23833,7 +24400,9 @@ function deriveStatus(row) {
     return "running";
   }
   if (row.exit_code === ORPHAN_EXIT_CODE) return "orphaned";
-  if (row.exit_code === CANCELLED_EXIT_CODE) return "cancelled";
+  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";
 }
@@ -23849,7 +24418,7 @@ function insertAgentSession(db, params) {
     pid = null,
     notes = null
   } = params;
-  const command = persona && instance_index !== null ? `session-instance:${persona}-${instance_index}` : "session-instance";
+  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,
@@ -24054,63 +24623,139 @@ function updateAgentSession(db, id, params) {
     values
   );
 }
-function sweepStaleAgentSessions(db, thresholdSeconds) {
-  const staleSql = `
-    SELECT uid, id FROM command_executions
-    WHERE finished_at IS NULL
-      AND last_heartbeat_at IS NOT NULL
-      AND (julianday('now') - julianday(last_heartbeat_at)) * 86400 > ?
-  `;
-  const stale = resultToRows(
-    db.exec(staleSql, [thresholdSeconds])
+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 (stale.length === 0) {
-    return { orphanedIds: [] };
+  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)`;
-  db.run(
-    `UPDATE command_executions
-       SET finished_at = datetime('now'),
-           exit_code = ?,
-           notes = COALESCE(notes || char(10), '') || ?
-     WHERE finished_at IS NULL
-       AND last_heartbeat_at IS NOT NULL
-       AND (julianday('now') - julianday(last_heartbeat_at)) * 86400 > ?`,
-    [ORPHAN_EXIT_CODE, note, thresholdSeconds]
-  );
+  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: stale.map((row) => row.uid ?? String(row.id))
+    orphanedIds: dead.map((r) => r.uid ?? String(r.id)),
+    cascadedWorkflowIds
   };
 }
-var ORPHAN_EXIT_CODE, CANCELLED_EXIT_CODE, NOTE_ORPHAN_PREFIX;
+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) };
+}
+var NOTE_ORPHAN_PREFIX, INSTANCE_COMMAND;
 var init_agent_sessions = __esm({
   "src/lib/db/agent-sessions.ts"() {
     "use strict";
     init_result_mapper();
-    ORPHAN_EXIT_CODE = -3;
-    CANCELLED_EXIT_CODE = -2;
+    init_queries();
+    init_liveness();
+    init_exit_codes();
     NOTE_ORPHAN_PREFIX = "orphaned by liveness sweep";
+    INSTANCE_COMMAND = "session-instance";
   }
 });
 
 // src/lib/db/command-log.ts
-import { appendFileSync, existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync9, renameSync, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname4, join as join12 } from "node:path";
+import { appendFileSync, existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync9, renameSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname5, join as join13 } from "node:path";
 import { randomUUID as randomUUID2 } from "node:crypto";
 function generateCommandUid() {
   return randomUUID2();
 }
 function cacheDir(ocrDir) {
-  return join12(ocrDir, "data", CACHE_DIR);
+  return join13(ocrDir, "data", CACHE_DIR);
 }
 function commandLogPath(ocrDir) {
-  return join12(cacheDir(ocrDir), FILENAME);
+  return join13(cacheDir(ocrDir), FILENAME);
 }
 function appendCommandLog(ocrDir, entry) {
   try {
     const filePath = commandLogPath(ocrDir);
-    const dir = dirname4(filePath);
-    if (!existsSync10(dir)) mkdirSync3(dir, { recursive: true });
+    const dir = dirname5(filePath);
+    if (!existsSync11(dir)) mkdirSync3(dir, { recursive: true });
     const line = JSON.stringify(entry) + "\n";
     appendFileSync(filePath, line, { encoding: "utf-8" });
     if (approxLineCount >= 0) approxLineCount++;
@@ -24120,7 +24765,7 @@ function appendCommandLog(ocrDir, entry) {
 }
 function readCommandLog(ocrDir) {
   const filePath = commandLogPath(ocrDir);
-  if (!existsSync10(filePath)) return [];
+  if (!existsSync11(filePath)) return [];
   const content = readFileSync9(filePath, "utf-8");
   const entries = [];
   for (const line of content.split("\n")) {
@@ -24199,16 +24844,25 @@ var init_command_log = __esm({
 // src/lib/db/index.ts
 var db_exports = {};
 __export(db_exports, {
+  CANCELLED_EXIT_CODE: () => CANCELLED_EXIT_CODE,
+  CASCADE_CLOSE_EXIT_CODE: () => CASCADE_CLOSE_EXIT_CODE,
   MIGRATIONS: () => MIGRATIONS,
+  ORPHAN_EXIT_CODE: () => ORPHAN_EXIT_CODE,
+  PID_REUSE_GUARD_MS: () => PID_REUSE_GUARD_MS,
+  STATE_EXIT: () => STATE_EXIT,
+  StateError: () => StateError,
   appendCommandLog: () => appendCommandLog,
-  applyPragmas: () => applyPragmas,
   bindVendorSessionIdOpportunistically: () => bindVendorSessionIdOpportunistically,
   bumpAgentSessionHeartbeat: () => bumpAgentSessionHeartbeat,
   cacheDir: () => cacheDir,
+  cascadeTerminateExecutions: () => cascadeTerminateExecutions,
   closeAllDatabases: () => closeAllDatabases,
   closeDatabase: () => closeDatabase,
   commandLogPath: () => commandLogPath,
+  commitReasonClose: () => commitReasonClose,
+  defaultIsAlive: () => defaultIsAlive,
   ensureDatabase: () => ensureDatabase,
+  formatUpgradeNotice: () => formatUpgradeNotice,
   generateCommandUid: () => generateCommandUid,
   getAgentSession: () => getAgentSession,
   getAllSessions: () => getAllSessions,
@@ -24217,119 +24871,153 @@ __export(db_exports, {
   getLatestActiveSession: () => getLatestActiveSession,
   getLatestAgentSessionWithVendorId: () => getLatestAgentSessionWithVendorId,
   getLatestEventId: () => getLatestEventId,
+  getSchemaVersion: () => getSchemaVersion,
   getSession: () => getSession,
   insertAgentSession: () => insertAgentSession,
   insertEvent: () => insertEvent,
   insertSession: () => insertSession,
+  isBusyError: () => isBusyError,
   linkDashboardInvocationToWorkflow: () => linkDashboardInvocationToWorkflow,
   listAgentSessionsForWorkflow: () => listAgentSessionsForWorkflow,
-  locateWasm: () => locateWasm,
   openDatabase: () => openDatabase,
+  probeEngine: () => probeEngine,
+  probeWrite: () => probeWrite,
   readCommandLog: () => readCommandLog,
+  reconcileLegacyState: () => reconcileLegacyState,
   recordVendorSessionIdForExecution: () => recordVendorSessionIdForExecution,
   replayCommandLog: () => replayCommandLog,
   resultToRow: () => resultToRow,
   resultToRows: () => resultToRows,
+  rowKind: () => rowKind,
   runMigrations: () => runMigrations,
-  saveDatabase: () => saveDatabase,
   setAgentSessionStatus: () => setAgentSessionStatus,
   setAgentSessionVendorId: () => setAgentSessionVendorId,
+  sqliteUtcMs: () => sqliteUtcMs,
   sweepStaleAgentSessions: () => sweepStaleAgentSessions,
+  sweepStaleSessions: () => sweepStaleSessions,
   updateAgentSession: () => updateAgentSession,
   updateSession: () => updateSession,
   walCheckpointTruncate: () => walCheckpointTruncate
 });
-import { existsSync as existsSync11, mkdirSync as mkdirSync4, readFileSync as readFileSync10, renameSync as renameSync2, writeFileSync as writeFileSync7 } from "node:fs";
-import { dirname as dirname5, join as join13 } from "node:path";
-import { createRequire as createRequire2 } from "node:module";
-import { spawnSync as spawnSync2 } from "node:child_process";
-import initSqlJs from "sql.js";
-function locateWasm() {
-  const require3 = createRequire2(import.meta.url);
-  const sqlJsPath = require3.resolve("sql.js");
-  return join13(dirname5(sqlJsPath), "sql-wasm.wasm");
-}
-function applyPragmas(db) {
-  db.run("PRAGMA foreign_keys = ON;");
-  db.run("PRAGMA journal_mode = WAL;");
-  db.run("PRAGMA busy_timeout = 5000;");
+import {
+  existsSync as existsSync12,
+  mkdirSync as mkdirSync4,
+  copyFileSync,
+  statSync,
+  mkdtempSync,
+  rmSync
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname as dirname6, join as join14 } from "node:path";
+function maybeSnapshotBeforeUpgrade(db, dbPath, fromVersion) {
+  if (fromVersion < 1 || fromVersion >= V2_SCHEMA_VERSION) return null;
+  const bakPath = `${dbPath}.bak.v${fromVersion}`;
+  if (existsSync12(bakPath)) return bakPath;
+  try {
+    if (!existsSync12(dbPath) || statSync(dbPath).size === 0) return null;
+    db.pragma("wal_checkpoint(TRUNCATE)");
+    copyFileSync(dbPath, bakPath);
+    return bakPath;
+  } catch {
+    return null;
+  }
+}
+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");
 }
 async function openDatabase(dbPath) {
   const cached = connections.get(dbPath);
   if (cached) {
     return cached;
   }
-  const wasmBuffer = readFileSync10(locateWasm());
-  const wasmBinary = wasmBuffer.buffer.slice(
-    wasmBuffer.byteOffset,
-    wasmBuffer.byteOffset + wasmBuffer.byteLength
-  );
-  const SQL = await initSqlJs({
-    wasmBinary
-  });
-  let db;
-  if (existsSync11(dbPath)) {
-    const fileBuffer = readFileSync10(dbPath);
-    db = new SQL.Database(fileBuffer);
-  } else {
-    db = new SQL.Database();
+  const dir = dirname6(dbPath);
+  if (!existsSync12(dir)) {
+    mkdirSync4(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 = dirname5(dbPath);
-  if (!existsSync11(dir)) {
-    mkdirSync4(dir, { recursive: true });
-  }
-  const tmpPath = `${dbPath}.${process.pid}.tmp`;
-  writeFileSync7(tmpPath, Buffer.from(data));
-  renameSync2(tmpPath, dbPath);
-}
 async function getDb(ocrDir) {
-  const dbPath = join13(ocrDir, "data", "ocr.db");
+  const dbPath = join14(ocrDir, "data", "ocr.db");
   return openDatabase(dbPath);
 }
 async function ensureDatabase(ocrDir) {
-  const dataDir = join13(ocrDir, "data");
-  if (!existsSync11(dataDir)) {
+  const dataDir = join14(ocrDir, "data");
+  if (!existsSync12(dataDir)) {
     mkdirSync4(dataDir, { recursive: true });
   }
-  const dbPath = join13(dataDir, "ocr.db");
+  const dbPath = join14(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 (!existsSync11(dbPath)) {
+  if (!existsSync12(dbPath)) {
     return "skipped";
   }
-  try {
-    const probe = spawnSync2("sqlite3", ["-version"], {
-      stdio: "ignore",
-      timeout: 2e3
-    });
-    if (probe.status !== 0) {
-      return "skipped";
+  const cached = connections.get(dbPath);
+  if (cached) {
+    try {
+      cached.pragma("wal_checkpoint(TRUNCATE)");
+      return "checkpointed";
+    } catch {
+      return "failed";
     }
-  } catch {
-    return "skipped";
   }
+  let transient;
   try {
-    const result = spawnSync2(
-      "sqlite3",
-      [dbPath, "PRAGMA wal_checkpoint(TRUNCATE);"],
-      {
-        stdio: "ignore",
-        timeout: 5e3
-      }
-    );
-    return result.status === 0 ? "checkpointed" : "failed";
+    transient = openEngine(dbPath);
+    transient.pragma("wal_checkpoint(TRUNCATE)");
+    return "checkpointed";
   } catch {
     return "failed";
+  } finally {
+    try {
+      transient?.close();
+    } catch {
+    }
   }
 }
 function closeDatabase(dbPath) {
@@ -24345,20 +25033,70 @@ function closeAllDatabases() {
     connections.delete(path2);
   }
 }
-var connections;
+function probeWrite() {
+  let dir;
+  try {
+    dir = mkdtempSync(join14(tmpdir(), "ocr-probe-"));
+    const db = openEngine(join14(dir, "probe.db"));
+    try {
+      db.run("CREATE TABLE _probe_write (id INTEGER PRIMARY KEY, v TEXT)");
+      db.transaction(() => {
+        db.run("INSERT INTO _probe_write (v) VALUES (?)", ["written-in-txn"]);
+      });
+      const value = db.exec("SELECT v FROM _probe_write")[0]?.values[0]?.[0];
+      if (value !== "written-in-txn") {
+        return { ok: false, error: `unexpected probe value: ${String(value)}` };
+      }
+      return { ok: true };
+    } finally {
+      db.close();
+    }
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  } finally {
+    if (dir) rmDirBestEffort(dir);
+  }
+}
+function rmDirBestEffort(dir) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+      return;
+    } catch {
+      if (attempt === 2) return;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+}
+var V2_SCHEMA_VERSION, connections;
 var init_db = __esm({
   "src/lib/db/index.ts"() {
     "use strict";
+    init_engine();
     init_migrations();
+    init_reconcile();
     init_queries();
     init_agent_sessions();
+    init_liveness();
+    init_exit_codes();
     init_migrations();
     init_result_mapper();
+    init_engine();
+    init_reconcile();
+    init_migrations();
     init_command_log();
+    V2_SCHEMA_VERSION = 12;
     connections = /* @__PURE__ */ new Map();
   }
 });
 
+// src/lib/runtime-guard.ts
+init_runtime_checks();
+if (!isSupportedNode(process.versions.node)) {
+  process.stderr.write(nodeVersionGuardMessage(process.versions.node));
+  process.exit(1);
+}
+
 // ../../node_modules/.pnpm/commander@13.1.0/node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
 var {
@@ -28763,7 +29501,7 @@ ${hint}
 }
 
 // src/lib/version.ts
-var CLI_VERSION = true ? "1.11.0" : createRequire(import.meta.url)("../../package.json").version;
+var CLI_VERSION = true ? "2.1.0" : createRequire(import.meta.url)("../../package.json").version;
 
 // ../shared/platform/src/index.ts
 import { pathToFileURL } from "node:url";
@@ -29822,9 +30560,9 @@ var NodeFsHandler = class {
     if (this.fsw.closed) {
       return;
     }
-    const dirname7 = sysPath.dirname(file);
+    const dirname8 = sysPath.dirname(file);
     const basename8 = sysPath.basename(file);
-    const parent = this.fsw._getWatchedDir(dirname7);
+    const parent = this.fsw._getWatchedDir(dirname8);
     let prevStats = stats;
     if (parent.has(basename8))
       return;
@@ -29851,7 +30589,7 @@ var NodeFsHandler = class {
             prevStats = newStats2;
           }
         } catch (error) {
-          this.fsw._remove(dirname7, basename8);
+          this.fsw._remove(dirname8, basename8);
         }
       } else if (parent.has(basename8)) {
         const at = newStats.atimeMs;
@@ -30784,8 +31522,8 @@ function watch(paths, options = {}) {
 }
 
 // src/commands/progress.ts
-import { existsSync as existsSync12, readdirSync as readdirSync5, statSync } from "node:fs";
-import { join as join14, basename as basename7 } from "node:path";
+import { existsSync as existsSync13, readdirSync as readdirSync5, statSync as statSync2 } from "node:fs";
+import { join as join15, basename as basename7 } from "node:path";
 
 // ../../node_modules/.pnpm/log-update@7.0.2/node_modules/log-update/index.js
 import process12 from "node:process";
@@ -32421,15 +33159,15 @@ function debounce(fn, delay) {
   };
 }
 function findLatestActiveSession(sessionsDir) {
-  if (!existsSync12(sessionsDir)) {
+  if (!existsSync13(sessionsDir)) {
     return null;
   }
   const sessions = readdirSync5(sessionsDir).filter((name) => {
-    const sessionPath = join14(sessionsDir, name);
-    return statSync(sessionPath).isDirectory();
+    const sessionPath = join15(sessionsDir, name);
+    return statSync2(sessionPath).isDirectory();
   }).sort().reverse();
   for (const session of sessions) {
-    const sessionPath = join14(sessionsDir, session);
+    const sessionPath = join15(sessionsDir, session);
     if (isSessionActive(sessionPath)) {
       return session;
     }
@@ -32444,8 +33182,8 @@ function getStrategyForSession(sessionPath, explicitWorkflow) {
   return getStrategy(workflowType) ?? null;
 }
 async function initProgressDb(ocrDir) {
-  const dbPath = join14(ocrDir, "data", "ocr.db");
-  if (!existsSync12(dbPath)) {
+  const dbPath = join15(ocrDir, "data", "ocr.db");
+  if (!existsSync13(dbPath)) {
     return;
   }
   try {
@@ -32470,11 +33208,11 @@ var progressCommand = new Command("progress").description("Watch real-time progr
   const targetDir = process.cwd();
   requireOcrSetup(targetDir);
   const sessionsDir = ensureSessionsDir(targetDir);
-  const ocrDir = join14(targetDir, ".ocr");
+  const ocrDir = join15(targetDir, ".ocr");
   await initProgressDb(ocrDir);
   if (options.session) {
-    const sessionPath = join14(sessionsDir, options.session);
-    if (!existsSync12(sessionPath)) {
+    const sessionPath = join15(sessionsDir, options.session);
+    if (!existsSync13(sessionPath)) {
       console.error(source_default.red(`Session not found: ${options.session}`));
       process.exit(1);
     }
@@ -32499,7 +33237,7 @@ var progressCommand = new Command("progress").description("Watch real-time progr
       );
       console.error(
         source_default.dim(
-          `The orchestrating agent must create state via 'ocr state init' for progress tracking.`
+          `The orchestrating agent must create state via 'ocr state begin' for progress tracking.`
         )
       );
       process.exit(1);
@@ -32535,7 +33273,7 @@ var progressCommand = new Command("progress").description("Watch real-time progr
     return;
   }
   let currentSession = findLatestActiveSession(sessionsDir);
-  let currentSessionPath = currentSession ? join14(sessionsDir, currentSession) : null;
+  let currentSessionPath = currentSession ? join15(sessionsDir, currentSession) : null;
   let sessionWatcher = null;
   const preservedStartTimes = {
     review: void 0,
@@ -32543,11 +33281,11 @@ var progressCommand = new Command("progress").description("Watch real-time progr
   };
   let currentStrategy = null;
   const updateDisplayImpl = () => {
-    if (!currentSessionPath || !existsSync12(currentSessionPath) || !isSessionActive(currentSessionPath)) {
+    if (!currentSessionPath || !existsSync13(currentSessionPath) || !isSessionActive(currentSessionPath)) {
       const latestActive = findLatestActiveSession(sessionsDir);
       if (latestActive && latestActive !== currentSession) {
         currentSession = latestActive;
-        currentSessionPath = join14(sessionsDir, latestActive);
+        currentSessionPath = join15(sessionsDir, latestActive);
         preservedStartTimes.review = void 0;
         preservedStartTimes.map = void 0;
         currentStrategy = null;
@@ -32560,7 +33298,7 @@ var progressCommand = new Command("progress").description("Watch real-time progr
         currentStrategy = null;
       }
     }
-    if (currentSessionPath && existsSync12(currentSessionPath)) {
+    if (currentSessionPath && existsSync13(currentSessionPath)) {
       if (!options.workflow) {
         const activeWorkflows = detectActiveWorkflows(currentSessionPath);
         if (activeWorkflows.length > 1) {
@@ -32614,15 +33352,15 @@ var progressCommand = new Command("progress").description("Watch real-time progr
     watchSession(currentSessionPath);
   }
   const timerInterval = setInterval(updateDisplay, 1e3);
-  const watchDir = existsSync12(ocrDir) ? ocrDir : targetDir;
+  const watchDir = existsSync13(ocrDir) ? ocrDir : targetDir;
   const dirWatcher = watch(watchDir, {
     persistent: true,
     ignoreInitial: true,
     depth: 3
   });
   dirWatcher.on("addDir", (dirPath) => {
-    const parentDir = join14(dirPath, "..");
-    const isDirectChild = parentDir.endsWith("sessions") || parentDir.endsWith(join14(".ocr", "sessions"));
+    const parentDir = join15(dirPath, "..");
+    const isDirectChild = parentDir.endsWith("sessions") || parentDir.endsWith(join15(".ocr", "sessions"));
     if (isDirectChild && !dirPath.endsWith("sessions")) {
       const newSession = basename7(dirPath);
       currentSession = newSession;
@@ -32724,226 +33462,115 @@ function renderCombinedProgress(sessionPath, preservedStartTimes, ocrDir) {
 }
 
 // src/commands/state.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync6, readFileSync as readFileSync12 } from "node:fs";
-import { join as join16 } from "node:path";
+import { existsSync as existsSync15, mkdirSync as mkdirSync6, readFileSync as readFileSync11 } from "node:fs";
+import { join as join17 } from "node:path";
 
 // src/lib/state/index.ts
 init_db();
+init_exit_codes();
 import {
-  existsSync as existsSync13,
+  existsSync as existsSync14,
   mkdirSync as mkdirSync5,
   readdirSync as readdirSync6,
-  readFileSync as readFileSync11,
-  statSync as statSync2,
-  writeFileSync as writeFileSync8
+  readFileSync as readFileSync10,
+  statSync as statSync3,
+  writeFileSync as writeFileSync7
 } from "node:fs";
-import { join as join15 } from "node:path";
-function hasArtifacts(dir) {
-  try {
-    for (const entry of readdirSync6(dir, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        if (hasArtifacts(join15(dir, entry.name))) return true;
-      } else if (/\.(md|json)$/.test(entry.name)) {
-        return true;
-      }
-    }
-  } catch {
-  }
-  return false;
-}
-async function stateInit(params) {
-  const { sessionId, branch, workflowType, sessionDir, ocrDir } = params;
-  const db = await ensureDatabase(ocrDir);
-  const dbPath = join15(ocrDir, "data", "ocr.db");
-  const existing = getSession(db, sessionId);
-  if (existing) {
-    const roundsDir = join15(sessionDir, "rounds");
-    let nextRound = 1;
-    if (existsSync13(roundsDir)) {
-      const roundDirs = readdirSync6(roundsDir).filter((d) => /^round-\d+$/.test(d)).map((d) => parseInt(d.replace("round-", ""), 10)).sort((a, b) => a - b);
-      if (roundDirs.length > 0) {
-        const highest = roundDirs[roundDirs.length - 1];
-        const hasFinal = existsSync13(
-          join15(roundsDir, `round-${highest}`, "final.md")
-        );
-        nextRound = hasFinal ? highest + 1 : highest;
-      }
-    }
-    updateSession(db, sessionId, {
-      status: "active",
-      current_phase: "context",
-      phase_number: 1,
-      current_round: nextRound
-    });
-    insertEvent(db, {
-      session_id: sessionId,
-      event_type: nextRound > (existing.current_round ?? 1) ? "round_started" : "session_resumed",
-      phase: "context",
-      phase_number: 1,
-      round: nextRound
-    });
-    saveDatabase(db, dbPath);
-    return sessionId;
-  }
-  insertSession(db, {
-    id: sessionId,
-    branch,
-    workflow_type: workflowType,
-    current_phase: "context",
-    phase_number: 1,
-    current_round: 1,
-    current_map_run: 1,
-    session_dir: sessionDir
-  });
-  insertEvent(db, {
-    session_id: sessionId,
-    event_type: "session_created",
-    phase: "context",
-    phase_number: 1,
-    round: 1
-  });
-  saveDatabase(db, dbPath);
-  return sessionId;
-}
-async function stateTransition(params) {
-  const { sessionId, phase, phaseNumber, round, mapRun, ocrDir } = params;
-  const db = await ensureDatabase(ocrDir);
-  const dbPath = join15(ocrDir, "data", "ocr.db");
-  const existing = getSession(db, sessionId);
-  if (!existing) {
-    throw new Error(`Session not found: ${sessionId}`);
-  }
-  const previousRound = existing.current_round;
-  updateSession(db, sessionId, {
-    current_phase: phase,
-    phase_number: phaseNumber,
-    ...round !== void 0 ? { current_round: round } : {},
-    ...mapRun !== void 0 ? { current_map_run: mapRun } : {}
-  });
-  insertEvent(db, {
-    session_id: sessionId,
-    event_type: "phase_transition",
-    phase,
-    phase_number: phaseNumber,
-    round: round ?? existing.current_round
-  });
-  if (round !== void 0 && round !== previousRound) {
-    insertEvent(db, {
-      session_id: sessionId,
-      event_type: "round_started",
-      phase,
-      phase_number: phaseNumber,
-      round
-    });
+import { join as join16 } from "node:path";
+
+// src/lib/state/phase-graph.ts
+init_exit_codes();
+var REVIEW_PHASE_NUMBERS = {
+  context: 1,
+  "change-context": 2,
+  analysis: 3,
+  reviews: 4,
+  aggregation: 5,
+  discourse: 6,
+  synthesis: 7,
+  complete: 8
+};
+var MAP_PHASE_NUMBERS = {
+  "map-context": 1,
+  topology: 2,
+  "flow-analysis": 3,
+  "requirements-mapping": 4,
+  synthesis: 5,
+  complete: 6
+};
+function phaseNumberFor(workflowType, phase) {
+  const map = workflowType === "map" ? MAP_PHASE_NUMBERS : REVIEW_PHASE_NUMBERS;
+  const n = map[phase];
+  if (n === void 0) {
+    throw new StateError(
+      STATE_EXIT.ILLEGAL_TRANSITION,
+      `Invalid phase "${phase}" for workflow_type "${workflowType}". Valid: ${Object.keys(map).join(", ")}`
+    );
   }
-  saveDatabase(db, dbPath);
+  return n;
 }
-async function stateClose(params) {
-  const { sessionId, ocrDir } = params;
-  const db = await ensureDatabase(ocrDir);
-  const dbPath = join15(ocrDir, "data", "ocr.db");
-  const existing = getSession(db, sessionId);
-  if (!existing) {
-    throw new Error(`Session not found: ${sessionId}`);
-  }
-  updateSession(db, sessionId, {
-    status: "closed",
-    current_phase: "complete"
-  });
-  insertEvent(db, {
-    session_id: sessionId,
-    event_type: "session_closed",
-    phase: "complete",
-    phase_number: existing.phase_number,
-    round: existing.current_round
-  });
-  saveDatabase(db, dbPath);
+var REVIEW_PHASE_GRAPH = {
+  context: ["change-context"],
+  "change-context": ["analysis"],
+  analysis: ["reviews"],
+  reviews: ["aggregation"],
+  aggregation: ["discourse"],
+  discourse: ["synthesis"],
+  synthesis: ["complete"],
+  complete: ["context"]
+};
+var MAP_PHASE_GRAPH = {
+  "map-context": ["topology"],
+  topology: ["flow-analysis"],
+  "flow-analysis": ["requirements-mapping"],
+  "requirements-mapping": ["synthesis"],
+  synthesis: ["complete"],
+  complete: ["map-context"]
+};
+function graphFor(workflowType) {
+  return workflowType === "review" ? REVIEW_PHASE_GRAPH : MAP_PHASE_GRAPH;
 }
-async function stateShow(ocrDir, sessionId) {
-  let db;
-  try {
-    db = await ensureDatabase(ocrDir);
-  } catch {
-    return null;
-  }
-  const session = sessionId ? getSession(db, sessionId) : getLatestActiveSession(db);
-  if (!session) {
-    return null;
-  }
-  const events = getEventsForSession(db, session.id);
-  return {
-    session: {
-      id: session.id,
-      branch: session.branch,
-      status: session.status,
-      workflow_type: session.workflow_type,
-      current_phase: session.current_phase,
-      phase_number: session.phase_number,
-      current_round: session.current_round,
-      current_map_run: session.current_map_run,
-      started_at: session.started_at,
-      updated_at: session.updated_at
-    },
-    events: events.map((e) => ({
-      id: e.id,
-      event_type: e.event_type,
-      phase: e.phase,
-      phase_number: e.phase_number,
-      round: e.round,
-      metadata: e.metadata,
-      created_at: e.created_at
-    }))
-  };
+function initialPhaseFor(workflowType) {
+  return workflowType === "map" ? "map-context" : "context";
 }
-async function resolveActiveSession(ocrDir) {
-  const db = await ensureDatabase(ocrDir);
-  const session = getLatestActiveSession(db);
-  if (!session) {
-    throw new Error("No active session found");
+function validatePhaseTransition(workflowType, source, target, isRoundBoundary) {
+  const graph = graphFor(workflowType);
+  if (!(target in graph)) {
+    const validPhases = Object.keys(graph).join(", ");
+    throw new StateError(
+      STATE_EXIT.ILLEGAL_TRANSITION,
+      `Invalid phase "${target}" for workflow_type "${workflowType}". Valid phases: ${validPhases}`
+    );
   }
-  return {
-    id: session.id,
-    sessionDir: session.session_dir
-  };
-}
-function readJsonFromSource(params) {
-  if (params.source === "file") {
-    if (!existsSync13(params.filePath)) {
-      throw new Error(`File not found: ${params.filePath}`);
-    }
-    return readFileSync11(params.filePath, "utf-8");
+  if (source === target) return;
+  if (isRoundBoundary) {
+    const initial = initialPhaseFor(workflowType);
+    if (target === initial) return;
+    throw new StateError(
+      STATE_EXIT.ILLEGAL_TRANSITION,
+      `Illegal round-boundary transition: a new round/run must reset to "${initial}", not "${target}".`
+    );
   }
-  return params.data;
-}
-function parseRawJson(raw, label) {
-  try {
-    return JSON.parse(raw);
-  } catch (err) {
-    throw new Error(
-      `Failed to parse ${label}: ${err instanceof Error ? err.message : "invalid JSON"}`
+  const allowed = graph[source];
+  if (!allowed || !allowed.includes(target)) {
+    throw new StateError(
+      STATE_EXIT.ILLEGAL_TRANSITION,
+      `Illegal phase transition: ${source} \u2192 ${target}. From "${source}", only ${allowed && allowed.length > 0 ? allowed.join(", ") : "(no edges)"} are reachable. Pass --current-round to start a new round if the workflow is resetting.`
     );
   }
 }
-function resolveSessionForCompletion(db, explicitId) {
-  if (explicitId) {
-    const existing = getSession(db, explicitId);
-    if (!existing) throw new Error(`Session not found: ${explicitId}`);
-    return {
-      id: existing.id,
-      session_dir: existing.session_dir,
-      current_round: existing.current_round,
-      current_map_run: existing.current_map_run
-    };
-  }
-  const active = getLatestActiveSession(db);
-  if (!active) throw new Error("No active session found");
-  return {
-    id: active.id,
-    session_dir: active.session_dir,
-    current_round: active.current_round,
-    current_map_run: active.current_map_run
-  };
+
+// src/lib/state/meta-util.ts
+var DEFAULT_METADATA_MAX_LEN = 4096;
+function sanitizeMetadataString(s, opts = {}) {
+  const maxLen = opts.maxLen ?? DEFAULT_METADATA_MAX_LEN;
+  let out = s.replace(/[\x00-\x08\x0b-\x1f]/g, "");
+  out = out.replace(/^\s*\[ocr\]\s*/i, "");
+  if (out.length > maxLen) out = out.slice(0, maxLen);
+  return out;
 }
+
+// src/lib/state/round-meta.ts
 var VALID_CATEGORIES = /* @__PURE__ */ new Set(["blocker", "should_fix", "suggestion", "style"]);
 var VALID_SEVERITIES = /* @__PURE__ */ new Set(["critical", "high", "medium", "low", "info"]);
 function validateRoundMeta(meta) {
@@ -32959,6 +33586,7 @@ function validateRoundMeta(meta) {
   if (typeof obj.verdict !== "string" || obj.verdict.trim().length === 0) {
     throw new Error("round-meta.json must contain a non-empty verdict string");
   }
+  obj.verdict = sanitizeMetadataString(obj.verdict);
   if (!Array.isArray(obj.reviewers)) {
     throw new Error("round-meta.json must contain a reviewers array");
   }
@@ -32984,6 +33612,7 @@ function validateRoundMeta(meta) {
       if (typeof f.title !== "string" || f.title.trim().length === 0) {
         throw new Error("Each finding must have a non-empty title");
       }
+      f.title = sanitizeMetadataString(f.title);
       if (typeof f.category !== "string" || !VALID_CATEGORIES.has(f.category)) {
         throw new Error(
           `Finding "${f.title}" has invalid category: "${String(f.category)}". Must be one of: ${[...VALID_CATEGORIES].join(", ")}`
@@ -32997,6 +33626,7 @@ function validateRoundMeta(meta) {
       if (typeof f.summary !== "string") {
         throw new Error(`Finding "${f.title}" must have a summary string`);
       }
+      f.summary = sanitizeMetadataString(f.summary);
       if (f.file_path !== void 0 && typeof f.file_path !== "string") {
         throw new Error(`Finding "${f.title}" has invalid file_path: expected string`);
       }
@@ -33042,43 +33672,8 @@ function computeRoundCounts(meta) {
     totalFindingCount: allFindings.length
   };
 }
-async function stateRoundComplete(params) {
-  const { ocrDir } = params;
-  const db = await ensureDatabase(ocrDir);
-  const dbPath = join15(ocrDir, "data", "ocr.db");
-  const rawJsonString = readJsonFromSource(params);
-  const label = params.source === "file" ? params.filePath : "stdin";
-  const raw = parseRawJson(rawJsonString, label);
-  const meta = validateRoundMeta(raw);
-  const counts = computeRoundCounts(meta);
-  const session = resolveSessionForCompletion(db, params.sessionId);
-  const roundNumber = params.round ?? session.current_round;
-  let metaPath;
-  if (params.source === "stdin") {
-    const roundDir = join15(session.session_dir, "rounds", `round-${roundNumber}`);
-    mkdirSync5(roundDir, { recursive: true });
-    metaPath = join15(roundDir, "round-meta.json");
-    writeFileSync8(metaPath, JSON.stringify(meta, null, 2));
-  }
-  insertEvent(db, {
-    session_id: session.id,
-    event_type: "round_completed",
-    phase: "synthesis",
-    phase_number: 7,
-    round: roundNumber,
-    metadata: JSON.stringify({
-      verdict: meta.verdict,
-      blocker_count: counts.blockerCount,
-      should_fix_count: counts.shouldFixCount,
-      suggestion_count: counts.suggestionCount,
-      reviewer_count: counts.reviewerCount,
-      total_finding_count: counts.totalFindingCount,
-      source: "orchestrator"
-    })
-  });
-  saveDatabase(db, dbPath);
-  return { sessionId: session.id, round: roundNumber, metaPath };
-}
+
+// src/lib/state/map-meta.ts
 function validateMapMeta(meta) {
   if (!meta || typeof meta !== "object") {
     throw new Error("map-meta.json must be a JSON object");
@@ -33103,6 +33698,13 @@ function validateMapMeta(meta) {
     if (typeof s.title !== "string" || s.title.trim().length === 0) {
       throw new Error("Each section must have a non-empty title");
     }
+    s.title = sanitizeMetadataString(s.title);
+    if (s.description !== void 0) {
+      if (typeof s.description !== "string") {
+        throw new Error(`Section "${s.title}" description must be a string if provided`);
+      }
+      s.description = sanitizeMetadataString(s.description);
+    }
     if (!Array.isArray(s.files)) {
       throw new Error(`Section "${s.title}" must have a files array`);
     }
@@ -33117,6 +33719,7 @@ function validateMapMeta(meta) {
       if (typeof f.role !== "string") {
         throw new Error(`File "${f.file_path}" must have a role string`);
       }
+      f.role = sanitizeMetadataString(f.role);
       if (typeof f.lines_added !== "number") {
         throw new Error(`File "${f.file_path}" must have a lines_added number`);
       }
@@ -33136,53 +33739,597 @@ function computeMapCounts(meta) {
     fileCount: meta.sections.reduce((sum, s) => sum + s.files.length, 0)
   };
 }
-async function stateMapComplete(params) {
+
+// src/lib/state/projection.ts
+init_db();
+var REASON_EVENT_TYPES = [
+  "session_aborted",
+  "session_auto_closed_stale",
+  "session_synced",
+  "session_legacy_import"
+];
+var TERMINAL_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "session_closed",
+  ...REASON_EVENT_TYPES
+]);
+function hasCompletionInvariant(db, session) {
+  const eventType = session.workflow_type === "map" ? "map_completed" : "round_completed";
+  const round = session.workflow_type === "map" ? session.current_map_run : session.current_round;
+  const r = db.exec(
+    `SELECT 1 FROM orchestration_events
+       WHERE session_id = ? AND event_type = ? AND round = ? LIMIT 1`,
+    [session.id, eventType, round]
+  );
+  return (r[0]?.values.length ?? 0) > 0;
+}
+function getCompletenessState(db, sessionId) {
+  const r = db.exec(
+    "SELECT completeness_state FROM session_completeness WHERE session_id = ?",
+    [sessionId]
+  );
+  return r[0]?.values[0]?.[0] ?? null;
+}
+
+// src/lib/state/index.ts
+init_exit_codes();
+function deriveNextRound(db, sessionId, fallbackRound) {
+  const result = db.exec(
+    `SELECT MAX(round) FROM orchestration_events
+       WHERE session_id = ? AND event_type = 'round_completed'`,
+    [sessionId]
+  );
+  const max = result[0]?.values[0]?.[0];
+  if (typeof max === "number") return max + 1;
+  return fallbackRound;
+}
+function hasArtifacts(dir) {
+  try {
+    for (const entry of readdirSync6(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (hasArtifacts(join16(dir, entry.name))) return true;
+      } else if (/\.(md|json)$/.test(entry.name)) {
+        return true;
+      }
+    }
+  } catch {
+  }
+  return false;
+}
+function readJsonFromSource(params) {
+  if (params.source === "file") {
+    if (!existsSync14(params.filePath)) {
+      throw new StateError(STATE_EXIT.NOT_FOUND, `File not found: ${params.filePath}`);
+    }
+    return readFileSync10(params.filePath, "utf-8");
+  }
+  return params.data;
+}
+function parseRawJson(raw, label) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new StateError(
+      STATE_EXIT.SCHEMA_INVALID,
+      `Failed to parse ${label}: ${err instanceof Error ? err.message : "invalid JSON"}`
+    );
+  }
+}
+async function stateInit(params) {
+  const { sessionId, branch, workflowType, sessionDir, ocrDir } = params;
+  const db = await ensureDatabase(ocrDir);
+  const existing = getSession(db, sessionId);
+  if (existing) {
+    if (existing.workflow_type !== workflowType) {
+      throw new StateError(
+        STATE_EXIT.USAGE,
+        `Cannot re-open session ${sessionId} as workflow_type "${workflowType}": existing workflow_type is "${existing.workflow_type}". Maps and reviews have disjoint phase graphs.`
+      );
+    }
+    const nextRound = deriveNextRound(db, sessionId, existing.current_round);
+    const initialPhase2 = workflowType === "map" ? "map-context" : "context";
+    db.transaction(() => {
+      updateSession(db, sessionId, {
+        status: "active",
+        current_phase: initialPhase2,
+        phase_number: 1,
+        current_round: nextRound
+      });
+      insertEvent(db, {
+        session_id: sessionId,
+        event_type: nextRound > (existing.current_round ?? 1) ? "round_started" : "session_resumed",
+        phase: initialPhase2,
+        phase_number: 1,
+        round: nextRound
+      });
+    });
+    return sessionId;
+  }
+  const initialPhase = workflowType === "map" ? "map-context" : "context";
+  db.transaction(() => {
+    insertSession(db, {
+      id: sessionId,
+      branch,
+      workflow_type: workflowType,
+      current_phase: initialPhase,
+      phase_number: 1,
+      current_round: 1,
+      current_map_run: 1,
+      session_dir: sessionDir
+    });
+    insertEvent(db, {
+      session_id: sessionId,
+      event_type: "session_created",
+      phase: initialPhase,
+      phase_number: 1,
+      round: 1
+    });
+  });
+  return sessionId;
+}
+async function stateTransition(params, db) {
+  const { sessionId, phase, phaseNumber, round, mapRun, ocrDir } = params;
+  db ??= await ensureDatabase(ocrDir);
+  const existing = getSession(db, sessionId);
+  if (!existing) {
+    throw new StateError(STATE_EXIT.NOT_FOUND, `Session not found: ${sessionId}`);
+  }
+  const previousRound = existing.current_round;
+  const previousMapRun = existing.current_map_run;
+  const isRoundBoundary = round !== void 0 && round !== previousRound || mapRun !== void 0 && mapRun !== previousMapRun;
+  validatePhaseTransition(
+    existing.workflow_type,
+    existing.current_phase,
+    phase,
+    isRoundBoundary
+  );
+  db.transaction(() => {
+    updateSession(db, sessionId, {
+      current_phase: phase,
+      phase_number: phaseNumber,
+      ...round !== void 0 ? { current_round: round } : {},
+      ...mapRun !== void 0 ? { current_map_run: mapRun } : {}
+    });
+    insertEvent(db, {
+      session_id: sessionId,
+      event_type: "phase_transition",
+      phase,
+      phase_number: phaseNumber,
+      round: round ?? existing.current_round
+    });
+    if (round !== void 0 && round !== previousRound) {
+      insertEvent(db, {
+        session_id: sessionId,
+        event_type: "round_started",
+        phase,
+        phase_number: phaseNumber,
+        round
+      });
+    }
+  });
+}
+async function stateClose(params) {
+  const { sessionId, ocrDir, abort } = params;
+  const db = await ensureDatabase(ocrDir);
+  const existing = getSession(db, sessionId);
+  if (!existing) {
+    throw new StateError(STATE_EXIT.NOT_FOUND, `Session not found: ${sessionId}`);
+  }
+  if (existing.status === "closed") {
+    console.error(`[ocr] Session already closed: ${sessionId}`);
+    return;
+  }
+  if (!abort && !hasCompletionInvariant(db, existing)) {
+    const what = existing.workflow_type === "map" ? `map run ${existing.current_map_run} has no map_completed event` : `round ${existing.current_round} has no round_completed event`;
+    throw new StateError(
+      STATE_EXIT.INVARIANT_UNMET,
+      `Cannot close session ${sessionId}: ${what}. Run 'ocr state complete-round' to finalize it, or pass --abort to record an abandoned session.`
+    );
+  }
+  const note = "closed by parent workflow close";
+  db.transaction(() => {
+    if (abort) {
+      insertEvent(db, {
+        session_id: sessionId,
+        event_type: "session_aborted",
+        phase: existing.current_phase,
+        phase_number: existing.phase_number,
+        round: existing.current_round
+      });
+    }
+    updateSession(db, sessionId, {
+      status: "closed",
+      current_phase: "complete"
+    });
+    if (!abort) {
+      insertEvent(db, {
+        session_id: sessionId,
+        event_type: "session_closed",
+        phase: "complete",
+        phase_number: existing.phase_number,
+        round: existing.current_round
+      });
+    }
+    cascadeTerminateExecutions(db, sessionId, CASCADE_CLOSE_EXIT_CODE, note);
+  });
+}
+async function stateShow(ocrDir, sessionId) {
+  let db;
+  try {
+    db = await ensureDatabase(ocrDir);
+  } catch {
+    return null;
+  }
+  const session = sessionId ? getSession(db, sessionId) : getLatestActiveSession(db);
+  if (!session) {
+    return null;
+  }
+  const events = getEventsForSession(db, session.id);
+  return {
+    session: {
+      id: session.id,
+      branch: session.branch,
+      status: session.status,
+      workflow_type: session.workflow_type,
+      current_phase: session.current_phase,
+      phase_number: session.phase_number,
+      current_round: session.current_round,
+      current_map_run: session.current_map_run,
+      started_at: session.started_at,
+      updated_at: session.updated_at
+    },
+    events: events.map((e) => ({
+      id: e.id,
+      event_type: e.event_type,
+      phase: e.phase,
+      phase_number: e.phase_number,
+      round: e.round,
+      metadata: e.metadata,
+      created_at: e.created_at
+    }))
+  };
+}
+function resolveSession(db, explicitId) {
+  if (explicitId) {
+    const s = getSession(db, explicitId);
+    if (!s) throw new StateError(STATE_EXIT.NOT_FOUND, `Session not found: ${explicitId}`);
+    return {
+      id: s.id,
+      session_dir: s.session_dir,
+      current_round: s.current_round,
+      current_map_run: s.current_map_run,
+      workflow_type: s.workflow_type,
+      status: s.status,
+      current_phase: s.current_phase,
+      phase_number: s.phase_number,
+      branch: s.branch,
+      decision: "explicit"
+    };
+  }
+  const uid = process.env["OCR_DASHBOARD_EXECUTION_UID"];
+  if (uid) {
+    const result = db.exec(
+      "SELECT workflow_id FROM command_executions WHERE uid = ?",
+      [uid]
+    );
+    const workflowId = result[0]?.values[0]?.[0];
+    if (workflowId) {
+      const s = getSession(db, workflowId);
+      if (s) {
+        return {
+          id: s.id,
+          session_dir: s.session_dir,
+          current_round: s.current_round,
+          current_map_run: s.current_map_run,
+          workflow_type: s.workflow_type,
+          status: s.status,
+          current_phase: s.current_phase,
+          phase_number: s.phase_number,
+          branch: s.branch,
+          decision: "dashboard-uid"
+        };
+      }
+    }
+  }
+  const activeRows = db.exec(
+    `SELECT id, session_dir, current_round, current_map_run, workflow_type,
+            status, current_phase, phase_number, branch
+       FROM sessions
+      WHERE status = 'active'
+      ORDER BY started_at DESC`
+  );
+  const rows = activeRows[0]?.values ?? [];
+  if (rows.length === 0) throw new StateError(STATE_EXIT.NOT_FOUND, "No active session found");
+  if (rows.length > 1) {
+    const ids = rows.map((r) => r[0]);
+    throw new StateError(
+      STATE_EXIT.AMBIGUOUS,
+      `Ambiguous auto-detect: ${rows.length} active sessions exist. Pass --session-id explicitly. Candidates: ${ids.join(", ")}`
+    );
+  }
+  const row = rows[0];
+  return {
+    id: row[0],
+    session_dir: row[1],
+    current_round: row[2],
+    current_map_run: row[3],
+    workflow_type: row[4],
+    status: row[5],
+    current_phase: row[6],
+    phase_number: row[7],
+    branch: row[8],
+    decision: "latest-active"
+  };
+}
+function announceResolveDecision(r) {
+  if (r.decision === "explicit") return;
+  const path2 = r.decision === "dashboard-uid" ? "via OCR_DASHBOARD_EXECUTION_UID" : "via latest-active";
+  console.error(`[ocr] Auto-detected session: ${r.id} (${path2})`);
+}
+async function resolveActiveSession(ocrDir, explicitId) {
+  const db = await ensureDatabase(ocrDir);
+  const result = resolveSession(db, explicitId);
+  announceResolveDecision(result);
+  return {
+    id: result.id,
+    sessionDir: result.session_dir,
+    decision: result.decision
+  };
+}
+async function stateBegin(params) {
+  const id = await stateInit(params);
+  const db = await ensureDatabase(params.ocrDir);
+  const s = getSession(db, id);
+  return {
+    schema_version: 1,
+    session_id: id,
+    round: s?.current_round ?? 1,
+    phase: s?.current_phase ?? "context",
+    completeness: getCompletenessState(db, id)
+  };
+}
+async function stateAdvance(params) {
+  const db = await ensureDatabase(params.ocrDir);
+  const existing = getSession(db, params.sessionId);
+  if (!existing) {
+    throw new StateError(STATE_EXIT.NOT_FOUND, `Session not found: ${params.sessionId}`);
+  }
+  const phaseNumber = phaseNumberFor(existing.workflow_type, params.phase);
+  await stateTransition(
+    {
+      sessionId: params.sessionId,
+      phase: params.phase,
+      phaseNumber,
+      round: params.round,
+      mapRun: params.mapRun,
+      ocrDir: params.ocrDir
+    },
+    db
+  );
+}
+async function stateCompleteRound(params) {
   const { ocrDir } = params;
   const db = await ensureDatabase(ocrDir);
-  const dbPath = join15(ocrDir, "data", "ocr.db");
-  const rawJsonString = readJsonFromSource(params);
-  const label = params.source === "file" ? params.filePath : "stdin";
-  const raw = parseRawJson(rawJsonString, label);
-  const meta = validateMapMeta(raw);
-  const counts = computeMapCounts(meta);
-  const session = resolveSessionForCompletion(db, params.sessionId);
-  const mapRunNumber = params.mapRun ?? session.current_map_run;
+  let meta;
+  let counts;
+  try {
+    const rawJsonString = readJsonFromSource(params);
+    const label = params.source === "file" ? params.filePath : "stdin";
+    meta = validateRoundMeta(parseRawJson(rawJsonString, label));
+    counts = computeRoundCounts(meta);
+  } catch (e) {
+    throw new StateError(
+      STATE_EXIT.SCHEMA_INVALID,
+      e instanceof Error ? e.message : "invalid round metadata"
+    );
+  }
+  const resolved = resolveSession(db, params.sessionId);
+  const roundNumber = params.round ?? resolved.current_round;
+  const roundMetaPath = join16(
+    resolved.session_dir,
+    "rounds",
+    `round-${roundNumber}`,
+    "round-meta.json"
+  );
+  const already = db.exec(
+    `SELECT 1 FROM orchestration_events
+       WHERE session_id = ? AND event_type = 'round_completed' AND round = ? LIMIT 1`,
+    [resolved.id, roundNumber]
+  );
+  if ((already[0]?.values.length ?? 0) > 0) {
+    return { sessionId: resolved.id, round: roundNumber, metaPath: roundMetaPath, schema_version: 1 };
+  }
+  if (resolved.current_phase !== "synthesis") {
+    throw new StateError(
+      STATE_EXIT.INVARIANT_UNMET,
+      `Cannot complete round: workflow is at "${resolved.current_phase}", not "synthesis". Advance through the phases first.`
+    );
+  }
+  if (params.requireFinal) {
+    const finalPath = join16(resolved.session_dir, "rounds", `round-${roundNumber}`, "final.md");
+    if (!existsSync14(finalPath)) {
+      throw new StateError(
+        STATE_EXIT.INVARIANT_UNMET,
+        `Cannot complete round: --require-final set but ${finalPath} is missing.`
+      );
+    }
+  }
+  let metaPath;
+  if (params.source === "stdin") {
+    const roundDir = join16(resolved.session_dir, "rounds", `round-${roundNumber}`);
+    mkdirSync5(roundDir, { recursive: true });
+    metaPath = roundMetaPath;
+    writeFileSync7(metaPath, JSON.stringify(meta, null, 2));
+  }
+  db.transaction(() => {
+    insertEvent(db, {
+      session_id: resolved.id,
+      event_type: "round_completed",
+      phase: "synthesis",
+      phase_number: 7,
+      round: roundNumber,
+      metadata: JSON.stringify({
+        verdict: meta.verdict,
+        blocker_count: counts.blockerCount,
+        should_fix_count: counts.shouldFixCount,
+        suggestion_count: counts.suggestionCount,
+        reviewer_count: counts.reviewerCount,
+        total_finding_count: counts.totalFindingCount,
+        source: "orchestrator"
+      })
+    });
+    if (roundNumber >= resolved.current_round) {
+      updateSession(db, resolved.id, { current_round: roundNumber });
+    }
+    validatePhaseTransition("review", resolved.current_phase, "complete", false);
+    updateSession(db, resolved.id, { current_phase: "complete", phase_number: 8 });
+    insertEvent(db, {
+      session_id: resolved.id,
+      event_type: "phase_transition",
+      phase: "complete",
+      phase_number: 8,
+      round: roundNumber
+    });
+  });
+  return { sessionId: resolved.id, round: roundNumber, metaPath, schema_version: 1 };
+}
+async function stateCompleteMap(params) {
+  const { ocrDir } = params;
+  const db = await ensureDatabase(ocrDir);
+  let meta;
+  let counts;
+  try {
+    const rawJsonString = readJsonFromSource(params);
+    const label = params.source === "file" ? params.filePath : "stdin";
+    meta = validateMapMeta(parseRawJson(rawJsonString, label));
+    counts = computeMapCounts(meta);
+  } catch (e) {
+    throw new StateError(
+      STATE_EXIT.SCHEMA_INVALID,
+      e instanceof Error ? e.message : "invalid map metadata"
+    );
+  }
+  const resolved = resolveSession(db, params.sessionId);
+  const mapRunNumber = params.mapRun ?? resolved.current_map_run;
+  const mapMetaPath = join16(
+    resolved.session_dir,
+    "map",
+    "runs",
+    `run-${mapRunNumber}`,
+    "map-meta.json"
+  );
+  const already = db.exec(
+    `SELECT 1 FROM orchestration_events
+       WHERE session_id = ? AND event_type = 'map_completed' AND round = ? LIMIT 1`,
+    [resolved.id, mapRunNumber]
+  );
+  if ((already[0]?.values.length ?? 0) > 0) {
+    return { sessionId: resolved.id, mapRun: mapRunNumber, metaPath: mapMetaPath, schema_version: 1 };
+  }
+  if (resolved.current_phase !== "synthesis") {
+    throw new StateError(
+      STATE_EXIT.INVARIANT_UNMET,
+      `Cannot complete map: workflow is at "${resolved.current_phase}", not "synthesis". Advance first.`
+    );
+  }
   let metaPath;
   if (params.source === "stdin") {
-    const runDir = join15(session.session_dir, "map", "runs", `run-${mapRunNumber}`);
+    const runDir = join16(resolved.session_dir, "map", "runs", `run-${mapRunNumber}`);
     mkdirSync5(runDir, { recursive: true });
-    metaPath = join15(runDir, "map-meta.json");
-    writeFileSync8(metaPath, JSON.stringify(meta, null, 2));
-  }
-  insertEvent(db, {
-    session_id: session.id,
-    event_type: "map_completed",
-    phase: "synthesis",
-    phase_number: 5,
-    round: mapRunNumber,
-    metadata: JSON.stringify({
-      section_count: counts.sectionCount,
-      file_count: counts.fileCount,
-      source: "orchestrator"
-    })
+    metaPath = mapMetaPath;
+    writeFileSync7(metaPath, JSON.stringify(meta, null, 2));
+  }
+  db.transaction(() => {
+    insertEvent(db, {
+      session_id: resolved.id,
+      event_type: "map_completed",
+      phase: "synthesis",
+      phase_number: 5,
+      round: mapRunNumber,
+      metadata: JSON.stringify({
+        section_count: counts.sectionCount,
+        file_count: counts.fileCount,
+        source: "orchestrator"
+      })
+    });
+    validatePhaseTransition("map", resolved.current_phase, "complete", false);
+    updateSession(db, resolved.id, { current_phase: "complete", phase_number: 6 });
+    insertEvent(db, {
+      session_id: resolved.id,
+      event_type: "phase_transition",
+      phase: "complete",
+      phase_number: 6,
+      round: mapRunNumber
+    });
   });
-  saveDatabase(db, dbPath);
-  return { sessionId: session.id, mapRun: mapRunNumber, metaPath };
+  return { sessionId: resolved.id, mapRun: mapRunNumber, metaPath, schema_version: 1 };
+}
+async function stateStatus(ocrDir, sessionId) {
+  const db = await ensureDatabase(ocrDir);
+  const resolved = resolveSession(db, sessionId);
+  const view = db.exec(
+    `SELECT completeness_state, has_terminal_artifact, marked_closed, dependents_settled
+       FROM session_completeness WHERE session_id = ?`,
+    [resolved.id]
+  );
+  const row = view[0]?.values[0];
+  const completenessState = row?.[0] ?? null;
+  const hasTerminalArtifact = row?.[1] === 1;
+  let nextAction;
+  let nextActionKind;
+  switch (completenessState) {
+    case "complete":
+      nextAction = "none \u2014 session is complete";
+      nextActionKind = "none";
+      break;
+    case "closed_without_artifact":
+      nextAction = "re-open and finalize: this session was closed without a completed round/run";
+      nextActionKind = "reopen";
+      break;
+    case "in_flight":
+      nextAction = "wait for in-flight agent processes to finish";
+      nextActionKind = "wait";
+      break;
+    default:
+      if (hasTerminalArtifact) {
+        nextAction = "run 'ocr state finish' to close the workflow";
+        nextActionKind = "finish";
+      } else if (resolved.current_phase === "synthesis") {
+        nextAction = "pipe round metadata to 'ocr state complete-round --stdin'";
+        nextActionKind = "complete_round";
+      } else {
+        nextAction = "advance through the phases, then 'ocr state complete-round'";
+        nextActionKind = "advance";
+      }
+  }
+  return {
+    schema_version: 1,
+    session_id: resolved.id,
+    workflow_type: resolved.workflow_type,
+    status: resolved.status,
+    current_phase: resolved.current_phase,
+    current_round: resolved.current_round,
+    current_map_run: resolved.current_map_run,
+    completeness_state: completenessState,
+    has_terminal_artifact: hasTerminalArtifact,
+    marked_closed: row?.[2] === 1,
+    dependents_settled: row?.[3] === 1,
+    next_action: nextAction,
+    next_action_kind: nextActionKind
+  };
 }
 async function stateSync(ocrDir) {
   const db = await ensureDatabase(ocrDir);
-  const dbPath = join15(ocrDir, "data", "ocr.db");
-  const sessionsRoot = join15(ocrDir, "sessions");
-  if (!existsSync13(sessionsRoot)) {
+  const sessionsRoot = join16(ocrDir, "sessions");
+  if (!existsSync14(sessionsRoot)) {
     return 0;
   }
   const entries = readdirSync6(sessionsRoot).filter((name) => {
-    const fullPath = join15(sessionsRoot, name);
-    return statSync2(fullPath).isDirectory();
+    const fullPath = join16(sessionsRoot, name);
+    return statSync3(fullPath).isDirectory();
   });
   let synced = 0;
   for (const dirName of entries) {
-    const dirPath = join15(sessionsRoot, dirName);
+    const dirPath = join16(sessionsRoot, dirName);
     const existing = getSession(db, dirName);
     if (existing) {
       continue;
@@ -33190,28 +34337,41 @@ async function stateSync(ocrDir) {
     if (!hasArtifacts(dirPath)) {
       continue;
     }
-    const hasRoundsDir = existsSync13(join15(dirPath, "rounds"));
-    const hasMapDir = existsSync13(join15(dirPath, "map"));
+    const hasRoundsDir = existsSync14(join16(dirPath, "rounds"));
+    const hasMapDir = existsSync14(join16(dirPath, "map"));
     const workflowType = hasMapDir && !hasRoundsDir ? "map" : "review";
     const branchMatch = dirName.match(/^\d{4}-\d{2}-\d{2}-(.+)$/);
     const branch = branchMatch?.[1] ?? dirName;
     let inferredPhase = "context";
+    let inferredPhaseNumber = 1;
+    let inferredRound = 1;
+    let inferredMapRun = 1;
     if (workflowType === "review") {
-      const roundsDir = join15(dirPath, "rounds");
-      if (existsSync13(roundsDir)) {
-        const roundDirs = readdirSync6(roundsDir).filter((d) => /^round-\d+$/.test(d)).sort((a, b) => parseInt(a.replace(/^\D+-/, ""), 10) - parseInt(b.replace(/^\D+-/, ""), 10));
-        const latestRound = roundDirs[roundDirs.length - 1];
-        if (latestRound && existsSync13(join15(roundsDir, latestRound, "final.md"))) {
-          inferredPhase = "complete";
+      const roundsDir = join16(dirPath, "rounds");
+      if (existsSync14(roundsDir)) {
+        const roundDirs = readdirSync6(roundsDir).filter((d) => /^round-\d+$/.test(d)).map((d) => parseInt(d.replace("round-", ""), 10)).filter((n) => Number.isFinite(n)).sort((a, b) => a - b);
+        const latestRoundNum = roundDirs[roundDirs.length - 1];
+        if (latestRoundNum !== void 0) {
+          inferredRound = latestRoundNum;
+          if (existsSync14(
+            join16(roundsDir, `round-${latestRoundNum}`, "final.md")
+          )) {
+            inferredPhase = "complete";
+            inferredPhaseNumber = 8;
+          }
         }
       }
     } else if (workflowType === "map") {
-      const runsDir = join15(dirPath, "map", "runs");
-      if (existsSync13(runsDir)) {
-        const runDirs = readdirSync6(runsDir).filter((d) => /^run-\d+$/.test(d)).sort((a, b) => parseInt(a.replace(/^\D+-/, ""), 10) - parseInt(b.replace(/^\D+-/, ""), 10));
-        const latestRun = runDirs[runDirs.length - 1];
-        if (latestRun && existsSync13(join15(runsDir, latestRun, "map.md"))) {
-          inferredPhase = "complete";
+      const runsDir = join16(dirPath, "map", "runs");
+      if (existsSync14(runsDir)) {
+        const runDirs = readdirSync6(runsDir).filter((d) => /^run-\d+$/.test(d)).map((d) => parseInt(d.replace("run-", ""), 10)).filter((n) => Number.isFinite(n)).sort((a, b) => a - b);
+        const latestRunNum = runDirs[runDirs.length - 1];
+        if (latestRunNum !== void 0) {
+          inferredMapRun = latestRunNum;
+          if (existsSync14(join16(runsDir, `run-${latestRunNum}`, "map.md"))) {
+            inferredPhase = "complete";
+            inferredPhaseNumber = 6;
+          }
         }
       }
     }
@@ -33220,35 +34380,36 @@ async function stateSync(ocrDir) {
       branch,
       workflow_type: workflowType,
       current_phase: inferredPhase,
-      phase_number: 1,
-      current_round: 1,
-      current_map_run: 1,
+      phase_number: inferredPhaseNumber,
+      current_round: inferredRound,
+      current_map_run: inferredMapRun,
       session_dir: dirPath
     });
-    updateSession(db, dirName, { status: "closed" });
-    insertEvent(db, {
-      session_id: dirName,
-      event_type: "session_synced",
-      phase: inferredPhase,
-      phase_number: 1,
-      metadata: JSON.stringify({ source: "filesystem_backfill" })
-    });
+    commitReasonClose(
+      db,
+      dirName,
+      {
+        event_type: "session_synced",
+        phase: inferredPhase,
+        phase_number: 1,
+        metadata: JSON.stringify({ source: "filesystem_backfill" })
+      },
+      { status: "closed" }
+    );
     synced++;
   }
-  if (synced > 0) {
-    saveDatabase(db, dbPath);
-  }
   return synced;
 }
 
 // src/commands/state.ts
 init_command_log();
 init_db();
+init_db();
 function readDashboardSpawnMarker(ocrDir) {
-  const path2 = join16(ocrDir, "data", "dashboard-active-spawn.json");
+  const path2 = join17(ocrDir, "data", "dashboard-active-spawn.json");
   let raw;
   try {
-    raw = readFileSync12(path2, "utf-8");
+    raw = readFileSync11(path2, "utf-8");
   } catch {
     return null;
   }
@@ -33280,143 +34441,37 @@ async function readStdin() {
   }
   return data;
 }
-var initSubcommand = new Command("init").description("Initialize a new OCR session").requiredOption("--session-id <id>", "Session ID").requiredOption("--branch <branch>", "Branch name").requiredOption(
-  "--workflow-type <type>",
-  "Workflow type (review or map)",
-  (value) => {
-    if (value !== "review" && value !== "map") {
-      throw new Error(
-        `Invalid workflow type: "${value}". Must be "review" or "map".`
-      );
-    }
-    return value;
-  }
-).option("--session-dir <dir>", "Session directory path (auto-resolved if omitted)").option(
-  "--dashboard-uid <uid>",
-  "Dashboard command_executions uid to link this workflow to. Takes precedence over the OCR_DASHBOARD_EXECUTION_UID env var so AI shells that strip env vars can still wire the linkage."
-).action(
-  async (options) => {
-    const targetDir = process.cwd();
-    requireOcrSetup(targetDir);
-    const ocrDir = join16(targetDir, ".ocr");
-    const sessionDir = options.sessionDir ?? join16(ocrDir, "sessions", options.sessionId);
-    if (!existsSync14(sessionDir)) {
-      mkdirSync6(sessionDir, { recursive: true });
-    }
-    try {
-      const sessionId = await stateInit({
-        sessionId: options.sessionId,
-        branch: options.branch,
-        workflowType: options.workflowType,
-        sessionDir,
-        ocrDir
-      });
-      const markerUid = readDashboardSpawnMarker(ocrDir)?.execution_uid;
-      const dashboardUid = options.dashboardUid ?? process.env["OCR_DASHBOARD_EXECUTION_UID"] ?? markerUid;
-      if (dashboardUid) {
-        try {
-          const db = await getDb(ocrDir);
-          linkDashboardInvocationToWorkflow(db, dashboardUid, sessionId);
-          saveDatabase(db, join16(ocrDir, "data", "ocr.db"));
-          console.error(
-            source_default.gray(
-              `[state init] linked workflow_id=${sessionId} \u2192 dashboard uid=${dashboardUid}`
-            )
-          );
-        } catch (linkErr) {
-          console.error(
-            source_default.yellow(
-              `Warning: failed to link dashboard command_execution to session: ${linkErr instanceof Error ? linkErr.message : String(linkErr)}`
-            )
-          );
-        }
-      } else {
-        console.error(
-          source_default.gray(
-            `[state init] no dashboard linkage available (flag, env var, and marker file all absent \u2014 CLI-only invocation)`
-          )
-        );
-      }
-      console.log(sessionId);
-    } catch (error) {
-      console.error(
-        source_default.red(
-          `Error: ${error instanceof Error ? error.message : "Failed to initialize session"}`
-        )
-      );
-      process.exit(1);
-    }
-  }
-);
-var transitionSubcommand = new Command("transition").description("Transition session to a new phase").option("--session-id <id>", "Session ID (auto-detects latest active if omitted)").requiredOption("--phase <phase>", "Target phase name").requiredOption("--phase-number <number>", "Phase number", parseInt).option("--current-round <number>", "Round number", parseInt).option("--current-map-run <number>", "Map run number", parseInt).action(
-  async (options) => {
-    const targetDir = process.cwd();
-    requireOcrSetup(targetDir);
-    const ocrDir = join16(targetDir, ".ocr");
-    const VALID_PHASES = /* @__PURE__ */ new Set([
-      "context",
-      "change-context",
-      "analysis",
-      "reviews",
-      "aggregation",
-      "discourse",
-      "synthesis",
-      "complete",
-      "map-context",
-      "topology",
-      "flow-analysis",
-      "requirements-mapping"
-    ]);
-    if (!VALID_PHASES.has(options.phase)) {
-      throw new Error(`Invalid phase: "${options.phase}". Must be one of: ${[...VALID_PHASES].join(", ")}`);
-    }
-    try {
-      const sessionId = options.sessionId ?? (await resolveActiveSession(ocrDir)).id;
-      await stateTransition({
-        sessionId,
-        phase: options.phase,
-        phaseNumber: options.phaseNumber,
-        round: options.currentRound,
-        mapRun: options.currentMapRun,
-        ocrDir
-      });
-      console.log(
-        `${sessionId}: ${options.phase} (phase ${options.phaseNumber})`
-      );
-    } catch (error) {
-      console.error(
-        source_default.red(
-          `Error: ${error instanceof Error ? error.message : "Failed to transition"}`
-        )
-      );
-      process.exit(1);
-    }
+async function linkDashboardInvocation(ocrDir, sessionId, explicitUid, label) {
+  const markerUid = readDashboardSpawnMarker(ocrDir)?.execution_uid;
+  const dashboardUid = explicitUid ?? process.env["OCR_DASHBOARD_EXECUTION_UID"] ?? markerUid;
+  if (!dashboardUid) {
+    console.error(
+      source_default.gray(
+        `[state ${label}] no dashboard linkage available (flag, env var, and marker file all absent \u2014 CLI-only invocation)`
+      )
+    );
+    return;
   }
-);
-var closeSubcommand = new Command("close").description("Close a session").option("--session-id <id>", "Session ID (auto-detects latest active if omitted)").action(async (options) => {
-  const targetDir = process.cwd();
-  requireOcrSetup(targetDir);
-  const ocrDir = join16(targetDir, ".ocr");
   try {
-    const sessionId = options.sessionId ?? (await resolveActiveSession(ocrDir)).id;
-    await stateClose({
-      sessionId,
-      ocrDir
-    });
-    console.log(`${sessionId}: closed`);
-  } catch (error) {
+    const db = await getDb(ocrDir);
+    linkDashboardInvocationToWorkflow(db, dashboardUid, sessionId);
     console.error(
-      source_default.red(
-        `Error: ${error instanceof Error ? error.message : "Failed to close session"}`
+      source_default.gray(
+        `[state ${label}] linked workflow_id=${sessionId} \u2192 dashboard uid=${dashboardUid}`
+      )
+    );
+  } catch (linkErr) {
+    console.error(
+      source_default.yellow(
+        `Warning: failed to link dashboard command_execution to session: ${linkErr instanceof Error ? linkErr.message : String(linkErr)}`
       )
     );
-    process.exit(1);
   }
-});
+}
 var showSubcommand = new Command("show").description("Show current session state").option("--session-id <id>", "Session ID (defaults to latest active)").option("--json", "Output as JSON").action(async (options) => {
   const targetDir = process.cwd();
   requireOcrSetup(targetDir);
-  const ocrDir = join16(targetDir, ".ocr");
+  const ocrDir = join17(targetDir, ".ocr");
   try {
     const result = await stateShow(ocrDir, options.sessionId);
     if (!result) {
@@ -33485,7 +34540,7 @@ var showSubcommand = new Command("show").description("Show current session state
 var syncSubcommand = new Command("sync").description("Rebuild session state from filesystem artifacts").action(async () => {
   const targetDir = process.cwd();
   requireOcrSetup(targetDir);
-  const ocrDir = join16(targetDir, ".ocr");
+  const ocrDir = join17(targetDir, ".ocr");
   try {
     const synced = await stateSync(ocrDir);
     console.log(`Synced ${synced} session${synced !== 1 ? "s" : ""} from filesystem.`);
@@ -33495,7 +34550,6 @@ var syncSubcommand = new Command("sync").description("Rebuild session state from
     if (totalCmds === 0) {
       const recovered = replayCommandLog(db, ocrDir);
       if (recovered > 0) {
-        saveDatabase(db, join16(ocrDir, "data", "ocr.db"));
         console.log(`Recovered ${recovered} command${recovered !== 1 ? "s" : ""} from backup log.`);
       }
     }
@@ -33508,123 +34562,216 @@ var syncSubcommand = new Command("sync").description("Rebuild session state from
     process.exit(1);
   }
 });
-var roundCompleteSubcommand = new Command("round-complete").description("Import structured round data into SQLite").option("--file <path>", "Path to round-meta.json").option("--stdin", "Read round-meta JSON from stdin (recommended)").option("--session-id <id>", "Session ID (auto-detects latest active if omitted)").option("--round <number>", "Round number (auto-detects current if omitted)", parseInt).action(
+var reconcileSubcommand = new Command("reconcile").description(
+  "Heal legacy/drifted session state by deriving truth from events + artifacts"
+).option("--dry-run", "Print the repair plan without writing anything").option("--json", "Output the result as JSON").action(async (options) => {
+  const targetDir = process.cwd();
+  requireOcrSetup(targetDir);
+  const ocrDir = join17(targetDir, ".ocr");
+  try {
+    const db = await ensureDatabase(ocrDir);
+    const result = reconcileLegacyState(db, ocrDir, { dryRun: options.dryRun });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const repairs = result.actions.filter((a) => a.kind !== "ok");
+    if (repairs.length === 0) {
+      console.log(source_default.dim("Nothing to reconcile \u2014 all sessions consistent."));
+      return;
+    }
+    console.log(
+      result.dryRun ? source_default.bold(`Reconciliation plan (${repairs.length} change(s), dry run):`) : source_default.bold(`Reconciled ${repairs.length} session(s):`)
+    );
+    for (const a of repairs) {
+      console.log(`  ${source_default.cyan(a.kind)}  ${a.sessionId}`);
+      console.log(`    ${source_default.dim(a.detail)}`);
+    }
+  } catch (error) {
+    console.error(
+      source_default.red(
+        `Error: ${error instanceof Error ? error.message : "Failed to reconcile"}`
+      )
+    );
+    process.exit(1);
+  }
+});
+function exitFromStateError(error, fallback2) {
+  if (error instanceof StateError) {
+    console.error(source_default.red(`Error: ${error.message}`));
+    process.exit(error.code);
+  }
+  if (isBusyError(error)) {
+    console.error(
+      source_default.red(
+        `Error: database is busy (locked past retry budget): ${error instanceof Error ? error.message : String(error)}`
+      )
+    );
+    process.exit(STATE_EXIT.BUSY);
+  }
+  console.error(
+    source_default.red(`Error: ${error instanceof Error ? error.message : fallback2}`)
+  );
+  process.exit(1);
+}
+var beginSubcommand = new Command("begin").description("Start or resume a workflow and report where it stands").requiredOption("--session-id <id>", "Session ID").requiredOption("--branch <branch>", "Branch name").requiredOption("--workflow-type <type>", "Workflow type (review or map)", (v) => {
+  if (v !== "review" && v !== "map") {
+    throw new Error(`Invalid workflow type: "${v}". Must be "review" or "map".`);
+  }
+  return v;
+}).option("--session-dir <dir>", "Session directory path (auto-resolved if omitted)").option(
+  "--dashboard-uid <uid>",
+  "Dashboard command_executions uid to link this workflow to (takes precedence over OCR_DASHBOARD_EXECUTION_UID)"
+).option("--json", "Output the result as JSON").action(
   async (options) => {
     const targetDir = process.cwd();
     requireOcrSetup(targetDir);
-    const ocrDir = join16(targetDir, ".ocr");
-    if (!options.file && !options.stdin) {
-      console.error(source_default.red("Error: Provide either --file <path> or --stdin"));
-      process.exit(1);
-    }
-    if (options.file && options.stdin) {
-      console.error(source_default.red("Error: --file and --stdin are mutually exclusive"));
-      process.exit(1);
-    }
+    const ocrDir = join17(targetDir, ".ocr");
+    const sessionDir = options.sessionDir ?? join17(ocrDir, "sessions", options.sessionId);
+    if (!existsSync15(sessionDir)) mkdirSync6(sessionDir, { recursive: true });
     try {
-      let result;
-      if (options.stdin) {
-        const data = await readStdin();
-        result = await stateRoundComplete({
-          source: "stdin",
-          ocrDir,
-          data,
-          sessionId: options.sessionId,
-          round: options.round
-        });
-      } else if (options.file) {
-        result = await stateRoundComplete({
-          source: "file",
-          ocrDir,
-          filePath: options.file,
-          sessionId: options.sessionId,
-          round: options.round
-        });
-      } else {
-        process.exit(1);
-      }
-      console.log(source_default.green("Round data imported successfully."));
-      if (result.metaPath) {
-        console.log(source_default.dim(`Wrote ${result.metaPath}`));
-      }
-    } catch (error) {
-      console.error(
-        source_default.red(
-          `Error: ${error instanceof Error ? error.message : "Failed to import round data"}`
-        )
+      const result = await stateBegin({
+        sessionId: options.sessionId,
+        branch: options.branch,
+        workflowType: options.workflowType,
+        sessionDir,
+        ocrDir
+      });
+      await linkDashboardInvocation(ocrDir, result.session_id, options.dashboardUid, "begin");
+      console.log(
+        options.json ? JSON.stringify(result, null, 2) : `${result.session_id}: round ${result.round}, phase ${result.phase} (${result.completeness ?? "unknown"})`
       );
-      process.exit(1);
+    } catch (error) {
+      exitFromStateError(error, "Failed to begin session");
     }
   }
 );
-var mapCompleteSubcommand = new Command("map-complete").description("Import structured map run data into SQLite").option("--file <path>", "Path to map-meta.json").option("--stdin", "Read map-meta JSON from stdin (recommended)").option("--session-id <id>", "Session ID (auto-detects latest active if omitted)").option("--map-run <number>", "Map run number (auto-detects current if omitted)", parseInt).action(
+var advanceSubcommand = new Command("advance").description("Advance the workflow to a phase (graph-validated; phase number derived)").requiredOption("--phase <phase>", "Target phase name").option("--session-id <id>", "Session ID (auto-detects active if omitted)").option("--current-round <number>", "Round number", parseInt).option("--current-map-run <number>", "Map run number", parseInt).option("--phase-number <number>", "(ignored \u2014 derived from --phase)", parseInt).action(
   async (options) => {
     const targetDir = process.cwd();
     requireOcrSetup(targetDir);
-    const ocrDir = join16(targetDir, ".ocr");
-    if (!options.file && !options.stdin) {
-      console.error(source_default.red("Error: Provide either --file <path> or --stdin"));
-      process.exit(1);
-    }
-    if (options.file && options.stdin) {
-      console.error(source_default.red("Error: --file and --stdin are mutually exclusive"));
-      process.exit(1);
+    const ocrDir = join17(targetDir, ".ocr");
+    try {
+      const { id: sessionId } = await resolveActiveSession(ocrDir, options.sessionId);
+      await stateAdvance({
+        sessionId,
+        phase: options.phase,
+        round: options.currentRound,
+        mapRun: options.currentMapRun,
+        ocrDir
+      });
+      console.log(`${sessionId}: ${options.phase}`);
+    } catch (error) {
+      exitFromStateError(error, "Failed to advance");
     }
+  }
+);
+var completeRoundSubcommand = new Command("complete-round").description("Atomically finalize a review round (validate + record + transition)").option("--session-id <id>", "Session ID (auto-detects active if omitted)").option("--round <number>", "Round number (defaults to current)", parseInt).option("--stdin", "Read round metadata JSON from stdin").option("--file <path>", "Read round metadata JSON from a file").option("--require-final", "Require rounds/round-N/final.md to exist").option("--json", "Output the result as JSON").action(
+  async (options) => {
+    const targetDir = process.cwd();
+    requireOcrSetup(targetDir);
+    const ocrDir = join17(targetDir, ".ocr");
     try {
-      let result;
-      if (options.stdin) {
-        const data = await readStdin();
-        result = await stateMapComplete({
-          source: "stdin",
-          ocrDir,
-          data,
-          sessionId: options.sessionId,
-          mapRun: options.mapRun
-        });
-      } else if (options.file) {
-        result = await stateMapComplete({
-          source: "file",
-          ocrDir,
-          filePath: options.file,
-          sessionId: options.sessionId,
-          mapRun: options.mapRun
-        });
-      } else {
-        process.exit(1);
-      }
-      console.log(source_default.green("Map data imported successfully."));
-      if (result.metaPath) {
-        console.log(source_default.dim(`Wrote ${result.metaPath}`));
-      }
+      const base = options.stdin ? { source: "stdin", data: await readStdin() } : options.file ? { source: "file", filePath: options.file } : (() => {
+        throw new StateError(STATE_EXIT.USAGE, "Provide --stdin or --file with round metadata");
+      })();
+      const result = await stateCompleteRound({
+        ...base,
+        ocrDir,
+        sessionId: options.sessionId,
+        round: options.round,
+        requireFinal: options.requireFinal
+      });
+      console.log(
+        options.json ? JSON.stringify(result, null, 2) : `${result.sessionId}: round ${result.round} complete`
+      );
     } catch (error) {
-      console.error(
-        source_default.red(
-          `Error: ${error instanceof Error ? error.message : "Failed to import map data"}`
-        )
+      exitFromStateError(error, "Failed to complete round");
+    }
+  }
+);
+var completeMapSubcommand = new Command("complete-map").description("Atomically finalize a map run (validate + record + transition)").option("--session-id <id>", "Session ID (auto-detects active if omitted)").option("--map-run <number>", "Map run number (defaults to current)", parseInt).option("--stdin", "Read map metadata JSON from stdin").option("--file <path>", "Read map metadata JSON from a file").option("--json", "Output the result as JSON").action(
+  async (options) => {
+    const targetDir = process.cwd();
+    requireOcrSetup(targetDir);
+    const ocrDir = join17(targetDir, ".ocr");
+    try {
+      const base = options.stdin ? { source: "stdin", data: await readStdin() } : options.file ? { source: "file", filePath: options.file } : (() => {
+        throw new StateError(STATE_EXIT.USAGE, "Provide --stdin or --file with map metadata");
+      })();
+      const result = await stateCompleteMap({
+        ...base,
+        ocrDir,
+        sessionId: options.sessionId,
+        mapRun: options.mapRun
+      });
+      console.log(
+        options.json ? JSON.stringify(result, null, 2) : `${result.sessionId}: map run ${result.mapRun} complete`
       );
-      process.exit(1);
+    } catch (error) {
+      exitFromStateError(error, "Failed to complete map");
     }
   }
 );
-var stateCommand = new Command("state").description("Manage OCR session state").addCommand(initSubcommand).addCommand(transitionSubcommand).addCommand(closeSubcommand).addCommand(showSubcommand).addCommand(syncSubcommand).addCommand(roundCompleteSubcommand).addCommand(mapCompleteSubcommand);
+var finishSubcommand = new Command("finish").description("Close a workflow (refuses unless the current round/run is complete)").option("--session-id <id>", "Session ID (auto-detects active if omitted)").option("--abort", "Abandon the session \u2014 records a distinct, non-success terminal").action(async (options) => {
+  const targetDir = process.cwd();
+  requireOcrSetup(targetDir);
+  const ocrDir = join17(targetDir, ".ocr");
+  try {
+    const { id: sessionId } = await resolveActiveSession(ocrDir, options.sessionId);
+    await stateClose({ sessionId, ocrDir, abort: options.abort });
+    console.log(`${sessionId}: ${options.abort ? "aborted" : "finished"}`);
+  } catch (error) {
+    exitFromStateError(error, "Failed to finish");
+  }
+});
+var statusSubcommand = new Command("status").description("Report whether a session is complete and, if not, what's missing").option("--session-id <id>", "Session ID (auto-detects active if omitted)").option("--json", "Output the result as JSON").action(async (options) => {
+  const targetDir = process.cwd();
+  requireOcrSetup(targetDir);
+  const ocrDir = join17(targetDir, ".ocr");
+  try {
+    const result = await stateStatus(ocrDir, options.sessionId);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`${result.session_id}: ${result.completeness_state}`);
+      console.log(source_default.dim(`  next: ${result.next_action}`));
+    }
+  } catch (error) {
+    exitFromStateError(error, "Failed to read status");
+  }
+});
+var RETIRED_STATE_VERBS = {
+  init: "begin",
+  transition: "advance",
+  "round-complete": "complete-round",
+  "map-complete": "complete-map",
+  close: "finish"
+};
+var stateCommand = new Command("state").description("Manage OCR session state").addCommand(beginSubcommand).addCommand(advanceSubcommand).addCommand(completeRoundSubcommand).addCommand(completeMapSubcommand).addCommand(finishSubcommand).addCommand(statusSubcommand).addCommand(showSubcommand).addCommand(syncSubcommand).addCommand(reconcileSubcommand).showSuggestionAfterError(false).on("command:*", (operands) => {
+  const verb = operands[0] ?? "";
+  const replacement = RETIRED_STATE_VERBS[verb];
+  const msg = replacement ? `'ocr state ${verb}' was retired in v2.0 \u2014 use 'ocr state ${replacement}'. See 'ocr state --help'.` : `Unknown 'ocr state' subcommand: '${verb}'. See 'ocr state --help'.`;
+  exitFromStateError(new StateError(STATE_EXIT.USAGE, msg), msg);
+});
 
 // src/commands/session.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
-import { join as join18 } from "node:path";
+import { join as join19 } from "node:path";
 init_db();
 
 // src/lib/runtime-config.ts
-import { existsSync as existsSync15, readFileSync as readFileSync13 } from "node:fs";
-import { join as join17 } from "node:path";
+import { existsSync as existsSync16, readFileSync as readFileSync12 } from "node:fs";
+import { join as join18 } from "node:path";
 var DEFAULT_AGENT_HEARTBEAT_SECONDS = 60;
 function getAgentHeartbeatSeconds(ocrDir) {
-  const configPath = join17(ocrDir, "config.yaml");
-  if (!existsSync15(configPath)) {
+  const configPath = join18(ocrDir, "config.yaml");
+  if (!existsSync16(configPath)) {
     return DEFAULT_AGENT_HEARTBEAT_SECONDS;
   }
   let content;
   try {
-    content = readFileSync13(configPath, "utf-8");
+    content = readFileSync12(configPath, "utf-8");
   } catch {
     return DEFAULT_AGENT_HEARTBEAT_SECONDS;
   }
@@ -33663,16 +34810,18 @@ function fail(message) {
 async function setup() {
   const targetDir = process.cwd();
   requireOcrSetup(targetDir);
-  const ocrDir = join18(targetDir, ".ocr");
-  const dbPath = join18(ocrDir, "data", "ocr.db");
-  return { ocrDir, dbPath };
+  const ocrDir = join19(targetDir, ".ocr");
+  return { ocrDir };
 }
 var startInstanceSubcommand = new Command("start-instance").description("Journal a new agent-CLI process spawned for the active review").option("--workflow <id>", "Workflow session id (auto-detects active if omitted)").option("--persona <name>", "Reviewer persona, e.g. 'principal'").option("--instance <number>", "Instance index within (workflow, persona)", parseInt).option("--name <name>", "Human-friendly name (default: '{persona}-{instance}')").requiredOption("--vendor <vendor>", "Underlying CLI vendor (e.g. 'claude', 'opencode')").option("--model <id>", "Resolved model id passed to the CLI's --model flag").option("--phase <phase>", "Workflow phase this instance is doing").option("--pid <pid>", "Process id of the spawned process", parseInt).option("--note <text>", "Free-form note to attach").action(
   async (options) => {
-    const { ocrDir, dbPath } = await setup();
+    const { ocrDir } = await setup();
     const db = await ensureDatabase(ocrDir);
     try {
-      const workflowId = options.workflow ?? (await resolveActiveSession(ocrDir)).id;
+      const { id: workflowId } = await resolveActiveSession(
+        ocrDir,
+        options.workflow
+      );
       const id = randomUUID3();
       const persona = options.persona ?? null;
       const instanceIndex = options.instance ?? null;
@@ -33691,7 +34840,6 @@ var startInstanceSubcommand = new Command("start-instance").description("Journal
         pid: options.pid ?? null,
         notes: options.note ?? null
       });
-      saveDatabase(db, dbPath);
       console.log(id);
     } catch (error) {
       fail(error instanceof Error ? error.message : "Failed to start agent session");
@@ -33699,18 +34847,17 @@ var startInstanceSubcommand = new Command("start-instance").description("Journal
   }
 );
 var bindVendorIdSubcommand = new Command("bind-vendor-id").description("Bind the underlying CLI's session id to an OCR agent session").argument("<agent-session-id>", "OCR agent session id").argument("<vendor-session-id>", "Underlying CLI's session id").action(async (agentId, vendorId) => {
-  const { ocrDir, dbPath } = await setup();
+  const { ocrDir } = await setup();
   const db = await ensureDatabase(ocrDir);
   try {
     setAgentSessionVendorId(db, agentId, vendorId);
-    saveDatabase(db, dbPath);
     console.log(`${agentId}: vendor_session_id=${vendorId}`);
   } catch (error) {
     fail(error instanceof Error ? error.message : "Failed to bind vendor session id");
   }
 });
 var beatSubcommand = new Command("beat").description("Bump last_heartbeat_at on an agent session").argument("<agent-session-id>", "OCR agent session id").action(async (agentId) => {
-  const { ocrDir, dbPath } = await setup();
+  const { ocrDir } = await setup();
   const db = await ensureDatabase(ocrDir);
   try {
     const existing = getAgentSession(db, agentId);
@@ -33718,7 +34865,6 @@ var beatSubcommand = new Command("beat").description("Bump last_heartbeat_at on
       fail(`Agent session not found: ${agentId}`);
     }
     bumpAgentSessionHeartbeat(db, agentId);
-    saveDatabase(db, dbPath);
     console.log(`${agentId}: heartbeat`);
   } catch (error) {
     fail(error instanceof Error ? error.message : "Failed to bump heartbeat");
@@ -33729,7 +34875,7 @@ var endInstanceSubcommand = new Command("end-instance").description("Transition
   "Terminal status (done | crashed | cancelled). Default inferred from --exit-code (0 \u2192 done, non-zero \u2192 crashed)"
 ).option("--exit-code <code>", "Process exit code", parseInt).option("--note <text>", "Free-form note to append").action(
   async (agentId, options) => {
-    const { ocrDir, dbPath } = await setup();
+    const { ocrDir } = await setup();
     const db = await ensureDatabase(ocrDir);
     try {
       const existing = getAgentSession(db, agentId);
@@ -33760,7 +34906,6 @@ var endInstanceSubcommand = new Command("end-instance").description("Transition
         exitCode: options.exitCode ?? null,
         note: options.note
       });
-      saveDatabase(db, dbPath);
       console.log(`${agentId}: ${status}`);
     } catch (error) {
       fail(error instanceof Error ? error.message : "Failed to end agent session");
@@ -33771,7 +34916,10 @@ var listSubcommand = new Command("list").description("List agent sessions for a
   const { ocrDir } = await setup();
   const db = await ensureDatabase(ocrDir);
   try {
-    const workflowId = options.workflow ?? (await resolveActiveSession(ocrDir)).id;
+    const { id: workflowId } = await resolveActiveSession(
+      ocrDir,
+      options.workflow
+    );
     const rows = listAgentSessionsForWorkflow(db, workflowId);
     if (options.json) {
       console.log(JSON.stringify(rows, null, 2));
@@ -33917,8 +35065,8 @@ var modelsCommand = new Command("models").description("Inspect models available
 
 // src/commands/team.ts
 var import_yaml2 = __toESM(require_dist(), 1);
-import { existsSync as existsSync16, readFileSync as readFileSync14, writeFileSync as writeFileSync9 } from "node:fs";
-import { join as join19 } from "node:path";
+import { existsSync as existsSync17, readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "node:fs";
+import { join as join20 } from "node:path";
 async function readStdin2() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -33977,7 +35125,7 @@ var resolveSubcommand = new Command("resolve").description("Resolve and print th
   async (options) => {
     const targetDir = process.cwd();
     requireOcrSetup(targetDir);
-    const ocrDir = join19(targetDir, ".ocr");
+    const ocrDir = join20(targetDir, ".ocr");
     try {
       const { team } = loadTeamConfig(ocrDir);
       let override;
@@ -34016,8 +35164,8 @@ var setSubcommand = new Command("set").description("Persist a new default_team c
   }
   const targetDir = process.cwd();
   requireOcrSetup(targetDir);
-  const ocrDir = join19(targetDir, ".ocr");
-  const configPath = join19(ocrDir, "config.yaml");
+  const ocrDir = join20(targetDir, ".ocr");
+  const configPath = join20(ocrDir, "config.yaml");
   try {
     const raw = await readStdin2();
     const team = parseSessionOverride(raw);
@@ -34027,17 +35175,17 @@ var setSubcommand = new Command("set").description("Persist a new default_team c
       list.push(inst);
       byPersona.set(inst.persona, list);
     }
-    const doc = existsSync16(configPath) ? (0, import_yaml2.parseDocument)(readFileSync14(configPath, "utf-8")) : new import_yaml2.Document({});
+    const doc = existsSync17(configPath) ? (0, import_yaml2.parseDocument)(readFileSync13(configPath, "utf-8")) : new import_yaml2.Document({});
     applyDefaultTeamSurgically(doc, byPersona);
     const yamlOutput = doc.toString({ lineWidth: 0 });
-    writeFileSync9(configPath, yamlOutput, "utf-8");
-    const reviewersDir = join19(ocrDir, "skills", "references", "reviewers");
-    const metaPath = join19(ocrDir, "reviewers-meta.json");
+    writeFileSync8(configPath, yamlOutput, "utf-8");
+    const reviewersDir = join20(ocrDir, "skills", "references", "reviewers");
+    const metaPath = join20(ocrDir, "reviewers-meta.json");
     let metaWritten = false;
     try {
       const meta = generateReviewersMeta(reviewersDir, configPath);
       if (meta) {
-        writeFileSync9(metaPath, JSON.stringify(meta, null, 2) + "\n", "utf-8");
+        writeFileSync8(metaPath, JSON.stringify(meta, null, 2) + "\n", "utf-8");
         metaWritten = true;
       }
     } catch (err) {
@@ -34128,7 +35276,7 @@ var teamCommand = new Command("team").description("Resolve and persist team comp
 
 // src/commands/review.ts
 import { spawn as spawn3 } from "node:child_process";
-import { join as join20 } from "node:path";
+import { join as join21 } from "node:path";
 init_db();
 
 // src/lib/vendor-resume.ts
@@ -34167,7 +35315,7 @@ var reviewCommand = new Command("review").description("Run or resume an OCR revi
   }
   const targetDir = process.cwd();
   requireOcrSetup(targetDir);
-  const ocrDir = join20(targetDir, ".ocr");
+  const ocrDir = join21(targetDir, ".ocr");
   const db = await ensureDatabase(ocrDir);
   const session = getSession(db, options.resume);
   if (!session) {
@@ -34209,16 +35357,16 @@ var reviewCommand = new Command("review").description("Run or resume an OCR revi
 });
 
 // src/commands/update.ts
-import { existsSync as existsSync17 } from "node:fs";
-import { join as join21 } from "node:path";
+import { existsSync as existsSync18 } from "node:fs";
+import { join as join22 } from "node:path";
 function detectConfiguredTools(targetDir) {
   return AI_TOOLS.filter((tool) => {
     if (tool.commandStrategy === "subdirectory") {
-      const ocrDir = join21(targetDir, tool.commandsDir, "ocr");
-      return existsSync17(ocrDir);
+      const ocrDir = join22(targetDir, tool.commandsDir, "ocr");
+      return existsSync18(ocrDir);
     } else {
-      const reviewCmd = join21(targetDir, tool.commandsDir, "ocr-review.md");
-      return existsSync17(reviewCmd);
+      const reviewCmd = join22(targetDir, tool.commandsDir, "ocr-review.md");
+      return existsSync18(reviewCmd);
     }
   });
 }
@@ -34292,7 +35440,7 @@ var updateCommand = new Command("update").description("Update OCR assets after p
         const result = installForTool(tool, targetDir);
         results.push(result);
       }
-      ensureGitignore(join21(targetDir, ".ocr"));
+      ensureGitignore(join22(targetDir, ".ocr"));
       spinner.stop();
       const successful = results.filter((r) => r.success);
       const failed = results.filter((r) => !r.success);
@@ -34328,10 +35476,10 @@ var updateCommand = new Command("update").description("Update OCR assets after p
   if (updateInject) {
     if (options.dryRun) {
       console.log(source_default.dim("  Would update:"));
-      if (existsSync17(join21(targetDir, "AGENTS.md"))) {
+      if (existsSync18(join22(targetDir, "AGENTS.md"))) {
         console.log(source_default.dim("    \u2022 AGENTS.md (OCR managed block)"));
       }
-      if (existsSync17(join21(targetDir, "CLAUDE.md"))) {
+      if (existsSync18(join22(targetDir, "CLAUDE.md"))) {
         console.log(source_default.dim("    \u2022 CLAUDE.md (OCR managed block)"));
       }
       console.log();
@@ -34363,14 +35511,14 @@ var updateCommand = new Command("update").description("Update OCR assets after p
 });
 
 // src/commands/dashboard.ts
-import { existsSync as existsSync18 } from "node:fs";
-import { join as join22, dirname as dirname6 } from "node:path";
+import { existsSync as existsSync19 } from "node:fs";
+import { join as join23, dirname as dirname7 } from "node:path";
 import { fileURLToPath } from "node:url";
 init_db();
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname6(__filename);
+var __dirname = dirname7(__filename);
 function resolveServerPath() {
-  return join22(__dirname, "dashboard", "server.js");
+  return join23(__dirname, "dashboard", "server.js");
 }
 var dashboardCommand = new Command("dashboard").description("Start the OCR dashboard web interface").option("-p, --port <port>", "Port to run the server on", "4173").option("--no-open", "Don't open the browser automatically").action(
   async (options) => {
@@ -34381,7 +35529,7 @@ var dashboardCommand = new Command("dashboard").description("Start the OCR dashb
       console.error(source_default.red(`Error: Invalid port "${options.port}". Must be 1-65535.`));
       process.exit(1);
     }
-    const ocrDir = join22(targetDir, ".ocr");
+    const ocrDir = join23(targetDir, ".ocr");
     try {
       await ensureDatabase(ocrDir);
       closeAllDatabases();
@@ -34395,7 +35543,7 @@ var dashboardCommand = new Command("dashboard").description("Start the OCR dashb
       process.exit(1);
     }
     const serverPath = resolveServerPath();
-    if (!existsSync18(serverPath)) {
+    if (!existsSync19(serverPath)) {
       console.error(source_default.red("Error: Dashboard server bundle not found."));
       console.error(
         source_default.dim(`  Expected at: ${serverPath}`)
@@ -34429,10 +35577,53 @@ var dashboardCommand = new Command("dashboard").description("Start the OCR dashb
 );
 
 // src/commands/doctor.ts
-import { existsSync as existsSync19 } from "node:fs";
-import { join as join23 } from "node:path";
-var doctorCommand = new Command("doctor").description("Check OCR installation and verify all dependencies").action(() => {
+import { existsSync as existsSync20 } from "node:fs";
+import { join as join24 } from "node:path";
+init_db();
+function printStorageEngine(probeWriteEnabled) {
+  console.log();
+  console.log(source_default.bold("  Storage Engine"));
+  console.log();
+  const engine = probeEngine();
+  if (!engine.ok) {
+    console.log(`    ${source_default.red("\u2717")} node:sqlite unavailable`);
+    console.log(`      ${source_default.dim(engine.error)}`);
+    console.log(
+      `      ${source_default.dim(
+        "OCR requires Node >= 22.5 (node:sqlite). Upgrade Node, then re-run `ocr doctor`."
+      )}`
+    );
+    return false;
+  }
+  console.log(
+    `    ${source_default.green("\u2713")} node:sqlite (SQLite ${engine.version}, WAL)`
+  );
+  if (probeWriteEnabled) {
+    const write = probeWrite();
+    if (!write.ok) {
+      console.log(`    ${source_default.red("\u2717")} write probe failed`);
+      console.log(`      ${source_default.dim(write.error)}`);
+      return false;
+    }
+    console.log(
+      `    ${source_default.green("\u2713")} write probe (on-disk WAL transaction round-trip)`
+    );
+  }
+  return true;
+}
+var doctorCommand = new Command("doctor").description("Check OCR installation and verify all dependencies").option(
+  "--probe-write",
+  "additionally exercise an on-disk WAL transaction round-trip (used by the release install gate)"
+).option(
+  "--engine-only",
+  "check ONLY the storage engine and exit on its result \u2014 skips project/tool checks (used by the release install gate, which runs from a non-initialized dir with no AI tools)"
+).action((options) => {
   printHeader();
+  if (options.engineOnly) {
+    const ok = printStorageEngine(options.probeWrite ?? false);
+    console.log();
+    process.exit(ok ? 0 : 1);
+  }
   const targetDir = process.cwd();
   let hasIssues = false;
   const depResult = checkDependencies();
@@ -34444,10 +35635,10 @@ var doctorCommand = new Command("doctor").description("Check OCR installation an
   console.log(source_default.bold("  OCR Installation"));
   console.log();
   const ocrStatus = checkOcrSetup(targetDir);
-  const configPath = join23(targetDir, ".ocr", "config.yaml");
-  const dbPath = join23(targetDir, ".ocr", "data", "ocr.db");
-  const hasConfig = existsSync19(configPath);
-  const hasDb = existsSync19(dbPath);
+  const configPath = join24(targetDir, ".ocr", "config.yaml");
+  const dbPath = join24(targetDir, ".ocr", "data", "ocr.db");
+  const hasConfig = existsSync20(configPath);
+  const hasDb = existsSync20(dbPath);
   const ocrChecks = [
     { label: ".ocr/skills/", ok: ocrStatus.hasSkills },
     { label: ".ocr/sessions/", ok: ocrStatus.hasSessions },
@@ -34469,6 +35660,9 @@ var doctorCommand = new Command("doctor").description("Check OCR installation an
   if (!ocrStatus.valid) {
     hasIssues = true;
   }
+  if (!printStorageEngine(options.probeWrite ?? false)) {
+    hasIssues = true;
+  }
   console.log();
   printCapabilities(depResult);
   console.log();
@@ -34521,8 +35715,8 @@ var doctorCommand = new Command("doctor").description("Check OCR installation an
 });
 
 // src/commands/reviewers.ts
-import { writeFileSync as writeFileSync10, renameSync as renameSync3 } from "node:fs";
-import { join as join24 } from "node:path";
+import { writeFileSync as writeFileSync9, renameSync as renameSync2 } from "node:fs";
+import { join as join25 } from "node:path";
 async function readStdin3() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -34585,20 +35779,20 @@ function validateReviewersMeta(data) {
 var syncSubcommand2 = new Command("sync").description("Sync reviewers-meta.json from reviewer markdown files or structured JSON").option("--stdin", "Read reviewers JSON from stdin (for AI-invoked sync)").action(async (options) => {
   const targetDir = process.cwd();
   requireOcrSetup(targetDir);
-  const ocrDir = join24(targetDir, ".ocr");
+  const ocrDir = join25(targetDir, ".ocr");
   if (!options.stdin) {
     try {
-      const reviewersDir = join24(ocrDir, "skills", "references", "reviewers");
-      const configPath = join24(ocrDir, "config.yaml");
+      const reviewersDir = join25(ocrDir, "skills", "references", "reviewers");
+      const configPath = join25(ocrDir, "config.yaml");
       const meta = generateReviewersMeta(reviewersDir, configPath);
       if (!meta || meta.reviewers.length === 0) {
         console.error(source_default.yellow("No reviewer files found in .ocr/skills/references/reviewers/"));
         process.exit(1);
       }
-      const metaPath = join24(ocrDir, "reviewers-meta.json");
+      const metaPath = join25(ocrDir, "reviewers-meta.json");
       const tmpPath = metaPath + ".tmp";
-      writeFileSync10(tmpPath, JSON.stringify(meta, null, 2) + "\n");
-      renameSync3(tmpPath, metaPath);
+      writeFileSync9(tmpPath, JSON.stringify(meta, null, 2) + "\n");
+      renameSync2(tmpPath, metaPath);
       const tierCounts = meta.reviewers.reduce(
         (acc, r) => {
           acc[r.tier] = (acc[r.tier] ?? 0) + 1;
@@ -34625,10 +35819,10 @@ var syncSubcommand2 = new Command("sync").description("Sync reviewers-meta.json
       throw new Error("Invalid JSON on stdin");
     }
     const meta = validateReviewersMeta(parsed);
-    const metaPath = join24(ocrDir, "reviewers-meta.json");
+    const metaPath = join25(ocrDir, "reviewers-meta.json");
     const tmpPath = metaPath + ".tmp";
-    writeFileSync10(tmpPath, JSON.stringify(meta, null, 2) + "\n");
-    renameSync3(tmpPath, metaPath);
+    writeFileSync9(tmpPath, JSON.stringify(meta, null, 2) + "\n");
+    renameSync2(tmpPath, metaPath);
     const tierCounts = meta.reviewers.reduce(
       (acc, r) => {
         acc[r.tier] = (acc[r.tier] ?? 0) + 1;
@@ -34653,25 +35847,25 @@ var reviewersCommand = new Command("reviewers").description("Manage OCR reviewer
 
 // src/lib/update-check.ts
 import { homedir } from "node:os";
-import { join as join25 } from "node:path";
-import { readFileSync as readFileSync15, writeFileSync as writeFileSync11, mkdirSync as mkdirSync7 } from "node:fs";
+import { join as join26 } from "node:path";
+import { readFileSync as readFileSync14, writeFileSync as writeFileSync10, mkdirSync as mkdirSync7 } from "node:fs";
 var PACKAGE_NAME = "@open-code-review/cli";
 var REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
-var CACHE_DIR2 = join25(homedir(), ".ocr");
-var CACHE_FILE = join25(CACHE_DIR2, "update-check.json");
+var CACHE_DIR2 = join26(homedir(), ".ocr");
+var CACHE_FILE = join26(CACHE_DIR2, "update-check.json");
 var CHECK_INTERVAL_MS = 4 * 60 * 60 * 1e3;
 var FETCH_TIMEOUT_MS = 3e3;
 function readCache(cacheFile) {
   try {
-    return JSON.parse(readFileSync15(cacheFile, "utf-8"));
+    return JSON.parse(readFileSync14(cacheFile, "utf-8"));
   } catch {
     return null;
   }
 }
 function writeCache(cacheFile, cache) {
   try {
-    mkdirSync7(join25(cacheFile, ".."), { recursive: true });
-    writeFileSync11(cacheFile, JSON.stringify(cache));
+    mkdirSync7(join26(cacheFile, ".."), { recursive: true });
+    writeFileSync10(cacheFile, JSON.stringify(cache));
   } catch {
   }
 }
@@ -34691,7 +35885,7 @@ async function checkForUpdate(currentVersion, options) {
   if (process.env.CI || process.env.OCR_NO_UPDATE_CHECK) {
     return null;
   }
-  const cacheFile = join25(options?.cacheDir ?? CACHE_DIR2, "update-check.json");
+  const cacheFile = join26(options?.cacheDir ?? CACHE_DIR2, "update-check.json");
   try {
     const cache = readCache(cacheFile);
     if (cache && Date.now() - cache.lastCheck < CHECK_INTERVAL_MS) {