code-coordinator 0.5.46__py3-none-any.whl

coord/db.py

@@ -0,0 +1,1076 @@
+"""SQLite connection management and schema for coordinator state.
+
+Single DB at ~/.coord/coord.db with WAL mode.  All coordinator state lives
+here: assignments, proposals, merge queue, sessions, etc.
+
+Usage
+-----
+- Production code: ``get_connection()`` returns the singleton connection.
+- Tests: call ``override_connection(sqlite3.connect(":memory:"))`` then
+  ``close()`` in teardown (the ``coord_db`` fixture in conftest.py does this).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+
+from coord.platform_paths import default_coord_dir
+
+COORD_DIR = default_coord_dir()
+DB_PATH = COORD_DIR / "coord.db"
+
+_conn: sqlite3.Connection | None = None
+
+
+class ProductionDatabaseGuardError(RuntimeError):
+    """Raised when code running under pytest tries to open the live
+    ``~/.coord/coord.db`` (#1960).
+
+    The autouse ``coord_db`` fixture in ``tests/conftest.py`` overrides the
+    module-level singleton with an isolated ``:memory:`` connection before
+    every test body runs, so ``get_connection()`` normally never reaches
+    ``_open()`` at all during a test. This guard exists for the paths that
+    fixture can't reach: code that calls ``_open(DB_PATH)`` directly, a
+    subprocess the test spawned that re-imports ``coord.db`` fresh (pytest's
+    ``PYTEST_CURRENT_TEST`` env var is inherited by child processes by
+    default), or a test that closes the override and lets the singleton fall
+    back to the real path.
+    """
+
+
+def get_connection() -> sqlite3.Connection:
+    """Return the module-level singleton connection, opening it on first call."""
+    global _conn
+    if _conn is None:
+        _conn = _open(DB_PATH)
+    return _conn
+
+
+def _open(path: Path) -> sqlite3.Connection:
+    if path == DB_PATH and os.environ.get("PYTEST_CURRENT_TEST"):
+        raise ProductionDatabaseGuardError(
+            f"Refusing to open the production coordinator database at "
+            f"{path} while running under pytest "
+            f"(PYTEST_CURRENT_TEST={os.environ['PYTEST_CURRENT_TEST']!r}). "
+            "A test (or a subprocess it spawned) resolved the real "
+            "~/.coord/coord.db instead of an isolated one -- see #1960. "
+            "Fix: rely on the autouse `coord_db` fixture (already active for "
+            "every test and overrides this singleton with an in-memory DB), "
+            "or pass an explicit isolated path instead of coord.db.DB_PATH."
+        )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path), check_same_thread=False)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=5000")
+    conn.execute("PRAGMA foreign_keys=ON")
+    conn.row_factory = sqlite3.Row
+    _ensure_schema(conn)
+    _maybe_migrate_json(conn)
+    _migrate_gate_order(conn)
+    _backfill_orphaned_review_verdicts(conn)
+    return conn
+
+
+def override_connection(conn: sqlite3.Connection) -> None:
+    """Replace the singleton connection.  Used in tests to inject :memory: DBs."""
+    global _conn
+    _conn = conn
+
+
+def close() -> None:
+    """Close the singleton connection and reset it to None."""
+    global _conn
+    if _conn is not None:
+        _conn.close()
+        _conn = None
+
+
+# ── Schema ────────────────────────────────────────────────────────────────────
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    """Create all tables and indexes if they don't already exist."""
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS schema_version (
+            version INTEGER NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS assignments (
+            assignment_id TEXT PRIMARY KEY,
+            machine_name TEXT NOT NULL,
+            repo_name TEXT NOT NULL,
+            repo_github TEXT,
+            issue_number INTEGER NOT NULL,
+            issue_title TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'running',
+            type TEXT NOT NULL DEFAULT 'work',
+            branch TEXT,
+            pr_url TEXT,
+            briefing TEXT DEFAULT '',
+            files_allowed TEXT DEFAULT '[]',
+            files_forbidden TEXT DEFAULT '[]',
+            model TEXT,
+            dispatched_at REAL,
+            finished_at REAL,
+            smoke_test TEXT,
+            smoke_test_reason TEXT,
+            review_state TEXT,
+            review_of_assignment_id TEXT,
+            review_target TEXT,
+            required_gates TEXT DEFAULT '[]',
+            plan TEXT,
+            unreachable_count INTEGER DEFAULT 0,
+            exit_code INTEGER,
+            review_iteration INTEGER DEFAULT 0,
+            review_posted_at REAL,
+            test_state TEXT,
+            test_reason TEXT,
+            cost_usd REAL,
+            smoke_tests TEXT,
+            review_findings TEXT,
+            test_plan TEXT
+        );
+
+        CREATE TABLE IF NOT EXISTS notifications (
+            assignment_id TEXT PRIMARY KEY,
+            event TEXT NOT NULL,
+            branch TEXT,
+            posted_at REAL NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS proposals (
+            id INTEGER PRIMARY KEY,
+            machine_name TEXT NOT NULL,
+            repo_name TEXT NOT NULL,
+            issue_number INTEGER NOT NULL,
+            issue_title TEXT NOT NULL,
+            rationale TEXT DEFAULT '',
+            files_likely TEXT DEFAULT '[]',
+            briefing TEXT DEFAULT '',
+            model TEXT,
+            type TEXT DEFAULT 'work',
+            required_gates TEXT DEFAULT '[]'
+        );
+
+        CREATE TABLE IF NOT EXISTS split_proposals (
+            id INTEGER PRIMARY KEY,
+            repo_name TEXT NOT NULL,
+            issue_number INTEGER NOT NULL,
+            issue_title TEXT NOT NULL,
+            rationale TEXT DEFAULT ''
+        );
+
+        CREATE TABLE IF NOT EXISTS split_chunks (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            split_proposal_id INTEGER NOT NULL REFERENCES split_proposals(id),
+            title TEXT NOT NULL,
+            scope TEXT NOT NULL,
+            files_likely TEXT DEFAULT '[]'
+        );
+
+        CREATE TABLE IF NOT EXISTS merge_queue (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            assignment_id TEXT NOT NULL,
+            repo_name TEXT NOT NULL,
+            repo_github TEXT NOT NULL,
+            branch TEXT NOT NULL,
+            target_branch TEXT NOT NULL,
+            issue_number INTEGER NOT NULL,
+            issue_title TEXT NOT NULL,
+            state TEXT NOT NULL DEFAULT 'pending',
+            pr_number INTEGER,
+            pr_url TEXT,
+            size INTEGER,
+            last_attempt REAL,
+            error TEXT,
+            enqueued_at REAL,
+            assignment_type TEXT DEFAULT 'work',
+            required_gates TEXT,
+            ci_infra_reruns INTEGER NOT NULL DEFAULT 0
+        );
+
+        CREATE TABLE IF NOT EXISTS plans (
+            assignment_id TEXT PRIMARY KEY,
+            plan_data TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS sessions (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            started_at TEXT,
+            ended_at TEXT,
+            clean_shutdown INTEGER DEFAULT 0,
+            completed_this_session TEXT,
+            issues_closed TEXT,
+            total_cost_usd REAL
+        );
+
+        CREATE TABLE IF NOT EXISTS machines (
+            name TEXT PRIMARY KEY,
+            host TEXT NOT NULL,
+            capabilities TEXT DEFAULT '[]',
+            repos TEXT DEFAULT '[]'
+        );
+
+        CREATE TABLE IF NOT EXISTS board_meta (
+            key TEXT PRIMARY KEY,
+            value TEXT
+        );
+
+        CREATE TABLE IF NOT EXISTS issues (
+            repo_name  TEXT    NOT NULL,
+            number     INTEGER NOT NULL,
+            title      TEXT    NOT NULL DEFAULT '',
+            body       TEXT    NOT NULL DEFAULT '',
+            state      TEXT    NOT NULL DEFAULT 'open',
+            labels     TEXT    NOT NULL DEFAULT '[]',
+            synced_at  REAL,
+            PRIMARY KEY (repo_name, number)
+        );
+
+        -- #603: per-issue rolling context digest.  Short-lived curated notes
+        -- (cross-repo deps, failed approaches, hard constraints) that every
+        -- agent reads at the top of its briefing.  Structured entries rendered
+        -- to markdown at read time; pinned rows stay on top, newest-first
+        -- below, oldest non-pinned aged out by a budget; dropped on close.
+        CREATE TABLE IF NOT EXISTS issue_context (
+            id           INTEGER PRIMARY KEY,
+            repo_name    TEXT    NOT NULL,
+            issue_number INTEGER NOT NULL,
+            pinned       INTEGER NOT NULL DEFAULT 0,
+            source       TEXT,
+            body         TEXT    NOT NULL,
+            created_at   REAL    NOT NULL
+        );
+
+        -- #1036: durable, append-only audit trail.  One row per real
+        -- state-changing transition, captured at the state._*_local /
+        -- issue_store write choke points (never at the ~30 CLI call
+        -- sites) so the log is topology-agnostic (thin-client vs daemon).
+        -- Modeled on issue_context above: additive, no UPDATE/DELETE
+        -- except the opportunistic audit.max_rows trim in coord/audit.py.
+        CREATE TABLE IF NOT EXISTS audit_log (
+            id            INTEGER PRIMARY KEY AUTOINCREMENT,
+            ts            REAL    NOT NULL,
+            tier          TEXT    NOT NULL,
+            category      TEXT    NOT NULL,
+            event_type    TEXT    NOT NULL,
+            actor         TEXT    NOT NULL,
+            repo          TEXT,
+            issue         INTEGER,
+            assignment_id TEXT,
+            machine       TEXT,
+            summary       TEXT    NOT NULL DEFAULT '',
+            details_json  TEXT
+        );
+
+        -- #873: durable, queryable mirror of GitHub issue comments — the
+        -- prose message bus (completion summaries, review bodies, failure
+        -- reports) today lives only on GitHub. Populated two ways: (1)
+        -- capture-at-write, instrumented at the single choke point
+        -- coord.github_ops.post_issue_comment (which close_issue/close_pr
+        -- also funnel through), so a coord-authored comment is durable the
+        -- instant it posts, regardless of which machine posted it; (2) the
+        -- backfill sync (coord.state.sync_issue_comments), which upserts
+        -- human + out-of-band comments idempotently keyed on gh_comment_id.
+        -- Retained INDEFINITELY — never pruned on close, unlike the
+        -- short-lived issue_context digest above.
+        --
+        -- repo_name here holds whatever identifier the write site had —
+        -- in practice the GitHub "owner/repo" slug (github_ops functions
+        -- only ever see the slug, never the coordinator's config repo
+        -- key) — which differs from the issues/issue_context tables above
+        -- where repo_name is the coordinator.yml repo key. Documented here
+        -- since it's a real inconsistency a future reader could trip on.
+        --
+        -- created_at/updated_at are epoch seconds (REAL), matching the
+        -- rest of this schema's timestamp columns. body_ref is reserved,
+        -- unused for now — the future Azure-blob offload seam.
+        CREATE TABLE IF NOT EXISTS issue_comments (
+            id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+            gh_comment_id       INTEGER UNIQUE,
+            repo_name           TEXT    NOT NULL,
+            issue_number        INTEGER NOT NULL,
+            author              TEXT,
+            created_at          REAL,
+            updated_at          REAL,
+            body                TEXT    NOT NULL DEFAULT '',
+            body_ref            TEXT,
+            coord_event         TEXT,
+            coord_assignment_id TEXT,
+            machine             TEXT,
+            verdict             TEXT
+        );
+
+        -- #1505: board-visible "driver stuck" record.  Written by `coord
+        -- drive`'s merge stage the moment it hits a status no amount of
+        -- retrying can fix (NEEDS_ATTENTION / an unrecognised status) instead
+        -- of silently burning the merge-attempt budget on it (see
+        -- coord/drive.py's `_decide_merge`).  One row per (repo_name,
+        -- issue_number) — a fresh escalation replaces the previous one
+        -- (`ON CONFLICT ... DO UPDATE`, coord/state.py
+        -- `_record_drive_escalation_local`); `coord escalate dismiss` (or the
+        -- TUI's "Dismiss" menu item) deletes it outright. `gate_readings` is
+        -- a human-readable "key=value | key=value" summary, not JSON — the
+        -- whole record exists to be read by a human via the Pipeline row's
+        -- right-click menu, not machine-parsed.
+        CREATE TABLE IF NOT EXISTS drive_escalations (
+            id               INTEGER PRIMARY KEY AUTOINCREMENT,
+            repo_name        TEXT    NOT NULL,
+            issue_number     INTEGER NOT NULL,
+            stage            TEXT    NOT NULL DEFAULT 'merge',
+            assignment_id    TEXT,
+            reason           TEXT    NOT NULL,
+            gate_readings    TEXT    NOT NULL DEFAULT '',
+            proposed_command TEXT    NOT NULL DEFAULT '',
+            created_at       REAL    NOT NULL,
+            UNIQUE(repo_name, issue_number)
+        );
+
+        -- #1753 (DQ-1): the operator-declared `coord drive` work queue.  One
+        -- row per (repo_name, issue_number) — enqueueing an issue that is
+        -- already queued updates it in place (`ON CONFLICT ... DO UPDATE`,
+        -- coord/state.py `_enqueue_drive_queue_local`) rather than creating a
+        -- second row, so the queue can never hold the same issue twice.
+        -- Written by `coord drive-queue` (DQ-2) and by the tick processor that
+        -- launches entries; cleared by `coord drive-queue remove` (dequeue) —
+        -- terminal rows (`done`/`failed`) stay put until an operator removes
+        -- them, so the list doubles as a short run history.
+        --
+        -- `position` is DENSE and 0-BASED: enqueue-without-a-position appends
+        -- at max(position)+1 and `move` renumbers the affected span in one
+        -- transaction (no fractional positions — the queue is short by nature
+        -- and `coord drive-queue list` prints a dense integer order).
+        -- `machine` NULL means "let `coord drive` route it".  `after_json` is
+        -- a JSON list of FULLY QUALIFIED pre-req keys (`["repo#N", ...]`) so a
+        -- cross-repo queue needs no second column; it is decoded to a real
+        -- list on the wire via coord/dao.py's `_JSON_COLUMNS`.  This table
+        -- only STORES `after_json` — interpreting it (pre-req satisfaction) is
+        -- the tick processor's job, not the schema's.
+        --
+        -- #1757 (deploy gates) added the five `hold_*`/`resume_when` columns
+        -- below.  They are declared here so a FRESH database gets them from
+        -- the CREATE, and repeated in `_migrate_add_columns` so an EXISTING
+        -- ~/.coord/coord.db (DQ-1 shipped before this) gains them in place —
+        -- SQLite has no "ADD COLUMN IF NOT EXISTS", hence both.  See
+        -- coord/drive_queue.py for the lifecycle those columns encode.
+        --
+        -- #1870: `launch_host` is the SHORT HOSTNAME of the machine whose tick
+        -- actually ran `coord drive --tmux` for this entry — set alongside
+        -- `session_name`/`launched_at` when the launch succeeds, '' for a row
+        -- that predates this column or was hand-flipped to `running`.
+        -- Liveness (`coord.drive.list_drive_sessions`) is always a LOCAL tmux
+        -- read; without this column a tick running on a DIFFERENT host than
+        -- the one that launched the drive has no way to know that, sees no
+        -- session, and reaps a healthy drive out from under another machine
+        -- (the 2026-08-06 incident: a drive 47 minutes into Test on
+        -- `elitebook` was declared dead and relaunched by the timer on
+        -- `dellserver`).  `_reconcile_running` treats a mismatch as UNKNOWN,
+        -- never as dead — see coord/drive_queue.py.
+        CREATE TABLE IF NOT EXISTS drive_queue (
+            id            INTEGER PRIMARY KEY AUTOINCREMENT,
+            repo_name     TEXT    NOT NULL,
+            issue_number  INTEGER NOT NULL,
+            position      INTEGER NOT NULL,
+            machine       TEXT,
+            after_json    TEXT    NOT NULL DEFAULT '[]',
+            state         TEXT    NOT NULL DEFAULT 'waiting',
+            attempts      INTEGER NOT NULL DEFAULT 0,
+            deferrals     INTEGER NOT NULL DEFAULT 0,
+            last_reason   TEXT    NOT NULL DEFAULT '',
+            session_name  TEXT,
+            launched_at   REAL,
+            enqueued_at   REAL    NOT NULL,
+            hold_after    INTEGER NOT NULL DEFAULT 0,
+            hold_reason   TEXT    NOT NULL DEFAULT '',
+            resume_when   TEXT    NOT NULL DEFAULT '',
+            hold_state    TEXT    NOT NULL DEFAULT '',
+            hold_probes   INTEGER NOT NULL DEFAULT 0,
+            launch_host   TEXT    NOT NULL DEFAULT '',
+            UNIQUE(repo_name, issue_number)
+        );
+
+        -- #1630: daemon's aggregated view of each agent's /health payload
+        -- (H-1's check-registry results, when the agent reports them) plus
+        -- the poll's own reachability verdict.  One row per machine, always
+        -- overwritten in place (`ON CONFLICT ... DO UPDATE`,
+        -- coord/state.py `save_machine_health`) — this is a live snapshot,
+        -- not a history. `received_at` is THIS daemon's clock at poll time,
+        -- not anything the agent claims, so staleness detection (an agent
+        -- that stops reporting must read `unknown`, never "still green")
+        -- can never be fooled by a stopped agent's stale self-reported
+        -- timestamp. `health_json` is NULL for an unreachable machine or an
+        -- agent too old to report a health block — advisory only, never
+        -- consulted by dispatch/routing/merge-queue code (see
+        -- tests/test_health_advisory_only.py).
+        CREATE TABLE IF NOT EXISTS machine_health (
+            machine_name TEXT PRIMARY KEY,
+            state        TEXT    NOT NULL,
+            reason       TEXT    NOT NULL DEFAULT '',
+            latency_ms   REAL,
+            health_json  TEXT,
+            received_at  REAL    NOT NULL
+        );
+
+        -- #2048: per-assignment tracking state for the cheap per-turn
+        -- liveness auditor (coord/liveness_auditor.py). One row per
+        -- assignment ever audited; consecutive_blocked is the running
+        -- streak of BLOCKED verdicts (reset to 0 by any continue/done),
+        -- and `raised` flips to 1 the one time the streak first reaches
+        -- the configured strike count, so a stall is reported once rather
+        -- than on every subsequent poll while the worker stays blocked.
+        -- Read/written ONLY by coord.notify.detect_liveness_stall and
+        -- coord.state's accessors below — never by anything that also
+        -- touches Assignment.status/review_state/test_state (the auditor
+        -- is a tripwire, not a gate).
+        CREATE TABLE IF NOT EXISTS liveness_audits (
+            assignment_id       TEXT PRIMARY KEY,
+            consecutive_blocked INTEGER NOT NULL DEFAULT 0,
+            last_audit_at       REAL,
+            last_verdict        TEXT,
+            raised              INTEGER NOT NULL DEFAULT 0
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_assignments_status ON assignments(status);
+        CREATE INDEX IF NOT EXISTS idx_assignments_machine ON assignments(machine_name);
+        CREATE INDEX IF NOT EXISTS idx_merge_queue_state ON merge_queue(state);
+        CREATE INDEX IF NOT EXISTS idx_issue_context_issue
+            ON issue_context(repo_name, issue_number);
+        CREATE INDEX IF NOT EXISTS idx_audit_log_ts ON audit_log(ts);
+        CREATE INDEX IF NOT EXISTS idx_audit_log_assignment ON audit_log(assignment_id);
+        CREATE INDEX IF NOT EXISTS idx_issue_comments_issue
+            ON issue_comments(repo_name, issue_number);
+        CREATE INDEX IF NOT EXISTS idx_drive_escalations_issue
+            ON drive_escalations(repo_name, issue_number);
+        CREATE INDEX IF NOT EXISTS idx_drive_queue_state
+            ON drive_queue(state, position);
+
+        INSERT OR IGNORE INTO schema_version VALUES (1);
+    """)
+    conn.commit()
+    # Column-level migrations for existing databases.  SQLite does not support
+    # "ADD COLUMN IF NOT EXISTS", so we catch OperationalError instead.
+    _migrate_add_columns(conn)
+
+
+def _migrate_add_columns(conn: sqlite3.Connection) -> None:
+    """Add new columns to existing databases via ALTER TABLE.
+
+    Safe to call on databases that already have the columns — the
+    OperationalError raised by SQLite is silently swallowed.
+    """
+    migrations = [
+        "ALTER TABLE assignments ADD COLUMN review_iteration INTEGER DEFAULT 0",
+        "ALTER TABLE assignments ADD COLUMN review_posted_at REAL",
+        # #200: human-driven Test gate between Work and Review.
+        "ALTER TABLE assignments ADD COLUMN test_state TEXT",
+        "ALTER TABLE assignments ADD COLUMN test_reason TEXT",
+        # #253: persisted adversarial-review verdict so the merge gate can
+        # check approval without re-parsing logs after restart.
+        "ALTER TABLE assignments ADD COLUMN review_verdict TEXT",
+        # #208: worker cost captured from the final stream-json result event.
+        "ALTER TABLE assignments ADD COLUMN cost_usd REAL",
+        # #252: worker-emitted smoke-test list (JSON array of strings;
+        # NULL = not emitted, '[]' = explicit "(none — internal)").
+        "ALTER TABLE assignments ADD COLUMN smoke_tests TEXT",
+        # #bounce: cached review-findings body (markdown text) so coord
+        # bounce + the upcoming per-stage display don't have to re-fetch
+        # the review log from the agent.  Populated by notify.py when
+        # the review is first parsed.  NULL = not yet parsed; populated
+        # = full findings.body text.
+        "ALTER TABLE assignments ADD COLUMN review_findings TEXT",
+        # #315: claude session ID captured from the worker's `system.init`
+        # event.  Set by notify.py after the agent reports completion.  Used
+        # by `coord chat-continue` to pass `--resume <id>` to the next
+        # worker so it loads the prior conversation and continues it.
+        "ALTER TABLE assignments ADD COLUMN claude_session_id TEXT",
+        # #342 Phase A: AI-generated smoke test plan (JSON-encoded).
+        # NULL = not yet generated.  Set by `coord test-plan` and read back
+        # by the CLI (cache hit) and eventually by the TUI (Phase B).
+        "ALTER TABLE assignments ADD COLUMN test_plan TEXT",
+        # #349 Phase B: branch HEAD SHA at the time `coord test-plan` last ran.
+        # Used by the TUI to detect staleness: if the branch has advanced
+        # since the plan was generated, it re-runs `coord test-plan --refresh`
+        # automatically.  NULL = plan not yet generated, or generated without
+        # branch tracking (legacy).  Always reset to NULL when set_test_plan
+        # is called with branch_head=None so no stale SHA persists.
+        "ALTER TABLE assignments ADD COLUMN test_plan_branch_head TEXT",
+        # #406 Phase A: milestone columns on the issues table.
+        # milestone_number is the GitHub milestone number (integer id); NULL for
+        # unassigned.  milestone_title is the human-readable name (e.g. "v0.5");
+        # NULL when no milestone is assigned.  Idempotent — SQLite raises
+        # OperationalError when the column already exists, which is swallowed
+        # below.
+        "ALTER TABLE issues ADD COLUMN milestone_number INTEGER",
+        "ALTER TABLE issues ADD COLUMN milestone_title TEXT",
+        # #324: resolved provider name recorded at dispatch time so the TUI
+        # can surface it in the assignment detail panel (#327).  NULL for rows
+        # dispatched before #324 landed; the TUI shows "claude" as the
+        # implicit default when the column is NULL.
+        "ALTER TABLE assignments ADD COLUMN provider_name TEXT",
+        # #546: token counts for automated (claude -p) assignments, parsed from
+        # the final stream-json result event alongside cost_usd.  All default
+        # 0 so the TUI can sum them without NULLs.  Interactive (Max/OAuth)
+        # sessions do not bill per-token; those rows stay at 0 and the TUI
+        # labels them "Max (subscription)" rather than showing a dollar figure.
+        "ALTER TABLE assignments ADD COLUMN input_tokens INTEGER DEFAULT 0",
+        "ALTER TABLE assignments ADD COLUMN output_tokens INTEGER DEFAULT 0",
+        "ALTER TABLE assignments ADD COLUMN cache_creation_tokens INTEGER DEFAULT 0",
+        "ALTER TABLE assignments ADD COLUMN cache_read_tokens INTEGER DEFAULT 0",
+        # #546: track whether an assignment ran as a human-attended interactive
+        # session (Max/Pro subscription).  Used by the TUI to show
+        # "Max (subscription)" accurately without misidentifying old automated
+        # rows that also lack cost_usd + token data.
+        "ALTER TABLE assignments ADD COLUMN is_interactive INTEGER DEFAULT 0",
+        # #618: short human-readable reason for a launch failure (e.g.
+        # "branch already checked out at ~/.coord/worktrees/<old-aid>").
+        # Written by the CLI immediately when an interactive session can't
+        # start so the TUI can explain the red box without any log file.
+        # NULL for assignments that launched successfully.
+        "ALTER TABLE assignments ADD COLUMN failure_reason TEXT",
+        # #776 (Merge Queue v2-A): track when an entry was added to the queue
+        # so the merge plan can display age and sort stably.  NULL for entries
+        # created before this migration ran.
+        "ALTER TABLE merge_queue ADD COLUMN enqueued_at REAL",
+        # #821: commit-bound review gate — SHA of the branch HEAD at the time
+        # the review assignment ran.  When both this column and the merge-queue
+        # entry's branch_head_sha are populated and differ, `has_approved_review`
+        # treats the approval as stale (new commits since the review → re-review
+        # required).  NULL for rows predating this feature.
+        "ALTER TABLE assignments ADD COLUMN review_head_sha TEXT",
+        # #944: the Acceptance-gate verdict (oracle loop, docs/ORACLE_LOOP.md)
+        # — set by `coord acceptance record --issue N --sha <sha>`, the
+        # coordinator's external re-run of the sealed suite against the
+        # pushed SHA. NULL until a record has run. acceptance_reason carries
+        # a short failing-test summary (mirrors test_reason); acceptance_sha
+        # is the exact commit the verdict was recorded against, so staleness
+        # (new commits since the last record) is detectable the same way
+        # review_head_sha detects a stale review approval.
+        "ALTER TABLE assignments ADD COLUMN acceptance_state TEXT",
+        "ALTER TABLE assignments ADD COLUMN acceptance_reason TEXT",
+        "ALTER TABLE assignments ADD COLUMN acceptance_sha TEXT",
+        # #932: per-test counts alongside acceptance_state, so the Acceptance
+        # box can render "3/7 acceptance green" instead of a bare verdict.
+        "ALTER TABLE assignments ADD COLUMN acceptance_total INTEGER",
+        "ALTER TABLE assignments ADD COLUMN acceptance_passed INTEGER",
+        # #874: persist the worker's ### Summary prose block so the TUI's
+        # Summary tab has a durable, board-sourced field.  NULL when the
+        # worker emitted no summary (best-effort; never blocks completion).
+        "ALTER TABLE assignments ADD COLUMN completion_summary TEXT",
+        # #886 Phase 2: structured Milestone Outcome Audit verdict. Written by
+        # issue_store._persist_audit_result for type="audit" assignments only
+        # (the epic's issue_number doubles as the audit's issue_number — see
+        # #885's _dispatch_audit_of). audit_goals_json is a JSON array of
+        # {goal, metric_before, metric_after, verdict (met|partial|gap),
+        # evidence} — kept as a raw JSON string on the wire, same convention
+        # as review_findings above. audit_run_number increments once per
+        # `--audit-of <epic>` run against the same (repo_name, issue_number)
+        # so later runs can diff against earlier ones. NULL for every row
+        # predating this feature and for non-audit assignment types.
+        "ALTER TABLE assignments ADD COLUMN audit_goals_json TEXT",
+        "ALTER TABLE assignments ADD COLUMN audit_bottom_line TEXT",
+        "ALTER TABLE assignments ADD COLUMN audit_run_number INTEGER",
+        # #1077: the originating assignment's `type` (e.g. "work",
+        # "mock-author"), so the merge processor can tell whether merging
+        # this entry's PR should deterministically close `issue_number` —
+        # see coord.models.CLOSES_ISSUE_TYPES. Existing rows default to
+        # 'work', preserving the prior always-close behavior for entries
+        # enqueued before this column existed.
+        "ALTER TABLE merge_queue ADD COLUMN assignment_type TEXT DEFAULT 'work'",
+        # #1084: for type="test-author" JIT-mode assignments, the work-order
+        # member issue this dispatch is extending the acceptance suite for —
+        # see coord.models.Assignment.for_issue_number. NULL for milestone-
+        # mode (Gate A) authoring, every other assignment type, and rows
+        # predating this column.
+        "ALTER TABLE assignments ADD COLUMN for_issue_number INTEGER",
+        # #1213: snapshot of the originating assignment's resolved
+        # required_gates (JSON array; NULL/'[]' = no per-issue override —
+        # callers fall back to config.pipeline.default_gates), captured at
+        # enqueue time so the review/smoke merge gates are commit-bound
+        # rather than re-resolved from the live board at merge time. NULL
+        # for rows predating this column, which fall back the same way.
+        "ALTER TABLE merge_queue ADD COLUMN required_gates TEXT",
+        # #1456: audit trail for a coordinator override of a reviewer's verdict
+        # (the #476 approve-with-nits gate).  `review_verdict_original` holds
+        # the reviewer's own verdict and `review_verdict_override_reason` the
+        # parsed counts that justified the override; `review_verdict` keeps the
+        # effective value the merge gate reads.  NULL for every row where the
+        # coordinator never overrode anything, and for rows predating this
+        # column — see coord.models.Assignment.review_verdict_original.
+        "ALTER TABLE assignments ADD COLUMN review_verdict_original TEXT",
+        "ALTER TABLE assignments ADD COLUMN review_verdict_override_reason TEXT",
+        # #1475: content-addressed fingerprint of the diff a review approved
+        # (`git patch-id --stable`), captured alongside `review_head_sha`. A
+        # rebase that changes no content produces the same patch-id even
+        # though the branch's HEAD SHA moved, so `has_approved_review` can
+        # carry the approval forward instead of re-blocking on the #821 SHA
+        # check. NULL for rows predating this column or where the patch-id
+        # could not be computed — those fall back to today's SHA-only
+        # staleness behaviour (fail closed).
+        "ALTER TABLE assignments ADD COLUMN review_patch_id TEXT",
+        # #1479: Test-gate staleness anchor, captured (best-effort) alongside
+        # a terminal test_state write in
+        # `coord.state._record_test_verdict_local`. `test_head_sha` /
+        # `test_patch_id` mirror `review_head_sha` / `review_patch_id`
+        # (#821/#1475) for the branch's own content; `test_base_sha` is the
+        # NEW piece — the target/merge branch's HEAD SHA at test time, so
+        # `coord.merge_queue.has_smoke_verdict` can detect a base that moved
+        # out from under an otherwise content-identical branch (a rebase can
+        # break tests without changing the branch's own diff). NULL for rows
+        # predating this column or where the anchor couldn't be computed —
+        # those fall back to today's no-staleness-check behavior (fail open).
+        "ALTER TABLE assignments ADD COLUMN test_head_sha TEXT",
+        "ALTER TABLE assignments ADD COLUMN test_patch_id TEXT",
+        "ALTER TABLE assignments ADD COLUMN test_base_sha TEXT",
+        # #1476: audit trail for a SCOPED re-review — dispatched when a
+        # conflict-fix rebase changed content under an already-approved
+        # review (patch-id mismatch) but no other work/fix commit
+        # intervened. `review_scoped` marks the review row as scoped (vs. a
+        # full re-review of the whole PR); `review_scope_base_sha` records
+        # the prior review's `review_head_sha` — the commit the resolution
+        # delta was computed from — so a later audit can distinguish
+        # "reviewed the 15-line resolution" from "reviewed the whole PR".
+        # 0/NULL for every row predating this column and for ordinary
+        # (non-scoped) reviews.
+        "ALTER TABLE assignments ADD COLUMN review_scoped INTEGER DEFAULT 0",
+        "ALTER TABLE assignments ADD COLUMN review_scope_base_sha TEXT",
+        # #1499: durable provenance — `f"drive:{repo}#{issue}"` when this
+        # assignment was dispatched by `coord drive` (via `coord assign
+        # --driven-by`), NULL for a hand `coord assign` and for every row
+        # predating this column. This is the piece that survives the
+        # driver process exiting — see coord.models.Assignment.driven_by.
+        "ALTER TABLE assignments ADD COLUMN driven_by TEXT",
+        # #1629 (H-2): the toolchain string that produced a Test-gate
+        # verdict — e.g. "rustc 1.95.0" or "python 3.12.4, node 20.11.0" —
+        # captured (best-effort) alongside `test_state` in
+        # `coord.state._record_test_verdict_local`. Annotation only: nothing
+        # reads this to gate dispatch/review/merge (see
+        # coord.health.checks.toolchain's fleet_toolchain_skew, which is the
+        # thing that actually judges skew). NULL for every row predating
+        # this column and for any verdict recorded without a resolvable
+        # toolchain — a historical/unknown value, never treated as a mismatch.
+        "ALTER TABLE assignments ADD COLUMN test_toolchain TEXT",
+        # #1757 (deploy gates): mark a queue entry so that when it completes,
+        # the tick STOPS launching and waits for a human deploy step —
+        # `merged != live` is this repo's most-repeated operational lesson and
+        # a queue that models merge but not deploy sequences work straight into
+        # it, unattended.  DQ-1 shipped before this, so an existing
+        # ~/.coord/coord.db is upgraded in place here (the same columns are in
+        # `_ensure_schema`'s CREATE for fresh databases; the duplicate-column
+        # OperationalError is swallowed below).
+        #
+        #   hold_after   0/1 — this entry ends with a deploy gate
+        #   hold_reason  shown to the operator when the gate fires
+        #   resume_when  optional probe command; '' = manual resume only
+        #   hold_state   ''|armed|fired|released (coord/drive_queue.py)
+        #   hold_probes  consecutive failed `resume_when` runs since the gate
+        #                fired — a TYPED count, so the alert's rising attempt
+        #                number never has to be parsed back out of prose
+        #                (#1523 §2: typed state, never CLI prose).
+        "ALTER TABLE drive_queue ADD COLUMN hold_after INTEGER NOT NULL DEFAULT 0",
+        "ALTER TABLE drive_queue ADD COLUMN hold_reason TEXT NOT NULL DEFAULT ''",
+        "ALTER TABLE drive_queue ADD COLUMN resume_when TEXT NOT NULL DEFAULT ''",
+        "ALTER TABLE drive_queue ADD COLUMN hold_state TEXT NOT NULL DEFAULT ''",
+        "ALTER TABLE drive_queue ADD COLUMN hold_probes INTEGER NOT NULL DEFAULT 0",
+        # #1870: the short hostname of the machine that actually launched this
+        # entry's `coord drive --tmux` — see the CREATE TABLE comment above.
+        # '' for every row written before this migration; `_reconcile_running`
+        # treats that exactly like "launched here" (today's behaviour).
+        "ALTER TABLE drive_queue ADD COLUMN launch_host TEXT NOT NULL DEFAULT ''",
+        # #1892: count of automatic `CiStore.rerun_for_pr` calls `merge_queue
+        # .process()` has issued for this entry's current verdictless-CI-
+        # failure streak — see `coord.merge_queue.MAX_CI_INFRA_RERUNS` and
+        # `QueuedMerge.ci_infra_reruns`'s docstring. 0 for every row
+        # predating this column (no auto-reruns spent yet), same as the
+        # column's own default for freshly-enqueued entries.
+        "ALTER TABLE merge_queue ADD COLUMN ci_infra_reruns INTEGER NOT NULL DEFAULT 0",
+        # #1956: verdict provenance — WHO recorded `review_verdict` and HOW
+        # (see coord.models.Assignment.verdict_source for the three values
+        # and why conflating them was the second half of #1956). NULL for
+        # every row predating this column and for the common case (the
+        # reviewer's own log was parsed) — callers treat NULL identically to
+        # "agent".
+        "ALTER TABLE assignments ADD COLUMN verdict_source TEXT",
+        "ALTER TABLE assignments ADD COLUMN verdict_source_reason TEXT",
+    ]
+    for sql in migrations:
+        try:
+            conn.execute(sql)
+            conn.commit()
+        except sqlite3.OperationalError:
+            pass  # Column already exists
+
+
+# ── JSON migration ─────────────────────────────────────────────────────────────
+
+def _maybe_migrate_json(conn: sqlite3.Connection) -> None:
+    """Migrate old JSON files to SQLite if dispatched.json exists and DB is empty.
+
+    The ``json_migrated`` marker in board_meta is checked first.  Once set it
+    persists forever, so migration never re-runs even if JSON files reappear
+    (e.g. from stale code, test fixtures, or an agent writing legacy state).
+    """
+    # Marker check must come first — bail out immediately if migration already ran.
+    cursor = conn.execute(
+        "SELECT value FROM board_meta WHERE key='json_migrated'"
+    )
+    if cursor.fetchone() is not None:
+        return
+    dispatched_json = COORD_DIR / "dispatched.json"
+    if not dispatched_json.exists():
+        return
+    cursor = conn.execute("SELECT COUNT(*) FROM assignments")
+    if cursor.fetchone()[0] > 0:
+        return
+    try:
+        _migrate_json(conn)
+    except Exception as exc:  # noqa: BLE001 — migration is best-effort
+        import sys
+        print(f"coord: warning: JSON→SQLite migration failed: {exc}", file=sys.stderr)
+
+
+def _migrate_json(conn: sqlite3.Connection) -> None:  # noqa: C901 — acceptable complexity
+    """One-shot migration from JSON files to SQLite.  Renames JSON files to .bak."""
+    import time as _time
+
+    dispatched_json = COORD_DIR / "dispatched.json"
+    notified_json = COORD_DIR / "notified.json"
+    board_json = COORD_DIR / "board.json"
+    proposals_json = COORD_DIR / "pending_proposals.json"
+    splits_json = COORD_DIR / "pending_splits.json"
+    plans_json = COORD_DIR / "plans.json"
+    session_json = COORD_DIR / "session.json"
+    merge_queue_json = COORD_DIR / "merge_queue.json"
+
+    with conn:  # single transaction
+        # 1. dispatched.json → assignments (initial insert, status='running')
+        dispatched_data: list[dict] = []
+        if dispatched_json.exists():
+            try:
+                dispatched_data = json.loads(dispatched_json.read_text())
+            except Exception:  # noqa: BLE001
+                pass
+        for rec in dispatched_data:
+            conn.execute(
+                """INSERT OR IGNORE INTO assignments (
+                    assignment_id, machine_name, repo_name, repo_github,
+                    issue_number, issue_title, status, type, briefing,
+                    files_allowed, model, dispatched_at, review_of_assignment_id,
+                    required_gates
+                ) VALUES (?, ?, ?, ?, ?, ?, 'running', ?, ?, ?, ?, ?, ?, ?)""",
+                (
+                    rec.get("assignment_id", ""),
+                    rec.get("machine_name", ""),
+                    rec.get("repo_name", ""),
+                    rec.get("repo_github"),
+                    rec.get("issue_number", 0),
+                    rec.get("issue_title", ""),
+                    rec.get("type", "work"),
+                    rec.get("briefing", ""),
+                    json.dumps(rec.get("files_likely", [])),
+                    rec.get("model"),
+                    rec.get("dispatched_at"),
+                    rec.get("review_of_assignment_id"),
+                    json.dumps(rec.get("required_gates", [])),
+                ),
+            )
+
+        # 2. notified.json → notifications
+        if notified_json.exists():
+            try:
+                notified: dict[str, dict] = json.loads(notified_json.read_text())
+                for aid, info in notified.items():
+                    conn.execute(
+                        """INSERT OR REPLACE INTO notifications
+                           (assignment_id, event, branch, posted_at)
+                           VALUES (?, ?, ?, ?)""",
+                        (aid, info.get("event", ""), info.get("branch"),
+                         info.get("posted_at", _time.time())),
+                    )
+            except Exception:  # noqa: BLE001
+                pass
+
+        # 3. board.json → assignments (richer status fields via REPLACE)
+        if board_json.exists():
+            try:
+                board_data = json.loads(board_json.read_text())
+                all_entries = (
+                    board_data.get("active", []) + board_data.get("completed", [])
+                )
+                for a in all_entries:
+                    aid = a.get("assignment_id")
+                    if not aid:
+                        continue
+                    conn.execute(
+                        """INSERT OR REPLACE INTO assignments (
+                            assignment_id, machine_name, repo_name, repo_github,
+                            issue_number, issue_title, status, type, branch, pr_url,
+                            briefing, files_allowed, files_forbidden, model,
+                            dispatched_at, finished_at, smoke_test, smoke_test_reason,
+                            review_state, review_of_assignment_id, review_target,
+                            required_gates, plan, unreachable_count, exit_code
+                        ) VALUES (
+                            ?, ?, ?, ?,  ?, ?, ?, ?, ?, ?,
+                            ?, ?, ?, ?,  ?, ?, ?, ?,
+                            ?, ?, ?,     ?, ?, ?, ?
+                        )""",
+                        (
+                            aid,
+                            a.get("machine_name", ""),
+                            a.get("repo_name", ""),
+                            None,  # repo_github not in board JSON
+                            a.get("issue_number", 0),
+                            a.get("issue_title", ""),
+                            a.get("status", "running"),
+                            a.get("type", "work"),
+                            a.get("branch"),
+                            a.get("pr_url"),
+                            a.get("briefing", ""),
+                            json.dumps(a.get("files_allowed", [])),
+                            json.dumps(a.get("files_forbidden", [])),
+                            a.get("model"),
+                            a.get("dispatched_at"),
+                            a.get("finished_at"),
+                            a.get("smoke_test"),
+                            a.get("smoke_test_reason"),
+                            a.get("review_state"),
+                            a.get("review_of_assignment_id"),
+                            a.get("review_target"),
+                            json.dumps(a.get("required_gates", [])),
+                            json.dumps(a.get("plan")) if a.get("plan") else None,
+                            a.get("unreachable_count", 0),
+                            a.get("exit_code"),
+                        ),
+                    )
+                round_number = board_data.get("round_number", 0)
+                conn.execute(
+                    "INSERT OR REPLACE INTO board_meta (key, value) VALUES ('round_number', ?)",
+                    (str(round_number),),
+                )
+                conn.execute(
+                    "INSERT OR REPLACE INTO board_meta (key, value) VALUES ('board_initialized', '1')"
+                )
+            except Exception:  # noqa: BLE001
+                pass
+
+        # 4. proposals
+        if proposals_json.exists():
+            try:
+                for p in json.loads(proposals_json.read_text()):
+                    conn.execute(
+                        """INSERT OR IGNORE INTO proposals
+                           (id, machine_name, repo_name, issue_number, issue_title,
+                            rationale, files_likely, briefing, model, type, required_gates)
+                           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                        (
+                            p.get("id"), p.get("machine_name", ""), p.get("repo_name", ""),
+                            p.get("issue_number", 0), p.get("issue_title", ""),
+                            p.get("rationale", ""), json.dumps(p.get("files_likely", [])),
+                            p.get("briefing", ""), p.get("model"),
+                            p.get("type", "work"), json.dumps(p.get("required_gates", [])),
+                        ),
+                    )
+            except Exception:  # noqa: BLE001
+                pass
+
+        # 5. split proposals + chunks
+        if splits_json.exists():
+            try:
+                for s in json.loads(splits_json.read_text()):
+                    conn.execute(
+                        """INSERT OR IGNORE INTO split_proposals
+                           (id, repo_name, issue_number, issue_title, rationale)
+                           VALUES (?, ?, ?, ?, ?)""",
+                        (s.get("id"), s.get("repo_name", ""), s.get("issue_number", 0),
+                         s.get("issue_title", ""), s.get("rationale", "")),
+                    )
+                    for chunk in s.get("chunks", []):
+                        conn.execute(
+                            """INSERT INTO split_chunks
+                               (split_proposal_id, title, scope, files_likely)
+                               VALUES (?, ?, ?, ?)""",
+                            (s.get("id"), chunk.get("title", ""), chunk.get("scope", ""),
+                             json.dumps(chunk.get("files_likely", []))),
+                        )
+            except Exception:  # noqa: BLE001
+                pass
+
+        # 6. plans
+        if plans_json.exists():
+            try:
+                for aid, plan_dict in json.loads(plans_json.read_text()).items():
+                    conn.execute(
+                        "INSERT OR IGNORE INTO plans (assignment_id, plan_data) VALUES (?, ?)",
+                        (aid, json.dumps(plan_dict)),
+                    )
+            except Exception:  # noqa: BLE001
+                pass
+
+        # 7. session
+        if session_json.exists():
+            try:
+                sess = json.loads(session_json.read_text())
+                conn.execute(
+                    """INSERT INTO sessions
+                       (started_at, ended_at, clean_shutdown,
+                        completed_this_session, issues_closed, total_cost_usd)
+                       VALUES (?, ?, ?, ?, ?, ?)""",
+                    (
+                        sess.get("started_at"),
+                        sess.get("ended_at"),
+                        1 if sess.get("clean_shutdown") else 0,
+                        json.dumps(sess.get("completed_this_session", [])),
+                        json.dumps(sess.get("issues_closed", [])),
+                        sess.get("total_cost_usd"),
+                    ),
+                )
+            except Exception:  # noqa: BLE001
+                pass
+
+        # 8. merge queue
+        if merge_queue_json.exists():
+            try:
+                for entry in json.loads(merge_queue_json.read_text()):
+                    conn.execute(
+                        """INSERT INTO merge_queue (
+                            assignment_id, repo_name, repo_github, branch,
+                            target_branch, issue_number, issue_title, state,
+                            pr_number, pr_url, size, last_attempt, error
+                        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                        (
+                            entry.get("assignment_id"), entry.get("repo_name"),
+                            entry.get("repo_github"), entry.get("branch"),
+                            entry.get("target_branch"), entry.get("issue_number"),
+                            entry.get("issue_title"), entry.get("state", "pending"),
+                            entry.get("pr_number"), entry.get("pr_url"),
+                            entry.get("size"), entry.get("last_attempt"),
+                            entry.get("error"),
+                        ),
+                    )
+            except Exception:  # noqa: BLE001
+                pass
+
+        # Persist migration marker — this is the canonical "already migrated" signal.
+        # Checked at the top of _maybe_migrate_json(), so JSON files reappearing
+        # later (stale code, test fixtures, agent writing legacy state) won't
+        # re-trigger the migration.
+        conn.execute(
+            "INSERT OR REPLACE INTO board_meta (key, value) VALUES ('json_migrated', ?)",
+            (str(_time.time()),),
+        )
+
+        # Rename JSON files to .bak so migration doesn't re-run
+        for f in [
+            dispatched_json, notified_json, board_json, proposals_json,
+            splits_json, plans_json, session_json, merge_queue_json,
+        ]:
+            if f.exists():
+                try:
+                    f.rename(f.with_suffix(f.suffix + ".bak"))
+                except Exception:  # noqa: BLE001
+                    pass
+
+
+# ── Gate-order migration (Test-before-Review reorder) ─────────────────────────
+
+def _migrate_gate_order(conn: sqlite3.Connection) -> None:
+    """Rewrite the stale default gate order in stored rows.
+
+    The default gate order moved Test ahead of Review — from the #520-era
+    ``["review", "test", "merge"]`` to ``["test", "review", "merge"]`` — now
+    that the agent-assisted Testing stage is smooth enough to run as a smoke
+    test *before* the PR/review (the natural order), reversing #520's "get the
+    review over with first" workaround.  Any assignment, proposal, or
+    ``board_meta`` row still carrying the previous implicit default is updated
+    so the pipeline display and the headless review gate
+    (:meth:`PipelineConfig.test_precedes_review`) agree.  Only the exact
+    previous-default JSON string is touched — user-customised gate lists
+    (anything else) are left unchanged.
+
+    The target string (``["test", "review", "merge"]``) is also the pre-#520
+    original, so a DB that never migrated forward is already in the desired
+    state and untouched.
+
+    This function is idempotent: if the previous-default string is absent, no
+    rows change.
+    """
+    _OLD = '["review", "test", "merge"]'
+    _NEW = '["test", "review", "merge"]'
+    conn.execute(
+        "UPDATE assignments SET required_gates = ? WHERE required_gates = ?",
+        (_NEW, _OLD),
+    )
+    conn.execute(
+        "UPDATE proposals SET required_gates = ? WHERE required_gates = ?",
+        (_NEW, _OLD),
+    )
+    conn.execute(
+        "UPDATE board_meta SET value = ? "
+        "WHERE key = 'pipeline_default_gates' AND value = ?",
+        (_NEW, _OLD),
+    )
+    conn.commit()
+
+
+def _backfill_orphaned_review_verdicts(conn: sqlite3.Connection) -> int:
+    """#1663: copy a captured review verdict onto its parent WORK row.
+
+    ``run_drain`` (#1616) captured the verdict onto the ``type='review'`` row
+    and never propagated it to the parent, because the only path to that write
+    ran through ``auto_loop.process_review_completion`` — which also dispatches
+    fix workers, so the daemon's clock refused to enter it at all.  Every
+    verdict the drain consumed instead of a human's ``coord notify`` therefore
+    left its work row at ``review_state='dispatched'`` / ``review_verdict``
+    NULL.  The code fix is in ``coord.notify._run_drain_locked`` +
+    ``coord.auto_loop.propagate_review_verdict``; this repairs the rows already
+    stranded when it landed (the 2026-08-01 batch — #1527 #1624 #1658 #1633
+    #1353 — plus #544, #1078 and #1122), so none of them needs a re-review at
+    $1-3 a head.
+
+    **Copies only.**  The verdict is read from the existing review row via
+    ``review_of_assignment_id``; nothing is synthesised, re-derived from a
+    findings body, or inferred from pipeline state.  A work row whose review
+    row never captured a verdict (#1122's ``188ae219aca3``, lost to #1636/#1658
+    and recovered by hand onto PR #1656) has nothing to copy and is left
+    exactly as it is — a fabricated verdict there would overwrite hand-recovered
+    findings with a guess.
+
+    Scoped to work rows that are actually stranded: a work-like ``type``, a NULL
+    ``review_verdict`` of their own, and a review stage that demonstrably ran
+    (``review_state`` in ``dispatched``/``done``).  Rows at ``pending`` /
+    ``advisory`` / NULL are untouched — their review hasn't run or was waived.
+
+    Idempotent, and runs on every connection open like
+    :func:`_migrate_gate_order`: after the first pass every candidate has a
+    non-NULL ``review_verdict``, so the ``UPDATE`` matches nothing.  Returns the
+    number of rows repaired (0 on the steady state) for logging/tests.
+    """
+    # Latest verdict-carrying review for this work row.  `dispatched_at DESC`
+    # picks the most recent round when a work row was reviewed more than once.
+    # Deliberately NOT filtered on `r.status='done'`: #1122's review row is
+    # `failed`, and a verdict recovered onto a failed row by hand (#617's
+    # transcript recovery, `coord diagnose --stage review`) was still earned by
+    # a real review and is exactly what we want to preserve.
+    _LATEST_VERDICT = """
+        SELECT r.review_verdict FROM assignments r
+         WHERE r.review_of_assignment_id = assignments.assignment_id
+           AND r.type = 'review'
+           AND r.review_verdict IS NOT NULL
+           AND r.review_verdict != ''
+         ORDER BY r.dispatched_at DESC
+         LIMIT 1
+    """
+    cur = conn.execute(
+        f"""
+        UPDATE assignments
+           SET review_verdict = ({_LATEST_VERDICT}),
+               review_state = 'done'
+         WHERE type IN ('work', 'mock-author', 'test-author')
+           AND review_verdict IS NULL
+           AND review_state IN ('dispatched', 'done')
+           AND ({_LATEST_VERDICT}) IS NOT NULL
+        """
+    )
+    conn.commit()
+    return cur.rowcount if cur.rowcount and cur.rowcount > 0 else 0