agent-dealer 0.2.0 → 1.0.0

package/bundle/server/dist/db/migrate-to-issues.js

@@ -0,0 +1,824 @@
+#!/usr/bin/env tsx
+// packages/server/src/db/migrate-to-issues.ts
+//
+// NOT-66: the one-time, explicit cutover from the legacy single-agent `runs` model to the
+// issue-centric developer/reviewer model (design doc §"Migration and cutover"). This is
+// NOT the additive, idempotent-at-every-startup `migrate()` in ./index.ts — it is an
+// operator-invoked script that renames the legacy tables away, so it must refuse to run
+// twice and must refuse to run against a live service.
+//
+// Usage:
+//   tsx src/db/migrate-to-issues.ts <path-to-dealer.db>              # run the cutover
+//   tsx src/db/migrate-to-issues.ts <path-to-dealer.db> --rollback   # undo it
+//
+// Rollback procedure (documented here, exercised by an automated test below):
+//   The cutover's first act is an exclusive copy of the database to
+//   `<dbPath>.pre-issue-migration-backup` *before* any table is touched. To undo a
+//   completed migration, stop the service and run this script again with `--rollback`:
+//   it restores that backup file over the live database, verbatim. Rollback itself
+//   refuses to run against a live service, for the same reason the forward migration does.
+//
+// Scope note: this script only migrates data and creates the `legacy_v0_*` audit tables.
+// It does not touch any runtime route, the dispatcher, or the frontend nav — the ticket
+// explicitly scopes "remove legacy writers" as a separate, later action. The legacy
+// Operations/Inbox/Done UI and its routes keep working against the *renamed* legacy
+// tables' data having already moved into the issue model; the legacy runtime writers
+// themselves are untouched by this script and keep writing to a fresh, empty `runs` table
+// (recreated by schema.sql on next startup) until that follow-up work removes them.
+import Database from "better-sqlite3";
+import fs from "node:fs";
+import path from "node:path";
+import { v4 as uuid } from "uuid";
+import { RunStatus } from "@agent-dealer/shared";
+import { claimPidMarker, readPidMarkerOwner, releasePidMarker } from "../pid-marker.js";
+import { responseOptionsFor } from "../coordinator/commands.js";
+function emptyReport() {
+    return {
+        issuesCreated: 0,
+        legacySessionsCreated: 0,
+        artifactsRepointed: 0,
+        eventsRepointed: 0,
+        mismatches: [],
+        alreadyMigrated: false,
+    };
+}
+/** Groups every run by COALESCE(lineage_id, id) — one bucket per historical lineage. */
+function groupByLineage(runs) {
+    const groups = new Map();
+    for (const run of runs) {
+        const key = run.lineage_id ?? run.id;
+        const bucket = groups.get(key) ?? [];
+        bucket.push(run);
+        groups.set(key, bucket);
+    }
+    return groups;
+}
+function latestRun(runs) {
+    return [...runs].sort((a, b) => a.created_at.localeCompare(b.created_at))[runs.length - 1];
+}
+/** Legacy worker_session.status follows the same bucket as the issue-status mapping below. */
+function legacySessionStatus(runStatus) {
+    if (runStatus === "done" || runStatus === "review")
+        return "done";
+    if (runStatus === "failed")
+        return "failed";
+    return "cancelled"; // cancelled, queued, plan_pending, plan_approved, running
+}
+function issueStatusForLatest(runStatus) {
+    switch (runStatus) {
+        case "done":
+            return { status: "done", owner: "system" };
+        case "cancelled":
+            return { status: "closed", owner: "system" };
+        case "review":
+            return {
+                status: "final_review",
+                owner: "human",
+                humanAction: {
+                    actionType: "final_review",
+                    reason: "Migrated from a legacy run awaiting result review",
+                    question: "Accept this legacy work?",
+                },
+            };
+        case "failed":
+            return {
+                status: "needs_human",
+                owner: "human",
+                humanAction: {
+                    actionType: "attempts_exhausted",
+                    reason: "Migrated from a legacy failed run",
+                    question: "This legacy run failed — how should it be resolved?",
+                },
+            };
+        default:
+            // queued, plan_pending, plan_approved, running
+            return { status: "ready", owner: "system" };
+    }
+}
+/**
+ * The live app runs in WAL mode (getDb() in ./index.ts), which can leave recently
+ * committed data sitting only in the `<dbPath>-wal` sidecar file, not yet folded into the
+ * main database file. A plain `fs.copyFileSync(dbPath, ...)` of the main file alone would
+ * then silently miss that data (or, worse, produce a backup that is missing tables
+ * entirely if the schema itself was created since the last checkpoint). Checkpointing
+ * with TRUNCATE folds everything into the main file and empties the WAL, so a bare file
+ * copy of `dbPath` alone is always a complete, self-contained snapshot.
+ */
+function checkpointAndTruncate(dbPath) {
+    const db = new Database(dbPath);
+    try {
+        // No point waiting on SQLite's default busy retry loop — a conflicting reader isn't
+        // expected to release its snapshot imminently, and this function's job is to fail
+        // fast and clearly rather than block the whole migration on an indeterminate wait.
+        db.pragma("busy_timeout = 0");
+        // wal_checkpoint(TRUNCATE) reports failure via its result row, not by throwing: `busy`
+        // is nonzero when some other connection's open read transaction pinned WAL frames the
+        // checkpoint could not fold into the main file. Copying the main file in that state
+        // produces a backup silently missing whatever those unfoldable frames contained —
+        // exactly the rollback guarantee this function exists to protect. Refuse rather than
+        // guess; the caller can retry once nothing else holds the database open.
+        const [result] = db.pragma("wal_checkpoint(TRUNCATE)");
+        if (result.busy !== 0) {
+            throw new Error(`refusing to back up: WAL checkpoint could not complete (busy=${result.busy}, ` +
+                `log=${result.log} frames, checkpointed=${result.checkpointed}) — another connection ` +
+                `is holding a conflicting read lock on ${dbPath}. A backup taken now could silently ` +
+                `miss recent commits. Retry once nothing else is reading the database.`);
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+/** Removes a possibly-stale WAL/SHM sidecar so a later connection never replays frames
+ * left over from before a file at this path was overwritten (e.g. by rollback). */
+function removeWalSidecars(dbPath) {
+    for (const suffix of ["-wal", "-shm"]) {
+        try {
+            fs.unlinkSync(`${dbPath}${suffix}`);
+        }
+        catch {
+            /* fine if absent */
+        }
+    }
+}
+function tableExists(db, name) {
+    return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name);
+}
+function columnsOf(db, table) {
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    return new Set(rows.map((r) => r.name));
+}
+const REQUIRED_LEGACY_COLUMNS = {
+    runs: [
+        "id",
+        "source",
+        "external_id",
+        "external_label",
+        "title",
+        "description",
+        "repo",
+        "agent_id",
+        "status",
+        "lineage_id",
+        "acceptance_criteria",
+        "runtime",
+        "plan_model",
+        "execute_model",
+        "budget_json",
+        "created_at",
+        "updated_at",
+    ],
+    artifacts: ["id", "run_id", "kind", "content_json", "blob_path", "author", "created_at", "issue_id", "worker_session_id"],
+    events: ["id", "run_id", "type", "payload_json", "ts"],
+};
+const REQUIRED_TARGET_TABLES = [
+    "issues",
+    "worker_sessions",
+    "workflow_instances",
+    "workflow_events",
+    "human_actions",
+    "agents",
+];
+/**
+ * Refuses to guess: validates the legacy `runs`/`artifacts`/`events` shape this script
+ * depends on, and that the issue-centric target tables already exist (created by the
+ * ordinary additive `migrate()` in ./index.ts, which every server startup already runs).
+ * Returns a description of the first problem found, or null when the schema is safe to
+ * migrate. Called *before* the backup is created — a bad schema should never even cost a
+ * backup copy.
+ */
+function validateLegacySchema(db) {
+    for (const table of ["runs", "artifacts", "events", "approval_gates"]) {
+        if (!tableExists(db, table)) {
+            return `expected legacy table "${table}" not found — this database may already be migrated or is not an agent-dealer database`;
+        }
+    }
+    for (const table of REQUIRED_TARGET_TABLES) {
+        if (!tableExists(db, table)) {
+            return `expected issue-centric table "${table}" not found — run the ordinary server migration (npm run db:migrate) first`;
+        }
+    }
+    for (const [table, cols] of Object.entries(REQUIRED_LEGACY_COLUMNS)) {
+        const present = columnsOf(db, table);
+        const missing = cols.filter((c) => !present.has(c));
+        if (missing.length > 0) {
+            return `table "${table}" is missing expected column(s): ${missing.join(", ")}`;
+        }
+    }
+    // issueStatusForLatest()/legacySessionStatus() have a `default:` branch that folds any
+    // unrecognized status into "ready"/"cancelled" — appropriate for the *known* pre-terminal
+    // statuses that fall into it (queued/plan_pending/plan_approved/running), but silently
+    // wrong for a genuinely unexpected value (a future/older/corrupt status this script has
+    // never seen), which would otherwise be converted into ordinary runnable work instead of
+    // being flagged. Validate every distinct value up front against the full closed set.
+    const distinctStatuses = db.prepare("SELECT DISTINCT status FROM runs").all().map((r) => r.status);
+    const unknown = distinctStatuses.filter((s) => !RunStatus.safeParse(s).success);
+    if (unknown.length > 0) {
+        const offendingIds = db
+            .prepare(`SELECT id FROM runs WHERE status IN (${unknown.map(() => "?").join(",")})`)
+            .all(...unknown).map((r) => r.id);
+        return `runs table contains unrecognized status value(s) ${unknown.map((s) => `"${s}"`).join(", ")} (run ids: ${offendingIds.join(", ")}) — refusing to guess how to migrate them`;
+    }
+    return null;
+}
+/**
+ * Resolves symlinks so every derived path (server.pid, run.json, the backup, WAL
+ * sidecars) is anchored to the database's *real* directory, not wherever a symlink to it
+ * happens to live. Without this, `tsx src/db/migrate-to-issues.ts /some/alias/dealer.db`
+ * (a symlink to the real, live dealer.db elsewhere) would derive server.pid next to the
+ * alias — a path the running server never wrote to — so both the live-service check and
+ * the exclusive claim would incorrectly see nothing there and proceed to mutate the very
+ * database the live server is using. Falls back to a plain absolute-path resolution when
+ * the target doesn't exist (rollbackMigration may be pointed at a path that hasn't been
+ * created yet in some caller), matching the old, unresolved-path behavior for that case
+ * rather than throwing.
+ */
+function canonicalDbPath(dbPath) {
+    try {
+        return fs.realpathSync(dbPath);
+    }
+    catch {
+        return path.resolve(dbPath);
+    }
+}
+function serverPidPathFor(dbPath) {
+    return path.join(path.dirname(dbPath), "server.pid");
+}
+function runStatePathFor(dbPath) {
+    return path.join(path.dirname(dbPath), "run.json");
+}
+/** run.json uses `serverPid`, not `pid` — packages/cli/src/runtime-state.ts's RunState
+ * shape, kept as its own reader since it is a different file this script never claims. */
+function readRunStateOwner(dbPath) {
+    const owner = readPidMarkerOwner(runStatePathFor(dbPath));
+    if (owner)
+        return owner;
+    // readPidMarkerOwner() only understands the `pid` field; re-check run.json's own
+    // `serverPid` field directly rather than duplicating the alive-probe logic here.
+    const filePath = runStatePathFor(dbPath);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        const pid = raw.serverPid;
+        if (typeof pid !== "number" || !Number.isFinite(pid) || pid <= 0)
+            return null;
+        try {
+            process.kill(pid, 0);
+            return { pid, alive: true };
+        }
+        catch {
+            return { pid, alive: false };
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Real liveness check, not a placeholder: the running service is tracked via
+ * `server.pid` (packages/server/src/server-liveness.ts — written directly by the server's
+ * own entrypoint on every launch mode: `npm run dev`, `npm run start`, and the CLI daemon,
+ * which spawns that exact same entrypoint as a child) and, as a fallback,
+ * `run.json` (packages/cli/src/runtime-state.ts's RunState, written only by the CLI
+ * daemon supervisor). Checking server.pid first is what makes this guard hold for a
+ * directly-launched dev/start server, which never writes run.json at all.
+ *
+ * This is a read-only inspection, useful on its own (e.g. reporting), but runMigration()
+ * below does not rely on it alone for its own safety: between this check returning "not
+ * running" and the migration actually acting, a server could start. runMigration()
+ * instead atomically *claims* server.pid via pid-marker.ts for the duration of the
+ * migration, which is what actually closes that race (a server whose own claim then fails
+ * is required — see index.ts — to refuse to start, rather than run unmonitored).
+ */
+export function isServiceRunning(rawDbPath) {
+    const dbPath = canonicalDbPath(rawDbPath);
+    const serverOwner = readPidMarkerOwner(serverPidPathFor(dbPath));
+    if (serverOwner?.alive) {
+        return { running: true, detail: `pid ${serverOwner.pid} (from ${serverPidPathFor(dbPath)})` };
+    }
+    const cliOwner = readRunStateOwner(dbPath);
+    if (cliOwner?.alive) {
+        return { running: true, detail: `serverPid ${cliOwner.pid} (from ${runStatePathFor(dbPath)})` };
+    }
+    return { running: false };
+}
+export function runMigration(rawDbPath, opts) {
+    // Canonicalize once, up front — every path derived below (server.pid, run.json, the
+    // backup, WAL sidecars) must be anchored to the database's real location. See
+    // canonicalDbPath's doc comment.
+    const dbPath = canonicalDbPath(rawDbPath);
+    // Phase 0: read-only probe — idempotent no-op check + schema validation, before anything
+    // else touches the filesystem or the database.
+    const probe = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+        if (tableExists(probe, "legacy_v0_runs")) {
+            return { ...emptyReport(), alreadyMigrated: true };
+        }
+        const schemaError = validateLegacySchema(probe);
+        if (schemaError) {
+            return { ...emptyReport(), mismatches: [schemaError] };
+        }
+    }
+    finally {
+        probe.close();
+    }
+    // run.json (the CLI daemon's own marker) is a read-only signal this script never
+    // claims — a live entry there blocks unconditionally, the same as before.
+    if (!opts?.skipServiceCheck) {
+        const cliOwner = readRunStateOwner(dbPath);
+        if (cliOwner?.alive) {
+            return {
+                ...emptyReport(),
+                mismatches: [
+                    `refusing to migrate while the service is running (serverPid ${cliOwner.pid} from ${runStatePathFor(dbPath)}) — stop it first`,
+                ],
+            };
+        }
+    }
+    // Atomically claim server.pid for the duration of this migration (see pid-marker.ts).
+    // This is what actually closes the TOCTOU window a plain read-then-act check could
+    // not: a server trying to start concurrently sees this migration's own live pid as the
+    // current owner and — index.ts treats a failed claim as fatal — refuses to start, while
+    // this claim itself fails if a server won the race first.
+    const serverPidPath = serverPidPathFor(dbPath);
+    let claimedLock = false;
+    if (!opts?.skipServiceCheck) {
+        claimedLock = claimPidMarker(serverPidPath, { role: "migration" });
+        if (!claimedLock) {
+            const owner = readPidMarkerOwner(serverPidPath);
+            return {
+                ...emptyReport(),
+                mismatches: [
+                    `refusing to migrate while the service is running (pid ${owner?.pid} from ${serverPidPath}) — stop it first`,
+                ],
+            };
+        }
+    }
+    try {
+        return runMigrationBody(dbPath, opts);
+    }
+    finally {
+        if (claimedLock)
+            releasePidMarker(serverPidPath);
+    }
+}
+function runMigrationBody(dbPath, opts) {
+    if (opts?.injectFailureAt === "before-backup") {
+        throw new Error("injected failure: before-backup");
+    }
+    // Fold any WAL-resident commits into the main file before copying it — see
+    // checkpointAndTruncate's doc comment.
+    checkpointAndTruncate(dbPath);
+    // Exclusive, unique backup: COPYFILE_EXCL fails (EEXIST) rather than silently overwriting
+    // a backup from a prior attempt — a second invocation is a safe refusal, never a second
+    // (possibly different) backup replacing the first.
+    const backupPath = `${dbPath}.pre-issue-migration-backup`;
+    try {
+        fs.copyFileSync(dbPath, backupPath, fs.constants.COPYFILE_EXCL);
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            return {
+                ...emptyReport(),
+                mismatches: [
+                    `backup already exists at ${backupPath} — refusing to run again. If this is a stale backup ` +
+                        `from a previous failed attempt, inspect and remove it manually before retrying.`,
+                ],
+            };
+        }
+        throw err;
+    }
+    if (opts?.injectFailureAt === "after-backup") {
+        throw new Error("injected failure: after-backup");
+    }
+    const db = new Database(dbPath);
+    const report = emptyReport();
+    const tx = db.transaction(() => {
+        const runs = db.prepare("SELECT * FROM runs").all();
+        const runIds = new Set(runs.map((r) => r.id));
+        // Refuse malformed input rather than guessing: a lineage_id that points nowhere.
+        for (const run of runs) {
+            if (run.lineage_id && !runIds.has(run.lineage_id) && run.lineage_id !== run.id) {
+                report.mismatches.push(`run ${run.id} has lineage_id ${run.lineage_id} which does not exist`);
+            }
+        }
+        if (report.mismatches.length > 0)
+            return;
+        const agentExists = (id) => !!id && !!db.prepare("SELECT 1 FROM agents WHERE id = ?").get(id);
+        const issuesBefore = db.prepare("SELECT COUNT(*) AS c FROM issues").get().c;
+        const groups = groupByLineage(runs);
+        for (const [, lineageRuns] of groups) {
+            const issueId = uuid();
+            const latest = latestRun(lineageRuns);
+            const mapped = issueStatusForLatest(latest.status);
+            const resolvedAgentId = agentExists(latest.agent_id) ? latest.agent_id : null;
+            db.prepare(`
+        INSERT INTO issues (
+          id, source, external_id, external_label, external_url, title, description,
+          acceptance_criteria, repo, base_branch, status, current_owner, current_intent,
+          developer_agent_id, reviewer_agent_id, max_review_rounds, current_round,
+          max_infra_attempts, infra_attempts,
+          branch, base_sha, head_sha, pr_number, pr_url, created_at, updated_at
+        ) VALUES (
+          @id, @source, @external_id, @external_label, NULL, @title, @description,
+          @acceptance_criteria, @repo, 'main', @status, @current_owner, NULL,
+          @agent_id, @agent_id, 3, 1,
+          3, 0,
+          NULL, NULL, NULL, NULL, NULL, @created_at, @updated_at
+        )
+      `).run({
+                id: issueId,
+                source: latest.source,
+                external_id: latest.external_id,
+                external_label: latest.external_label,
+                title: latest.title,
+                description: latest.description,
+                acceptance_criteria: latest.acceptance_criteria,
+                repo: latest.repo ?? "unknown",
+                status: mapped.status,
+                current_owner: mapped.owner,
+                agent_id: resolvedAgentId,
+                created_at: latest.created_at,
+                updated_at: latest.updated_at,
+            });
+            report.issuesCreated += 1;
+            // One completed legacy_v0 workflow instance per lineage (audit only, never active).
+            // Inserted directly rather than through startWorkflowInstance(), which always creates
+            // an *active* (completed_at=null) instance — this one is born already complete.
+            const instanceId = uuid();
+            db.prepare(`
+        INSERT INTO workflow_instances (id, issue_id, workflow_version, started_at, completed_at, outcome)
+        VALUES (?, ?, 'legacy_v0', ?, ?, 'migrated')
+      `).run(instanceId, issueId, latest.created_at, latest.updated_at);
+            if (mapped.humanAction) {
+                // response_options_json populated from the exact same table the live coordinator
+                // uses (commands.ts's responseOptionsFor) — left NULL, the production UI parses it
+                // as no options and renders nothing to resolve the action with.
+                const responseOptionsJson = JSON.stringify(responseOptionsFor(mapped.humanAction.actionType));
+                db.prepare(`
+          INSERT INTO human_actions (
+            id, issue_id, workflow_instance_id, action_type, reason, question, evidence_json,
+            response_options_json, continuation_preview_json, status, resolution_json, resolved_by,
+            requested_at, resolved_at
+          ) VALUES (?, ?, ?, ?, ?, ?, NULL, ?, NULL, 'open', NULL, NULL, ?, NULL)
+        `).run(uuid(), issueId, instanceId, mapped.humanAction.actionType, mapped.humanAction.reason, mapped.humanAction.question, responseOptionsJson, latest.updated_at);
+            }
+            for (const run of lineageRuns) {
+                const sessionId = uuid();
+                const sessionStatus = legacySessionStatus(run.status);
+                const sessionAgentId = agentExists(run.agent_id) ? run.agent_id : null;
+                // Design §"worker_sessions": runtime/model/budget "moved from runs" — preserve them
+                // on the migrated session rather than dropping them, since legacy_v0_runs (where
+                // they'd otherwise still live) is only retained for one release. execute_model
+                // wins over plan_model when both are set, matching the same execute-first
+                // precedence migrate() already uses when backfilling agents.default_model.
+                const model = run.execute_model ?? run.plan_model;
+                db.prepare(`
+          INSERT INTO worker_sessions (
+            id, issue_id, role, round, agent_id, runtime, model, budget_json, worktree_path,
+            input_sha, status, session_ref, log_path, exit_code, error_json, metadata_json,
+            profile_snapshot_json, created_at, started_at, heartbeat_at, completed_at, updated_at
+          ) VALUES (
+            ?, ?, 'legacy', 1, ?, ?, ?, ?, NULL,
+            NULL, ?, NULL, NULL, NULL, NULL, ?,
+            NULL, ?, NULL, NULL, ?, ?
+          )
+        `).run(sessionId, issueId, sessionAgentId, run.runtime, model, run.budget_json, sessionStatus, JSON.stringify({
+                    legacyRunId: run.id,
+                    legacyStatus: run.status,
+                    legacyLineageId: run.lineage_id,
+                    legacyPlanModel: run.plan_model,
+                    legacyExecuteModel: run.execute_model,
+                }), run.created_at, run.updated_at, run.updated_at);
+                report.legacySessionsCreated += 1;
+                // Repoint in place — artifacts is the SAME table the live coordinator writes to
+                // (issue_id/worker_session_id were added to it additively, see ./index.ts), never a
+                // renamed legacy table. Updating in place, rather than copying into a staging table
+                // and swapping the whole table, is what keeps any artifact rows a real (non-legacy)
+                // issue already wrote — this migration is not the first runtime activity against
+                // this database — completely untouched.
+                const repointed = db
+                    .prepare("UPDATE artifacts SET issue_id = ?, worker_session_id = ? WHERE run_id = ?")
+                    .run(issueId, sessionId, run.id);
+                report.artifactsRepointed += repointed.changes;
+                const events = db.prepare("SELECT * FROM events WHERE run_id = ?").all(run.id);
+                for (const e of events) {
+                    let legacyPayload = null;
+                    if (e.payload_json) {
+                        try {
+                            legacyPayload = JSON.parse(e.payload_json);
+                        }
+                        catch {
+                            legacyPayload = e.payload_json;
+                        }
+                    }
+                    db.prepare(`
+            INSERT INTO workflow_events (
+              id, issue_id, workflow_instance_id, worker_session_id, type, actor_type, actor_ref,
+              stage, round, payload_json, artifact_ref, idempotency_key, causation_event_id, ts
+            ) VALUES (?, ?, ?, ?, 'legacy.imported', 'system', NULL, ?, 1, ?, NULL, NULL, NULL, ?)
+          `).run(uuid(), issueId, instanceId, sessionId, mapped.status, JSON.stringify({ legacyType: e.type, legacyPayload }), e.ts);
+                    report.eventsRepointed += 1;
+                }
+            }
+        }
+        if (opts?.injectFailureAt === "after-insert") {
+            throw new Error("injected failure: after-insert");
+        }
+        // Verification gate — any mismatch aborts the whole transaction (rollback).
+        const issuesAfter = db.prepare("SELECT COUNT(*) AS c FROM issues").get().c;
+        if (issuesAfter - issuesBefore !== groups.size) {
+            report.mismatches.push(`expected ${groups.size} new issues, found ${issuesAfter - issuesBefore} (database may already contain unrelated issues — compared as a delta)`);
+        }
+        const sessionCount = db.prepare("SELECT COUNT(*) AS c FROM worker_sessions WHERE role = 'legacy'").get().c;
+        if (sessionCount !== runs.length) {
+            report.mismatches.push(`expected ${runs.length} legacy sessions, found ${sessionCount}`);
+        }
+        // Scoped to the tables this migration writes to: a legacy `runs`/`events`/
+        // `approval_gates` row can already carry a dangling reference from before this script
+        // ever ran (e.g. an agent deleted outside deleteAgent()'s normal path) — that
+        // pre-existing legacy data quality issue is not this migration's to fix, and is kept
+        // as-is under legacy_v0_*. Only a violation in a table *this migration wrote to* means
+        // the migration itself produced a bad reference.
+        const NEW_TABLES = new Set(["issues", "worker_sessions", "workflow_instances", "workflow_events", "human_actions"]);
+        const fkViolations = db.prepare("PRAGMA foreign_key_check").all().filter((v) => NEW_TABLES.has(v.table));
+        if (fkViolations.length > 0) {
+            report.mismatches.push(`foreign key check failed: ${JSON.stringify(fkViolations)}`);
+        }
+        if (opts?.injectFailureAt === "after-verify") {
+            throw new Error("injected failure: after-verify");
+        }
+        if (report.mismatches.length > 0) {
+            throw new Error("migration verification failed — rolling back");
+        }
+        // Rename the legacy-only tables so the running app's fresh, empty versions (recreated
+        // by schema.sql on next startup) are the only ones the *new* coordinator ever writes —
+        // "artifacts" is deliberately excluded; see the repoint comment above.
+        for (const table of ["runs", "events", "approval_gates"]) {
+            db.exec(`ALTER TABLE ${table} RENAME TO legacy_v0_${table}`);
+        }
+        if (opts?.injectFailureAt === "after-rename") {
+            throw new Error("injected failure: after-rename");
+        }
+        // The rename above makes SQLite rewrite artifacts.run_id's FK target to
+        // "legacy_v0_runs" (a foreign key follows a RENAME of the table it references).
+        // schema.sql recreates a *fresh*, empty "runs" table on the very next startup — but
+        // the legacy `/api/runs` writers keep running per this ticket's scope, and the first
+        // fresh run's addArtifact() would then fail with "FOREIGN KEY constraint failed"
+        // because the live artifacts table's declared FK target no longer matches the table
+        // schema.sql just (re)created. Rebuild `artifacts` with run_id as a plain, unconstrained
+        // column instead — re-declaring `REFERENCES runs(id)` here does not work: SQLite
+        // requires the referenced table to exist by the time a row is *inserted* into the
+        // child (not merely at CREATE TABLE time), and this same transaction has to copy rows
+        // into the rebuilt table before schema.sql ever gets a chance to recreate "runs".
+        // Given "runs" itself now cycles between the renamed legacy table and a freshly
+        // recreated empty one across every cutover, a declared FK into it is unenforceable by
+        // construction; dropping the constraint (the column and its data are untouched) is the
+        // correct fix, not a workaround. Same rebuild-in-place technique migrate() already uses
+        // in ./index.ts for the analogous "SQLite can't ALTER a column's FK target" limitation.
+        db.exec(`
+      CREATE TABLE artifacts_new (
+        id TEXT PRIMARY KEY,
+        run_id TEXT,
+        kind TEXT NOT NULL,
+        content_json TEXT,
+        blob_path TEXT,
+        author TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        issue_id TEXT REFERENCES issues(id),
+        worker_session_id TEXT REFERENCES worker_sessions(id)
+      );
+      INSERT INTO artifacts_new (id, run_id, kind, content_json, blob_path, author, created_at, issue_id, worker_session_id)
+        SELECT id, run_id, kind, content_json, blob_path, author, created_at, issue_id, worker_session_id FROM artifacts;
+      DROP TABLE artifacts;
+      ALTER TABLE artifacts_new RENAME TO artifacts;
+      CREATE INDEX IF NOT EXISTS idx_artifacts_run ON artifacts(run_id);
+    `);
+        // The same rename-follows-reference behavior applies to each legacy table's own
+        // secondary indexes: SQLite keeps an index's original name attached through a table
+        // rename, so schema.sql's `CREATE INDEX IF NOT EXISTS idx_runs_status ...` (index
+        // names are unique database-wide, not per-table) finds that name already taken and
+        // silently skips creating it against the fresh "runs" table — leaving the live legacy
+        // write path with only its primary-key autoindex. Free the original names by giving
+        // the legacy copies new ones.
+        const LEGACY_INDEXES = [
+            { name: "idx_runs_status", table: "runs", columns: "status" },
+            { name: "idx_runs_external", table: "runs", columns: "source, external_id" },
+            { name: "idx_events_run", table: "events", columns: "run_id" },
+            { name: "idx_gates_run", table: "approval_gates", columns: "run_id" },
+        ];
+        for (const idx of LEGACY_INDEXES) {
+            db.exec(`DROP INDEX IF EXISTS ${idx.name}`);
+            db.exec(`CREATE INDEX legacy_v0_${idx.name} ON legacy_v0_${idx.table}(${idx.columns})`);
+        }
+        // Post-rename assertion: query "artifacts" exactly the way the live API does (by
+        // issue_id) and confirm every repointed artifact is actually reachable there.
+        const reachableForRun = db
+            .prepare(`SELECT COUNT(*) AS c FROM artifacts WHERE issue_id IS NOT NULL AND run_id IN (SELECT id FROM legacy_v0_runs)`)
+            .get();
+        if (reachableForRun.c !== report.artifactsRepointed) {
+            report.mismatches.push(`expected ${report.artifactsRepointed} migrated artifacts reachable via the post-cutover "artifacts" table, found ${reachableForRun.c}`);
+            throw new Error("migration verification failed — rolling back");
+        }
+    });
+    try {
+        tx();
+    }
+    catch (err) {
+        // better-sqlite3 already rolled back the transaction; report.mismatches carries the
+        // reason when it's one this script raised. An injected/unexpected error still needs a
+        // message so the caller can see *why* — mismatches is the one channel both use.
+        if (report.mismatches.length === 0) {
+            report.mismatches.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    finally {
+        // Whether committed or rolled back, leave the file self-contained on disk — the same
+        // reason the backup is checkpointed before copy (see checkpointAndTruncate).
+        db.pragma("wal_checkpoint(TRUNCATE)");
+        db.close();
+    }
+    return report;
+}
+/**
+ * Restores the pre-migration backup over the live database, undoing a completed cutover.
+ * Refuses while the service is running, for the same reason the forward migration does.
+ * Refuses when no backup exists rather than silently doing nothing that looks like success.
+ */
+/** Opens `path` read-only and runs an integrity check plus a minimal legacy-schema sanity
+ * check (it must look like a pre-migration snapshot, i.e. still have "runs" — a backup is
+ * only ever taken *before* the rename). Returns null when the file is a usable rollback
+ * source, or a description of the first problem found. */
+function validateRollbackSource(path_) {
+    // A malformed file (not a SQLite database at all, or truncated/corrupt) does not
+    // necessarily fail at open time — better-sqlite3/SQLite reads the header lazily, so the
+    // actual SQLITE_NOTADB/SQLITE_CORRUPT throw can happen on the first real statement
+    // (integrity_check below) just as easily as on the constructor. Both must be caught the
+    // same way: this is a "not a usable rollback source" verdict either way, not a crash.
+    let db = null;
+    try {
+        db = new Database(path_, { readonly: true, fileMustExist: true });
+        const rows = db.pragma("integrity_check");
+        const problems = rows.filter((r) => r.integrity_check !== "ok").map((r) => r.integrity_check);
+        if (problems.length > 0) {
+            return `${path_} failed SQLite's integrity check: ${problems.join("; ")}`;
+        }
+        // Reuse the exact same validation that gates creating a backup in the first place — a
+        // genuine pre-cutover snapshot must satisfy every bit of it too (all legacy tables and
+        // columns, all issue-centric target tables, no unrecognized run status), not a
+        // narrower ad hoc subset that a post-restart or unrelated database could pass by
+        // accident (e.g. one with only "runs"/"artifacts"/"events" but no "approval_gates" or
+        // target tables — a near-miss the previous, narrower check here did not catch).
+        const schemaProblem = validateLegacySchema(db);
+        if (schemaProblem) {
+            return `${path_} does not look like a pre-migration backup — ${schemaProblem}`;
+        }
+        // validateLegacySchema() doesn't check this — it runs on a live, not-yet-migrated
+        // database in the forward direction, where legacy_v0_* tables couldn't exist yet
+        // anyway. A rollback source additionally must not carry them: a post-restart database
+        // (schema.sql recreates a fresh "runs" after a real cutover) would otherwise pass the
+        // shape check above and be silently accepted as if it were the original pre-cutover
+        // snapshot.
+        const cutoverTables = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'legacy_v0_%'").all().map((r) => r.name);
+        if (cutoverTables.length > 0) {
+            return `${path_} does not look like a pre-migration backup — carries cutover-only table(s) ${cutoverTables.join(", ")}, meaning this looks like a post-migration database, not a pre-cutover snapshot`;
+        }
+        return null;
+    }
+    catch (err) {
+        return `cannot open ${path_} as a SQLite database: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * Restores the pre-migration backup over the live database, undoing a completed cutover.
+ * Refuses while the service is running, for the same reason the forward migration does.
+ * Refuses when no backup exists rather than silently doing nothing that looks like success.
+ *
+ * Never trusts the backup file blindly: a truncated, corrupted, or unrelated file at that
+ * path (a bad disk during the original backup, or manual tampering) is validated — opened
+ * read-only, integrity-checked, and schema-sanity-checked — *before* it ever touches the
+ * live database. The restore itself copies to a temporary file in the same directory,
+ * validates that copy too (protects against a corrupted copy, e.g. a disk failing
+ * mid-write), and only then atomically renames it over the live path — an interrupted
+ * copy leaves the original live database untouched rather than a half-written file in
+ * its place.
+ */
+export function rollbackMigration(rawDbPath, opts) {
+    const dbPath = canonicalDbPath(rawDbPath);
+    const backupPath = `${dbPath}.pre-issue-migration-backup`;
+    if (!fs.existsSync(backupPath)) {
+        return { rolledBack: false, detail: `no backup found at ${backupPath} — nothing to roll back to` };
+    }
+    // run.json (CLI daemon) is a read-only signal this script never claims — same as
+    // runMigration(), a live entry there blocks unconditionally.
+    if (!opts?.skipServiceCheck) {
+        const cliOwner = readRunStateOwner(dbPath);
+        if (cliOwner?.alive) {
+            return {
+                rolledBack: false,
+                detail: `refusing rollback while the service is running (serverPid ${cliOwner.pid} from ${runStatePathFor(dbPath)}) — stop it first`,
+            };
+        }
+    }
+    // Atomically claim server.pid for the duration of the restore, exactly as
+    // runMigration() does — a plain read-then-act liveness check leaves the same TOCTOU
+    // window a forward migration would: a server could start between the check and the
+    // rename below and have the file replaced out from under it mid-run.
+    const serverPidPath = serverPidPathFor(dbPath);
+    let claimedLock = false;
+    if (!opts?.skipServiceCheck) {
+        claimedLock = claimPidMarker(serverPidPath, { role: "rollback" });
+        if (!claimedLock) {
+            const owner = readPidMarkerOwner(serverPidPath);
+            return {
+                rolledBack: false,
+                detail: `refusing rollback while the service is running (pid ${owner?.pid} from ${serverPidPath}) — stop it first`,
+            };
+        }
+    }
+    try {
+        const sourceProblem = validateRollbackSource(backupPath);
+        // Opening the backup read-only for validation can itself create -wal/-shm sidecars
+        // next to it; tidy those up regardless of outcome — the backup file itself is untouched.
+        removeWalSidecars(backupPath);
+        if (sourceProblem) {
+            return { rolledBack: false, detail: `refusing rollback — ${sourceProblem}` };
+        }
+        const stagedPath = `${dbPath}.rollback-staging-${process.pid}-${Date.now()}`;
+        try {
+            fs.copyFileSync(backupPath, stagedPath);
+            const stagedProblem = validateRollbackSource(stagedPath);
+            if (stagedProblem) {
+                return { rolledBack: false, detail: `refusing rollback — staged copy is unusable: ${stagedProblem}` };
+            }
+            // Same-directory rename is atomic on the same filesystem — dbPath is either the
+            // fully restored file or (on any failure above) untouched; never a partial write.
+            fs.renameSync(stagedPath, dbPath);
+        }
+        finally {
+            // validateRollbackSource() opens stagedPath (even read-only), which can create its
+            // own -wal/-shm sidecars — clean those up alongside the main staged file too.
+            try {
+                fs.unlinkSync(stagedPath);
+            }
+            catch {
+                // already renamed away on success, or never created on an early failure — fine
+            }
+            removeWalSidecars(stagedPath);
+        }
+        // The restored main file is a complete snapshot (the backup was made from a
+        // checkpointed, WAL-truncated database) — any WAL/SHM sidecar still sitting next to
+        // dbPath from the post-migration state describes pages that no longer match this
+        // now-older main file, so it must not be replayed against it.
+        removeWalSidecars(dbPath);
+        return { rolledBack: true, detail: `restored ${dbPath} from ${backupPath}` };
+    }
+    finally {
+        if (claimedLock)
+            releasePidMarker(serverPidPath);
+    }
+}
+function printUsage() {
+    console.error("Usage:");
+    console.error("  tsx src/db/migrate-to-issues.ts <path-to-dealer.db>              # run the cutover");
+    console.error("  tsx src/db/migrate-to-issues.ts <path-to-dealer.db> --rollback   # undo it");
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const dbPath = args.find((a) => !a.startsWith("--"));
+    const rollback = args.includes("--rollback");
+    if (!dbPath) {
+        printUsage();
+        process.exit(1);
+    }
+    if (!fs.existsSync(dbPath)) {
+        console.error(`Database not found: ${dbPath}`);
+        process.exit(1);
+    }
+    if (rollback) {
+        const result = rollbackMigration(dbPath);
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result.rolledBack ? 0 : 1);
+    }
+    const report = runMigration(dbPath);
+    console.log(JSON.stringify(report, null, 2));
+    if (report.alreadyMigrated) {
+        console.log("Already migrated — no-op.");
+        return;
+    }
+    if (report.mismatches.length > 0) {
+        console.error("Migration refused or rolled back — see mismatches above. Original data untouched.");
+        process.exit(1);
+    }
+    console.log(`Migration complete. Roll back with: tsx src/db/migrate-to-issues.ts ${dbPath} --rollback`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}