@open-code-review/cli 2.1.0 → 2.2.0

package/dist/lib/state/index.js

@@ -0,0 +1,2196 @@
+// src/lib/state/index.ts
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync,
+  statSync as statSync2,
+  writeFileSync
+} from "node:fs";
+
+// src/lib/db/index.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  copyFileSync,
+  statSync,
+  mkdtempSync,
+  rmSync
+} from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
+
+// src/lib/db/engine.ts
+import { createRequire } from "node:module";
+
+// src/lib/runtime-checks.ts
+var NODE_FLOOR = { major: 22, minor: 5 };
+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");
+}
+
+// src/lib/db/engine.ts
+var SQLITE_BUSY = 5;
+var SQLITE_BUSY_SNAPSHOT = 261;
+var BUSY_RETRY_ATTEMPTS = 5;
+var BUSY_RETRY_BACKOFF_MS = 50;
+var savepointName = (depth) => `ocr_sp_${depth}`;
+var nodeRequire = createRequire(import.meta.url);
+var _preconditionsApplied = false;
+function applyEnginePreconditions() {
+  if (_preconditionsApplied) return;
+  _preconditionsApplied = true;
+  const originalEmitWarning = process.emitWarning.bind(process);
+  process.emitWarning = (warning, ...args) => {
+    if (isSuppressibleSqliteWarning(warning)) return;
+    originalEmitWarning(warning, ...args);
+  };
+}
+var _DatabaseSyncCtor;
+function newDatabase(path) {
+  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(path);
+}
+function isBusyError(e) {
+  const errcode = e?.errcode;
+  return errcode === SQLITE_BUSY || errcode === SQLITE_BUSY_SNAPSHOT;
+}
+var SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+  Atomics.wait(SLEEP_BUF, 0, 0, ms);
+}
+var 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;
+    }
+  }
+};
+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);
+}
+
+// src/lib/db/migrations.ts
+var MIGRATIONS = [
+  {
+    version: 1,
+    description: "Initial schema \u2014 sessions, events, artifacts, user state",
+    sql: `
+      -- Layer 1: Workflow State
+
+      CREATE TABLE sessions (
+        id TEXT PRIMARY KEY,
+        branch TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active', 'closed')),
+        workflow_type TEXT NOT NULL CHECK(workflow_type IN ('review', 'map')),
+        current_phase TEXT NOT NULL DEFAULT 'context',
+        phase_number INTEGER NOT NULL DEFAULT 1,
+        current_round INTEGER NOT NULL DEFAULT 1,
+        current_map_run INTEGER NOT NULL DEFAULT 1,
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        session_dir TEXT NOT NULL
+      );
+
+      CREATE TABLE orchestration_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        event_type TEXT NOT NULL,
+        phase TEXT,
+        phase_number INTEGER,
+        round INTEGER,
+        metadata TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX idx_events_session ON orchestration_events(session_id);
+      CREATE INDEX idx_events_type ON orchestration_events(event_type);
+
+      -- Layer 2: Artifacts
+
+      CREATE TABLE review_rounds (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        round_number INTEGER NOT NULL,
+        verdict TEXT,
+        blocker_count INTEGER DEFAULT 0,
+        suggestion_count INTEGER DEFAULT 0,
+        should_fix_count INTEGER DEFAULT 0,
+        final_md_path TEXT,
+        parsed_at TEXT,
+        UNIQUE(session_id, round_number)
+      );
+
+      CREATE TABLE reviewer_outputs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        round_id INTEGER NOT NULL REFERENCES review_rounds(id) ON DELETE CASCADE,
+        reviewer_type TEXT NOT NULL,
+        instance_number INTEGER NOT NULL DEFAULT 1,
+        file_path TEXT NOT NULL,
+        finding_count INTEGER DEFAULT 0,
+        parsed_at TEXT,
+        UNIQUE(round_id, reviewer_type, instance_number)
+      );
+
+      CREATE TABLE review_findings (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        reviewer_output_id INTEGER NOT NULL REFERENCES reviewer_outputs(id) ON DELETE CASCADE,
+        title TEXT NOT NULL,
+        severity TEXT NOT NULL CHECK(severity IN ('critical', 'high', 'medium', 'low', 'info')),
+        file_path TEXT,
+        line_start INTEGER,
+        line_end INTEGER,
+        summary TEXT,
+        is_blocker INTEGER NOT NULL DEFAULT 0,
+        parsed_at TEXT
+      );
+      CREATE INDEX idx_findings_severity ON review_findings(severity);
+
+      CREATE TABLE markdown_artifacts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        artifact_type TEXT NOT NULL,
+        round_number INTEGER,
+        file_path TEXT NOT NULL,
+        content TEXT NOT NULL,
+        parsed_at TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(session_id, artifact_type, round_number, file_path)
+      );
+
+      CREATE TABLE map_runs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        run_number INTEGER NOT NULL,
+        file_count INTEGER DEFAULT 0,
+        map_md_path TEXT,
+        parsed_at TEXT,
+        UNIQUE(session_id, run_number)
+      );
+
+      CREATE TABLE map_sections (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        map_run_id INTEGER NOT NULL REFERENCES map_runs(id) ON DELETE CASCADE,
+        section_number INTEGER NOT NULL,
+        title TEXT NOT NULL,
+        description TEXT,
+        file_count INTEGER DEFAULT 0,
+        display_order INTEGER NOT NULL DEFAULT 0,
+        UNIQUE(map_run_id, section_number)
+      );
+
+      CREATE TABLE map_files (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        section_id INTEGER NOT NULL REFERENCES map_sections(id) ON DELETE CASCADE,
+        file_path TEXT NOT NULL,
+        role TEXT,
+        lines_added INTEGER DEFAULT 0,
+        lines_deleted INTEGER DEFAULT 0,
+        display_order INTEGER NOT NULL DEFAULT 0,
+        UNIQUE(section_id, file_path)
+      );
+
+      -- Layer 3: User Interaction
+
+      CREATE TABLE user_file_progress (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        map_file_id INTEGER NOT NULL REFERENCES map_files(id) ON DELETE CASCADE,
+        is_reviewed INTEGER NOT NULL DEFAULT 0,
+        reviewed_at TEXT,
+        UNIQUE(map_file_id)
+      );
+
+      CREATE TABLE user_finding_progress (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        finding_id INTEGER NOT NULL REFERENCES review_findings(id) ON DELETE CASCADE,
+        status TEXT NOT NULL DEFAULT 'unread' CHECK(status IN ('unread', 'read', 'acknowledged', 'fixed', 'wont_fix')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(finding_id)
+      );
+
+      CREATE TABLE user_notes (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        target_type TEXT NOT NULL CHECK(target_type IN ('session', 'round', 'finding', 'run', 'section', 'file')),
+        target_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE command_executions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        command TEXT NOT NULL,
+        args TEXT,
+        exit_code INTEGER,
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        finished_at TEXT,
+        output TEXT
+      );
+    `
+  },
+  {
+    version: 2,
+    description: "Add chat conversations, messages, and round progress tables",
+    sql: `
+      CREATE TABLE IF NOT EXISTS chat_conversations (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        target_type TEXT NOT NULL CHECK(target_type IN ('map_run', 'review_round')),
+        target_id INTEGER NOT NULL,
+        claude_session_id TEXT,
+        status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active', 'expired')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        last_active_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS chat_messages (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        conversation_id TEXT NOT NULL REFERENCES chat_conversations(id) ON DELETE CASCADE,
+        role TEXT NOT NULL CHECK(role IN ('user', 'assistant')),
+        content TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS user_round_progress (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        round_id INTEGER NOT NULL REFERENCES review_rounds(id) ON DELETE CASCADE,
+        status TEXT NOT NULL DEFAULT 'needs_review'
+          CHECK(status IN ('needs_review', 'in_progress', 'changes_made', 'acknowledged', 'dismissed')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(round_id)
+      );
+    `
+  },
+  {
+    version: 3,
+    description: "Add PID tracking to command_executions for orphan process cleanup",
+    sql: `
+      ALTER TABLE command_executions ADD COLUMN pid INTEGER;
+    `
+  },
+  {
+    version: 4,
+    description: "Add is_detached flag to command_executions for process group kill strategy",
+    sql: `
+      ALTER TABLE command_executions ADD COLUMN is_detached INTEGER NOT NULL DEFAULT 0;
+    `
+  },
+  {
+    version: 5,
+    description: "Change orchestration_events FK to RESTRICT to protect audit trail",
+    sql: `
+      CREATE TABLE orchestration_events_new (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE RESTRICT,
+        event_type TEXT NOT NULL,
+        phase TEXT,
+        phase_number INTEGER,
+        round INTEGER,
+        metadata TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      INSERT INTO orchestration_events_new SELECT * FROM orchestration_events;
+      DROP TABLE orchestration_events;
+      ALTER TABLE orchestration_events_new RENAME TO orchestration_events;
+      CREATE INDEX idx_events_session ON orchestration_events(session_id);
+      CREATE INDEX idx_events_type ON orchestration_events(event_type);
+    `
+  },
+  {
+    version: 6,
+    description: "Add orchestrator-first columns to review_rounds for round-meta.json support",
+    sql: `
+      ALTER TABLE review_rounds ADD COLUMN source TEXT DEFAULT NULL;
+      ALTER TABLE review_rounds ADD COLUMN reviewer_count INTEGER DEFAULT 0;
+      ALTER TABLE review_rounds ADD COLUMN total_finding_count INTEGER DEFAULT 0;
+    `
+  },
+  {
+    version: 7,
+    description: "Add category column to review_findings for blocker/should_fix/suggestion classification",
+    sql: `
+      ALTER TABLE review_findings ADD COLUMN category TEXT DEFAULT NULL;
+    `
+  },
+  {
+    version: 8,
+    description: "Add orchestrator-first columns to map_runs for map-meta.json support",
+    sql: `
+      ALTER TABLE map_runs ADD COLUMN source TEXT DEFAULT NULL;
+      ALTER TABLE map_runs ADD COLUMN section_count INTEGER DEFAULT 0;
+    `
+  },
+  {
+    version: 9,
+    description: "Add uid column to command_executions for JSONL-backed recovery",
+    sql: `
+      ALTER TABLE command_executions ADD COLUMN uid TEXT;
+      CREATE UNIQUE INDEX idx_command_executions_uid ON command_executions(uid);
+    `
+  },
+  {
+    version: 10,
+    description: "Add agent_sessions journal for per-instance lifecycle tracking",
+    sql: `
+      CREATE TABLE agent_sessions (
+        id TEXT PRIMARY KEY,
+        workflow_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE RESTRICT,
+        vendor TEXT NOT NULL,
+        vendor_session_id TEXT,
+        persona TEXT,
+        instance_index INTEGER,
+        name TEXT,
+        resolved_model TEXT,
+        phase TEXT,
+        status TEXT NOT NULL CHECK(status IN ('spawning', 'running', 'done', 'crashed', 'cancelled', 'orphaned')),
+        pid INTEGER,
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        last_heartbeat_at TEXT NOT NULL DEFAULT (datetime('now')),
+        ended_at TEXT,
+        exit_code INTEGER,
+        notes TEXT
+      );
+      CREATE INDEX idx_agent_sessions_workflow ON agent_sessions(workflow_id);
+      CREATE INDEX idx_agent_sessions_status_heartbeat ON agent_sessions(status, last_heartbeat_at);
+    `
+  },
+  {
+    version: 11,
+    description: "Unify agent_sessions into command_executions \u2014 every spawned process is one execution row",
+    sql: `
+      -- Extend command_executions with the journaling fields previously on agent_sessions.
+      -- A NULL workflow_id is allowed because some commands (e.g. sync-reviewers,
+      -- create-reviewer) don't tie to a review workflow. Existing rows get NULL by default.
+      ALTER TABLE command_executions ADD COLUMN workflow_id TEXT REFERENCES sessions(id) ON DELETE RESTRICT;
+      -- parent_id = the dashboard-spawn that's the "Tech Lead" parent of an AI-spawned
+      -- session-instance row. NULL for top-level dashboard spawns.
+      ALTER TABLE command_executions ADD COLUMN parent_id INTEGER REFERENCES command_executions(id);
+      -- Vendor metadata (claude | opencode | gemini | \u2026). NULL for non-AI commands.
+      ALTER TABLE command_executions ADD COLUMN vendor TEXT;
+      -- The underlying CLI's own session id, captured from stream events.
+      -- Used for resume / handoff. Hidden from users (ocr exposes its own id only).
+      ALTER TABLE command_executions ADD COLUMN vendor_session_id TEXT;
+      -- Persona/instance metadata for AI sub-agents (set when the AI calls
+      -- ocr session start-instance). NULL for the parent dashboard spawn.
+      ALTER TABLE command_executions ADD COLUMN persona TEXT;
+      ALTER TABLE command_executions ADD COLUMN instance_index INTEGER;
+      ALTER TABLE command_executions ADD COLUMN name TEXT;
+      -- Resolved model string passed to --model post-alias-expansion.
+      ALTER TABLE command_executions ADD COLUMN resolved_model TEXT;
+      -- Liveness heartbeat. Bumped on every state event the AI emits.
+      -- Stale rows past the threshold are reclassified to orphaned (exit_code=-3).
+      ALTER TABLE command_executions ADD COLUMN last_heartbeat_at TEXT;
+      -- Free-form annotations (sweep notes, host-CLI capability warnings, etc).
+      ALTER TABLE command_executions ADD COLUMN notes TEXT;
+      CREATE INDEX idx_command_executions_workflow ON command_executions(workflow_id);
+      CREATE INDEX idx_command_executions_parent ON command_executions(parent_id);
+      CREATE INDEX idx_command_executions_heartbeat ON command_executions(last_heartbeat_at);
+
+      -- The agent_sessions table is retired. Phase 1 was a parallel journal that
+      -- this migration consolidates. We drop the table outright \u2014 the only existing
+      -- consumers are the cli helpers and tests, which are updated alongside this
+      -- migration. No production deployments have agent_sessions data worth migrating.
+      DROP INDEX IF EXISTS idx_agent_sessions_workflow;
+      DROP INDEX IF EXISTS idx_agent_sessions_status_heartbeat;
+      DROP TABLE IF EXISTS agent_sessions;
+    `
+  },
+  {
+    version: 12,
+    description: "Event-sourced lifecycle hardening: event_type taxonomy guard, sweep indexes, session_completeness view",
+    sql: `
+      -- \u2500\u2500 Indexes for the now-periodic stale-session sweep + round derivation \u2500\u2500
+      -- The sweep filters sessions by status and rolls up MAX(created_at) per
+      -- session over the event log; deriveNextRound does MAX(round). Index both.
+      CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
+      CREATE INDEX IF NOT EXISTS idx_events_session_created
+        ON orchestration_events(session_id, created_at);
+
+      -- \u2500\u2500 Event-type taxonomy guard \u2500\u2500
+      -- orchestration_events.event_type is the spine of all lifecycle
+      -- derivation. A typo (e.g. 'round_complete' vs 'round_completed') would
+      -- silently break deriveNextRound and the completeness view. SQLite cannot
+      -- add a CHECK to an existing column without a table rebuild, so enforce
+      -- the closed vocabulary with a BEFORE INSERT trigger instead.
+      CREATE TRIGGER IF NOT EXISTS trg_events_known_type
+      BEFORE INSERT ON orchestration_events
+      WHEN NEW.event_type NOT IN (
+        'session_created', 'session_resumed', 'round_started', 'phase_transition',
+        'round_completed', 'map_completed', 'session_closed', 'session_aborted',
+        'session_auto_closed_stale', 'session_synced', 'session_legacy_import'
+      )
+      BEGIN
+        SELECT RAISE(ABORT, 'unknown orchestration_events.event_type');
+      END;
+
+      -- \u2500\u2500 Close-guard (DB backstop for the completion invariant) \u2500\u2500
+      -- A session cannot transition active \u2192 closed unless its current
+      -- round/run has a terminal artifact event, OR an explicit reason event
+      -- (abort / auto-close-stale / sync / legacy-import) is present. Only a
+      -- *silent* premature close is banned \u2014 every legitimate non-artifact
+      -- close carries a reason event and passes. App-level guards in
+      -- stateClose/finish are the primary check; this makes the illegal state
+      -- unrepresentable even via raw SQL.
+      --
+      -- DEFENCE-IN-DEPTH NOTE (intentional, documented gap): the reason-event
+      -- branch below (event_type IN (...)) is NOT round-scoped \u2014 a reason event
+      -- recorded for an earlier round would also satisfy a later close. The
+      -- app-level guards ARE round-scoped (hasCompletionInvariant checks the
+      -- current round/run), so the precise check lives in the application; this
+      -- trigger is a coarse backstop against a *silent* premature close via raw
+      -- SQL. Tightening it to be round-scoped would require a new migration
+      -- (this v12 trigger is append-only and already shipped); the residual
+      -- risk is a non-artifact close carrying a stale reason event, which is
+      -- still an explicit, audited terminal \u2014 not the failure mode this guards.
+      CREATE TRIGGER IF NOT EXISTS trg_sessions_close_guard
+      BEFORE UPDATE OF status ON sessions
+      WHEN NEW.status = 'closed' AND OLD.status <> 'closed'
+        AND NOT EXISTS (
+          SELECT 1 FROM orchestration_events e
+           WHERE e.session_id = NEW.id
+             AND (
+               (NEW.workflow_type = 'review' AND e.event_type = 'round_completed' AND e.round = NEW.current_round)
+               OR (NEW.workflow_type = 'map' AND e.event_type = 'map_completed'   AND e.round = NEW.current_map_run)
+               OR e.event_type IN ('session_aborted','session_auto_closed_stale','session_synced','session_legacy_import')
+             )
+        )
+      BEGIN
+        SELECT RAISE(ABORT, 'cannot close session without a completed round/run or an explicit reason event');
+      END;
+
+      -- \u2500\u2500 session_completeness view \u2500\u2500
+      -- The published contract for "is this session actually complete, and if
+      -- not, what's missing". Completion is DERIVED from the event log, never a
+      -- mutable flag: a session is complete iff it is closed AND a terminal
+      -- artifact event exists for its current round/run. The dashboard's
+      -- outcome derivation and the agent 'status' command read this view, so
+      -- they cannot disagree.
+      --
+      -- completeness_state is an INTENTIONAL HYBRID: it combines the mutable
+      -- status column (marked_closed) with append-only event evidence (the
+      -- terminal artifact event). This is sound precisely because the
+      -- close-guard trigger above makes the status column trustworthy \u2014 a row
+      -- can only reach status='closed' with a completed round/run or an
+      -- explicit reason event \u2014 so reading the column is not a regression to
+      -- the old "mutable flag that could lie" model.
+      --
+      --   completeness_state:
+      --     'complete'                \u2014 closed + terminal artifact for current round/run
+      --     'closed_without_artifact' \u2014 closed but no terminal artifact (the
+      --                                 "completed too soon" condition)
+      --     'in_flight'               \u2014 open with a dependent process still running
+      --     'open_no_artifact'        \u2014 open, no in-flight dependents
+      CREATE VIEW IF NOT EXISTS session_completeness AS
+      SELECT
+        s.id              AS session_id,
+        s.workflow_type   AS workflow_type,
+        s.status          AS status,
+        s.current_round   AS current_round,
+        s.current_map_run AS current_map_run,
+        CASE WHEN EXISTS (
+          SELECT 1 FROM orchestration_events e
+           WHERE e.session_id = s.id
+             AND (
+               (s.workflow_type = 'review' AND e.event_type = 'round_completed' AND e.round = s.current_round)
+               OR (s.workflow_type = 'map' AND e.event_type = 'map_completed'   AND e.round = s.current_map_run)
+             )
+        ) THEN 1 ELSE 0 END AS has_terminal_artifact,
+        CASE WHEN s.status = 'closed' THEN 1 ELSE 0 END AS marked_closed,
+        CASE WHEN NOT EXISTS (
+          SELECT 1 FROM command_executions ce
+           WHERE ce.workflow_id = s.id AND ce.finished_at IS NULL
+        ) THEN 1 ELSE 0 END AS dependents_settled,
+        CASE
+          WHEN s.status = 'closed' AND EXISTS (
+            SELECT 1 FROM orchestration_events e
+             WHERE e.session_id = s.id
+               AND (
+                 (s.workflow_type = 'review' AND e.event_type = 'round_completed' AND e.round = s.current_round)
+                 OR (s.workflow_type = 'map' AND e.event_type = 'map_completed'   AND e.round = s.current_map_run)
+               )
+          ) THEN 'complete'
+          WHEN s.status = 'closed' THEN 'closed_without_artifact'
+          WHEN EXISTS (
+            SELECT 1 FROM command_executions ce
+             WHERE ce.workflow_id = s.id AND ce.finished_at IS NULL
+          ) THEN 'in_flight'
+          ELSE 'open_no_artifact'
+        END AS completeness_state
+      FROM sessions s;
+    `
+  },
+  {
+    version: 13,
+    description: "Retire dead parent_id column on command_executions (never written; row kind is derived from command)",
+    // parent_id was reserved for an AI-instance → dashboard-spawn lineage link
+    // that was never wired (no writer, no reader). A process's KIND (supervisor
+    // / reviewer-instance / utility) is derived from columns that are always
+    // present (command + last_heartbeat_at), so the dead lineage column and its
+    // all-NULL index are removed. Re-add a wired parent_id alongside a real
+    // consumer (e.g. a parent→child tree view) if lineage is ever needed.
+    //
+    // Imperative + guarded so the DROP COLUMN (which SQLite can't express as
+    // IF EXISTS) is idempotent under re-application.
+    run: (db) => {
+      if (!columnExists(db, "command_executions", "parent_id")) return;
+      db.run("DROP INDEX IF EXISTS idx_command_executions_parent;");
+      db.run("ALTER TABLE command_executions DROP COLUMN parent_id;");
+    }
+  },
+  {
+    version: 14,
+    description: "Self-heal markdown_artifacts duplication: collapse NULL-round duplicate rows and add a NULL-safe unique index so the dedup bug cannot recur",
+    // The table's `UNIQUE(session_id, artifact_type, round_number, file_path)`
+    // never deduped session-level artifacts because SQLite treats NULL ≠ NULL,
+    // and the writer used `INSERT OR REPLACE` — so every re-parse of a
+    // NULL-round artifact (context.md, map.md, …) appended a duplicate (one
+    // context.md reached 775 identical rows, ~177 MB). The writer is now an
+    // explicit UPDATE-or-INSERT; this migration heals existing DBs and adds a
+    // NULL-collapsing unique index as a DB-level backstop.
+    //
+    // Orphan-row sweep (FK-dangling children from the pre-FK-enforcement era)
+    // is intentionally NOT done here — it needs `PRAGMA foreign_keys = OFF`,
+    // which is a no-op inside the migration transaction. `ocr db doctor --fix`
+    // performs it outside a transaction.
+    run: (db) => {
+      db.run(`
+        DELETE FROM markdown_artifacts
+        WHERE rowid NOT IN (
+          SELECT MAX(rowid) FROM markdown_artifacts
+          GROUP BY session_id, artifact_type, IFNULL(round_number, -1), file_path
+        )
+      `);
+      db.run(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_markdown_artifacts_logical
+        ON markdown_artifacts(session_id, artifact_type, IFNULL(round_number, -1), file_path)
+      `);
+    }
+  }
+];
+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 (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now')),
+      description TEXT NOT NULL
+    );
+  `);
+}
+function getSchemaVersion(db) {
+  ensureSchemaVersionTable(db);
+  return getCurrentVersion(db);
+}
+function getCurrentVersion(db) {
+  const result = db.exec(
+    "SELECT MAX(version) as v FROM schema_version"
+  );
+  if (result.length === 0 || result[0]?.values.length === 0) {
+    return 0;
+  }
+  const val = result[0]?.values[0]?.[0];
+  return typeof val === "number" ? val : 0;
+}
+function runMigrations(db) {
+  ensureSchemaVersionTable(db);
+  const currentVersion = getCurrentVersion(db);
+  for (const migration of MIGRATIONS) {
+    if (migration.version <= currentVersion) {
+      continue;
+    }
+    db.run("BEGIN IMMEDIATE;");
+    try {
+      if (migration.sql) db.run(migration.sql);
+      migration.run?.(db);
+      db.run(
+        "INSERT INTO schema_version (version, description) VALUES (?, ?);",
+        [migration.version, migration.description]
+      );
+      db.run("COMMIT;");
+    } catch (error) {
+      db.run("ROLLBACK;");
+      throw error;
+    }
+  }
+}
+
+// src/lib/db/reconcile.ts
+import { existsSync } from "node:fs";
+import { isAbsolute, join, dirname } from "node:path";
+
+// src/lib/db/result-mapper.ts
+function resultToRows(result) {
+  if (result.length === 0 || !result[0]) {
+    return [];
+  }
+  const { columns, values } = result[0];
+  return values.map((row) => {
+    const obj = {};
+    for (let i = 0; i < columns.length; i++) {
+      obj[columns[i]] = row[i];
+    }
+    return obj;
+  });
+}
+function resultToRow(result) {
+  const rows = resultToRows(result);
+  return rows[0];
+}
+
+// src/lib/db/queries.ts
+function insertSession(db, params) {
+  const {
+    id,
+    branch,
+    workflow_type,
+    current_phase = "context",
+    phase_number = 1,
+    current_round = 1,
+    current_map_run = 1,
+    session_dir
+  } = params;
+  db.run(
+    `INSERT INTO sessions (id, branch, workflow_type, current_phase, phase_number, current_round, current_map_run, session_dir)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [id, branch, workflow_type, current_phase, phase_number, current_round, current_map_run, session_dir]
+  );
+}
+function updateSession(db, id, params) {
+  const setClauses = [];
+  const values = [];
+  if (params.status !== void 0) {
+    setClauses.push("status = ?");
+    values.push(params.status);
+  }
+  if (params.current_phase !== void 0) {
+    setClauses.push("current_phase = ?");
+    values.push(params.current_phase);
+  }
+  if (params.phase_number !== void 0) {
+    setClauses.push("phase_number = ?");
+    values.push(params.phase_number);
+  }
+  if (params.current_round !== void 0) {
+    setClauses.push("current_round = ?");
+    values.push(params.current_round);
+  }
+  if (params.current_map_run !== void 0) {
+    setClauses.push("current_map_run = ?");
+    values.push(params.current_map_run);
+  }
+  if (setClauses.length === 0) {
+    return;
+  }
+  setClauses.push("updated_at = datetime('now')");
+  values.push(id);
+  db.run(
+    `UPDATE sessions SET ${setClauses.join(", ")} WHERE id = ?`,
+    values
+  );
+}
+function getSession(db, id) {
+  return resultToRow(
+    db.exec("SELECT * FROM sessions WHERE id = ?", [id])
+  );
+}
+function getLatestActiveSession(db) {
+  return resultToRow(
+    db.exec(
+      "SELECT * FROM sessions WHERE status = 'active' ORDER BY started_at DESC LIMIT 1"
+    )
+  );
+}
+function getAllSessions(db) {
+  return resultToRows(
+    db.exec("SELECT * FROM sessions ORDER BY started_at DESC")
+  );
+}
+function insertEvent(db, params) {
+  const {
+    session_id,
+    event_type,
+    phase,
+    phase_number,
+    round,
+    metadata
+  } = params;
+  db.run(
+    `INSERT INTO orchestration_events (session_id, event_type, phase, phase_number, round, metadata)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    [
+      session_id,
+      event_type,
+      phase ?? null,
+      phase_number ?? null,
+      round ?? null,
+      metadata ?? null
+    ]
+  );
+}
+function getEventsForSession(db, sessionId) {
+  return resultToRows(
+    db.exec(
+      "SELECT * FROM orchestration_events WHERE session_id = ? ORDER BY id ASC",
+      [sessionId]
+    )
+  );
+}
+function commitReasonClose(db, sessionId, reasonEvent, projectionUpdates) {
+  db.transaction(() => {
+    insertEvent(db, { session_id: sessionId, ...reasonEvent });
+    updateSession(db, sessionId, projectionUpdates);
+  });
+}
+
+// src/lib/db/reconcile.ts
+var DEFAULT_STALE_THRESHOLD_SECONDS = 7 * 24 * 60 * 60;
+function hasTerminalArtifactEvent(db, sessionId, workflowType, currentRound, currentMapRun) {
+  const eventType = workflowType === "map" ? "map_completed" : "round_completed";
+  const round = workflowType === "map" ? currentMapRun : currentRound;
+  const r = db.exec(
+    `SELECT 1 FROM orchestration_events
+       WHERE session_id = ? AND event_type = ? AND round = ? LIMIT 1`,
+    [sessionId, eventType, round]
+  );
+  return (r[0]?.values.length ?? 0) > 0;
+}
+function hasReasonEvent(db, sessionId) {
+  const r = db.exec(
+    `SELECT 1 FROM orchestration_events
+       WHERE session_id = ?
+         AND event_type IN ('session_aborted','session_auto_closed_stale','session_synced','session_legacy_import')
+       LIMIT 1`,
+    [sessionId]
+  );
+  return (r[0]?.values.length ?? 0) > 0;
+}
+function lastEventAgeSeconds(db, sessionId) {
+  const r = db.exec(
+    `SELECT (julianday('now') - julianday(MAX(created_at))) * 86400
+       FROM orchestration_events WHERE session_id = ?`,
+    [sessionId]
+  );
+  const v = r[0]?.values[0]?.[0];
+  return typeof v === "number" ? v : null;
+}
+function hasInFlightDependents(db, sessionId) {
+  const r = db.exec(
+    `SELECT 1 FROM command_executions
+       WHERE workflow_id = ? AND finished_at IS NULL LIMIT 1`,
+    [sessionId]
+  );
+  return (r[0]?.values.length ?? 0) > 0;
+}
+function resolveSessionDir(ocrDir, sessionDir) {
+  if (!sessionDir) return null;
+  if (isAbsolute(sessionDir)) return sessionDir;
+  return join(dirname(ocrDir), sessionDir);
+}
+function reconcileLegacyState(db, ocrDir, opts = {}) {
+  const dryRun = opts.dryRun ?? false;
+  const threshold = opts.staleThresholdSeconds ?? DEFAULT_STALE_THRESHOLD_SECONDS;
+  const actions = [];
+  for (const s of getAllSessions(db)) {
+    const dir = resolveSessionDir(ocrDir, s.session_dir);
+    if (s.status === "closed") {
+      if (hasTerminalArtifactEvent(db, s.id, s.workflow_type, s.current_round, s.current_map_run) || hasReasonEvent(db, s.id)) {
+        continue;
+      }
+      const reviewFinal = s.workflow_type === "review" && dir ? existsSync(join(dir, "rounds", `round-${s.current_round}`, "final.md")) : false;
+      const mapFinal = s.workflow_type === "map" && dir ? existsSync(join(dir, "map", "runs", `run-${s.current_map_run}`, "map.md")) : false;
+      if (reviewFinal) {
+        actions.push({
+          sessionId: s.id,
+          kind: "synthesize-round-completed",
+          detail: `final.md present for round ${s.current_round}; synthesizing round_completed`
+        });
+        if (!dryRun) {
+          insertEvent(db, {
+            session_id: s.id,
+            event_type: "round_completed",
+            phase: "synthesis",
+            phase_number: 7,
+            round: s.current_round,
+            metadata: JSON.stringify({ source: "reconciled", synthesized_from: "final.md" })
+          });
+        }
+      } else if (mapFinal) {
+        actions.push({
+          sessionId: s.id,
+          kind: "synthesize-map-completed",
+          detail: `map.md present for run ${s.current_map_run}; synthesizing map_completed`
+        });
+        if (!dryRun) {
+          insertEvent(db, {
+            session_id: s.id,
+            event_type: "map_completed",
+            phase: "synthesis",
+            phase_number: 5,
+            round: s.current_map_run,
+            metadata: JSON.stringify({ source: "reconciled", synthesized_from: "map.md" })
+          });
+        }
+      } else {
+        actions.push({
+          sessionId: s.id,
+          kind: "grandfather",
+          detail: "no provable artifact; recording session_legacy_import"
+        });
+        if (!dryRun) {
+          insertEvent(db, {
+            session_id: s.id,
+            event_type: "session_legacy_import",
+            phase: "complete",
+            metadata: JSON.stringify({ source: "reconciled" })
+          });
+        }
+      }
+      continue;
+    }
+    const age = lastEventAgeSeconds(db, s.id);
+    const stale = (age === null || age > threshold) && !hasInFlightDependents(db, s.id);
+    if (stale) {
+      actions.push({
+        sessionId: s.id,
+        kind: "stale-close",
+        detail: age === null ? "active with no events and no in-flight dependents" : `active, last event ${Math.round(age / 86400)}d ago, no in-flight dependents`
+      });
+      if (!dryRun) {
+        commitReasonClose(
+          db,
+          s.id,
+          {
+            event_type: "session_auto_closed_stale",
+            phase: "complete",
+            metadata: JSON.stringify({ source: "reconciled", threshold_seconds: threshold })
+          },
+          { status: "closed", current_phase: "complete" }
+        );
+      }
+    }
+  }
+  return { dryRun, actions };
+}
+
+// src/lib/db/liveness.ts
+var PID_REUSE_GUARD_MS = 24 * 60 * 60 * 1e3;
+
+// src/lib/state/exit-codes.ts
+var STATE_EXIT = {
+  OK: 0,
+  USAGE: 2,
+  AMBIGUOUS: 3,
+  NOT_FOUND: 4,
+  ILLEGAL_TRANSITION: 5,
+  INVARIANT_UNMET: 6,
+  SCHEMA_INVALID: 7,
+  /** Database was locked past the bounded retry budget (SQLITE_BUSY). */
+  BUSY: 8
+};
+var StateError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "StateError";
+  }
+};
+var CANCELLED_EXIT_CODE = -2;
+var ORPHAN_EXIT_CODE = -3;
+var CASCADE_CLOSE_EXIT_CODE = -4;
+var WATCHDOG_DEADLINE_EXIT_CODE = -5;
+
+// 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]
+  );
+}
+
+// ../shared/platform/src/index.ts
+import {
+  execFile,
+  execFileSync,
+  spawn
+} from "node:child_process";
+import { promisify } from "node:util";
+var execFilePromise = promisify(execFile);
+var isWindows = process.platform === "win32";
+
+// src/lib/db/maintenance.ts
+var ONE_HOUR_MS = 60 * 60 * 1e3;
+var SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1e3;
+
+// src/lib/db/index.ts
+var V2_SCHEMA_VERSION = 12;
+function maybeSnapshotBeforeUpgrade(db, dbPath, fromVersion) {
+  if (fromVersion < 1 || fromVersion >= V2_SCHEMA_VERSION) return null;
+  const bakPath = `${dbPath}.bak.v${fromVersion}`;
+  if (existsSync2(bakPath)) return bakPath;
+  try {
+    if (!existsSync2(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");
+}
+var connections = /* @__PURE__ */ new Map();
+async function openDatabase(dbPath) {
+  const cached = connections.get(dbPath);
+  if (cached) {
+    return cached;
+  }
+  const dir = dirname2(dbPath);
+  if (!existsSync2(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const db = openEngine(dbPath);
+  connections.set(dbPath, db);
+  return db;
+}
+async function ensureDatabase(ocrDir) {
+  const dataDir = join2(ocrDir, "data");
+  if (!existsSync2(dataDir)) {
+    mkdirSync(dataDir, { recursive: true });
+  }
+  const dbPath = join2(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);
+  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;
+}
+
+// src/lib/state/index.ts
+import { join as join3 } from "node:path";
+
+// src/lib/state/phase-graph.ts
+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(", ")}`
+    );
+  }
+  return n;
+}
+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;
+}
+function initialPhaseFor(workflowType) {
+  return workflowType === "map" ? "map-context" : "context";
+}
+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}`
+    );
+  }
+  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}".`
+    );
+  }
+  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.`
+    );
+  }
+}
+
+// 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) {
+  if (!meta || typeof meta !== "object") {
+    throw new Error("round-meta.json must be a JSON object");
+  }
+  const obj = meta;
+  if (obj.schema_version !== 1) {
+    throw new Error(
+      `Unsupported schema_version: ${String(obj.schema_version)}. Expected 1.`
+    );
+  }
+  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");
+  }
+  for (const reviewer of obj.reviewers) {
+    if (!reviewer || typeof reviewer !== "object") {
+      throw new Error("Each reviewer must be an object");
+    }
+    const r = reviewer;
+    if (typeof r.type !== "string") {
+      throw new Error("Each reviewer must have a type string");
+    }
+    if (typeof r.instance !== "number") {
+      throw new Error("Each reviewer must have an instance number");
+    }
+    if (!Array.isArray(r.findings)) {
+      throw new Error(`Reviewer ${r.type}-${r.instance} must have a findings array`);
+    }
+    for (const finding of r.findings) {
+      if (!finding || typeof finding !== "object") {
+        throw new Error("Each finding must be an object");
+      }
+      const f = finding;
+      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(", ")}`
+        );
+      }
+      if (typeof f.severity !== "string" || !VALID_SEVERITIES.has(f.severity)) {
+        throw new Error(
+          `Finding "${f.title}" has invalid severity: "${String(f.severity)}". Must be one of: ${[...VALID_SEVERITIES].join(", ")}`
+        );
+      }
+      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`);
+      }
+      if (f.line_start !== void 0 && typeof f.line_start !== "number") {
+        throw new Error(`Finding "${f.title}" has invalid line_start: expected number`);
+      }
+      if (f.line_end !== void 0 && typeof f.line_end !== "number") {
+        throw new Error(`Finding "${f.title}" has invalid line_end: expected number`);
+      }
+      if (f.flagged_by !== void 0 && !Array.isArray(f.flagged_by)) {
+        throw new Error(`Finding "${f.title}" has invalid flagged_by: expected array`);
+      }
+    }
+  }
+  if (obj.synthesis_counts !== void 0) {
+    if (!obj.synthesis_counts || typeof obj.synthesis_counts !== "object") {
+      throw new Error("synthesis_counts must be an object");
+    }
+    const sc = obj.synthesis_counts;
+    if (typeof sc.blockers !== "number" || sc.blockers < 0) {
+      throw new Error("synthesis_counts.blockers must be a non-negative number");
+    }
+    if (typeof sc.should_fix !== "number" || sc.should_fix < 0) {
+      throw new Error("synthesis_counts.should_fix must be a non-negative number");
+    }
+    if (typeof sc.suggestions !== "number" || sc.suggestions < 0) {
+      throw new Error("synthesis_counts.suggestions must be a non-negative number");
+    }
+  }
+  return meta;
+}
+function computeRoundCounts(meta) {
+  const allFindings = [];
+  for (const reviewer of meta.reviewers) {
+    allFindings.push(...reviewer.findings);
+  }
+  const sc = meta.synthesis_counts;
+  return {
+    blockerCount: sc ? sc.blockers : allFindings.filter((f) => f.category === "blocker").length,
+    shouldFixCount: sc ? sc.should_fix : allFindings.filter((f) => f.category === "should_fix").length,
+    suggestionCount: sc ? sc.suggestions : allFindings.filter((f) => f.category === "suggestion").length,
+    reviewerCount: meta.reviewers.length,
+    totalFindingCount: allFindings.length
+  };
+}
+
+// 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");
+  }
+  const obj = meta;
+  if (obj.schema_version !== 1) {
+    throw new Error(
+      `Unsupported schema_version: ${String(obj.schema_version)}. Expected 1.`
+    );
+  }
+  if (!Array.isArray(obj.sections)) {
+    throw new Error("map-meta.json must contain a sections array");
+  }
+  for (const section of obj.sections) {
+    if (!section || typeof section !== "object") {
+      throw new Error("Each section must be an object");
+    }
+    const s = section;
+    if (typeof s.section_number !== "number") {
+      throw new Error("Each section must have a section_number");
+    }
+    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`);
+    }
+    for (const file of s.files) {
+      if (!file || typeof file !== "object") {
+        throw new Error("Each file must be an object");
+      }
+      const f = file;
+      if (typeof f.file_path !== "string" || f.file_path.trim().length === 0) {
+        throw new Error("Each file must have a non-empty file_path");
+      }
+      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`);
+      }
+      if (typeof f.lines_deleted !== "number") {
+        throw new Error(`File "${f.file_path}" must have a lines_deleted number`);
+      }
+    }
+  }
+  if (obj.dependencies !== void 0 && !Array.isArray(obj.dependencies)) {
+    throw new Error("map-meta.json dependencies must be an array if provided");
+  }
+  return meta;
+}
+function computeMapCounts(meta) {
+  return {
+    sectionCount: meta.sections.length,
+    fileCount: meta.sections.reduce((sum, s) => sum + s.files.length, 0)
+  };
+}
+
+// src/lib/state/projection.ts
+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 rebuildSessionProjection(db, sessionId) {
+  const events = getEventsForSession(db, sessionId);
+  if (events.length === 0) return null;
+  const acc = {
+    status: "active",
+    current_phase: "context",
+    phase_number: 1,
+    current_round: 1,
+    current_map_run: 1
+  };
+  for (const e of events) {
+    switch (e.event_type) {
+      case "session_created":
+      case "session_resumed":
+      case "round_started":
+        acc.status = "active";
+        if (e.phase) acc.current_phase = e.phase;
+        if (e.phase_number != null) acc.phase_number = e.phase_number;
+        if (e.round != null) acc.current_round = e.round;
+        break;
+      case "phase_transition":
+        if (e.phase) acc.current_phase = e.phase;
+        if (e.phase_number != null) acc.phase_number = e.phase_number;
+        if (e.round != null) acc.current_round = e.round;
+        break;
+      case "round_completed":
+        if (e.round != null && e.round >= acc.current_round) {
+          acc.current_round = e.round;
+        }
+        break;
+      case "map_completed":
+        if (e.round != null) acc.current_map_run = e.round;
+        break;
+      default:
+        if (TERMINAL_EVENT_TYPES.has(e.event_type)) {
+          acc.status = "closed";
+          acc.current_phase = "complete";
+          if (e.phase_number != null) acc.phase_number = e.phase_number;
+        }
+    }
+  }
+  return acc;
+}
+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
+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 readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (hasArtifacts(join3(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 (!existsSync3(params.filePath)) {
+      throw new StateError(STATE_EXIT.NOT_FOUND, `File not found: ${params.filePath}`);
+    }
+    return readFileSync(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 reconcileWorkflowOnExit(ocrDir, sessionId, db) {
+  db ??= await ensureDatabase(ocrDir);
+  const existing = getSession(db, sessionId);
+  if (!existing) return "not-found";
+  if (existing.status === "closed") return "already-closed";
+  if (!hasCompletionInvariant(db, existing)) return "incomplete";
+  if (hasInFlightDependents(db, sessionId)) return "in-flight";
+  await stateClose({ sessionId, ocrDir, abort: false });
+  return "closed";
+}
+async function reconcileCompletedSessions(ocrDir) {
+  const db = await ensureDatabase(ocrDir);
+  const closed = [];
+  for (const s of getAllSessions(db)) {
+    if (s.status !== "active") continue;
+    const outcome = await reconcileWorkflowOnExit(ocrDir, s.id, db);
+    if (outcome === "closed") closed.push(s.id);
+  }
+  return closed;
+}
+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
+    }))
+  };
+}
+async function stateList(ocrDir) {
+  let db;
+  try {
+    db = await ensureDatabase(ocrDir);
+  } catch {
+    return [];
+  }
+  const sessions = getAllSessions(db);
+  return sessions.map((s) => ({
+    id: s.id,
+    branch: s.branch,
+    status: s.status,
+    workflow_type: s.workflow_type,
+    current_phase: s.current_phase,
+    phase_number: s.phase_number,
+    current_round: s.current_round,
+    current_map_run: s.current_map_run,
+    started_at: s.started_at,
+    updated_at: s.updated_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 path = r.decision === "dashboard-uid" ? "via OCR_DASHBOARD_EXECUTION_UID" : "via latest-active";
+  console.error(`[ocr] Auto-detected session: ${r.id} (${path})`);
+}
+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);
+  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 = join3(
+    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 = join3(resolved.session_dir, "rounds", `round-${roundNumber}`, "final.md");
+    if (!existsSync3(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 = join3(resolved.session_dir, "rounds", `round-${roundNumber}`);
+    mkdirSync2(roundDir, { recursive: true });
+    metaPath = roundMetaPath;
+    writeFileSync(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 = join3(
+    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 = join3(resolved.session_dir, "map", "runs", `run-${mapRunNumber}`);
+    mkdirSync2(runDir, { recursive: true });
+    metaPath = mapMetaPath;
+    writeFileSync(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
+    });
+  });
+  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 sessionsRoot = join3(ocrDir, "sessions");
+  if (!existsSync3(sessionsRoot)) {
+    return 0;
+  }
+  const entries = readdirSync(sessionsRoot).filter((name) => {
+    const fullPath = join3(sessionsRoot, name);
+    return statSync2(fullPath).isDirectory();
+  });
+  let synced = 0;
+  for (const dirName of entries) {
+    const dirPath = join3(sessionsRoot, dirName);
+    const existing = getSession(db, dirName);
+    if (existing) {
+      continue;
+    }
+    if (!hasArtifacts(dirPath)) {
+      continue;
+    }
+    const hasRoundsDir = existsSync3(join3(dirPath, "rounds"));
+    const hasMapDir = existsSync3(join3(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 = join3(dirPath, "rounds");
+      if (existsSync3(roundsDir)) {
+        const roundDirs = readdirSync(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 (existsSync3(
+            join3(roundsDir, `round-${latestRoundNum}`, "final.md")
+          )) {
+            inferredPhase = "complete";
+            inferredPhaseNumber = 8;
+          }
+        }
+      }
+    } else if (workflowType === "map") {
+      const runsDir = join3(dirPath, "map", "runs");
+      if (existsSync3(runsDir)) {
+        const runDirs = readdirSync(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 (existsSync3(join3(runsDir, `run-${latestRunNum}`, "map.md"))) {
+            inferredPhase = "complete";
+            inferredPhaseNumber = 6;
+          }
+        }
+      }
+    }
+    insertSession(db, {
+      id: dirName,
+      branch,
+      workflow_type: workflowType,
+      current_phase: inferredPhase,
+      phase_number: inferredPhaseNumber,
+      current_round: inferredRound,
+      current_map_run: inferredMapRun,
+      session_dir: dirPath
+    });
+    commitReasonClose(
+      db,
+      dirName,
+      {
+        event_type: "session_synced",
+        phase: inferredPhase,
+        phase_number: 1,
+        metadata: JSON.stringify({ source: "filesystem_backfill" })
+      },
+      { status: "closed" }
+    );
+    synced++;
+  }
+  return synced;
+}
+export {
+  CANCELLED_EXIT_CODE,
+  CASCADE_CLOSE_EXIT_CODE,
+  MAP_PHASE_NUMBERS,
+  ORPHAN_EXIT_CODE,
+  REASON_EVENT_TYPES,
+  REVIEW_PHASE_NUMBERS,
+  STATE_EXIT,
+  StateError,
+  TERMINAL_EVENT_TYPES,
+  WATCHDOG_DEADLINE_EXIT_CODE,
+  announceResolveDecision,
+  commitReasonClose,
+  computeMapCounts,
+  computeRoundCounts,
+  getCompletenessState,
+  graphFor,
+  hasCompletionInvariant,
+  initialPhaseFor,
+  phaseNumberFor,
+  rebuildSessionProjection,
+  reconcileCompletedSessions,
+  reconcileWorkflowOnExit,
+  resolveActiveSession,
+  resolveSession,
+  sanitizeMetadataString,
+  stateAdvance,
+  stateBegin,
+  stateClose,
+  stateCompleteMap,
+  stateCompleteRound,
+  stateInit,
+  stateList,
+  stateShow,
+  stateStatus,
+  stateSync,
+  stateTransition,
+  validateMapMeta,
+  validatePhaseTransition,
+  validateRoundMeta
+};