@worca/app 1.0.0 → 1.2.0-rc.1

package/src/core/db.mjs

@@ -17,10 +17,11 @@
 // would make getDb() async and break the synchronous data layer.
 
 import { createRequire } from 'node:module';
-import { mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { worcaHome } from './projects.mjs';
 import { maybeMigrateFromFs } from './migrate-fs-to-db.mjs';
+import { SEED_TEMPLATES, NODE_ID_MAP, FB_WIRE_MAP } from './graph/seed-templates.mjs';
 
 const _require = createRequire(import.meta.url);
 let _DatabaseSync; // cached node:sqlite DatabaseSync ctor (lazy-loaded once)
@@ -50,8 +51,10 @@ const BUSY_TIMEOUT_MS = 5000;
 const OPEN_RETRY_LIMIT = 100;
 const OPEN_BACKOFF_MS = 15;
 
-/** Latest schema version. Bump + append a new migration step when the DDL grows. */
-const SCHEMA_VERSION = 17;
+/** Latest schema version. Bump + append a new migration step when the DDL grows.
+ *  Exported so migration tests assert "reached the module's current version"
+ *  instead of hardcoding the number — a schema bump then touches no test file. */
+export const SCHEMA_VERSION = 27;
 
 /** Absolute path to the database file: <worcaHome>/worca-cc.db. */
 export function dbPath() {
@@ -70,6 +73,7 @@ export function getDb() {
   mkdirSync(home, { recursive: true }); // chicken/egg: ensure the dir before open
   const db = _openConfiguredMigrated();  // open + pragmas + migrate, retried on BUSY
   maybeMigrateFromFs(db);    // one-shot fs→db import (other phase; self-guarded)
+  reconcileAfterFsImport(db);  // V24: archive v1 templates that import just created
   _db = db;                  // publish only after the DB is fully ready
   return _db;
 }
@@ -99,15 +103,22 @@ function _openConfiguredMigrated() {
 }
 
 /**
- * True when err is a transient SQLite lock/busy that retrying can clear. Prefers the
- * structured errcode (5 = SQLITE_BUSY, 6 = SQLITE_LOCKED) and falls back to the message
- * so a lock is still caught on any node:sqlite build that doesn't populate errcode. A
- * false positive only costs a bounded retry that still re-throws the original error.
+ * True when err is a transient SQLite error that retrying the open can clear. Prefers
+ * the structured errcode — 5 = SQLITE_BUSY, 6 = SQLITE_LOCKED, and primary code 10 =
+ * SQLITE_IOERR (extended codes carry it in the low byte) — and falls back to the
+ * message so a lock is still caught on any node:sqlite build that doesn't populate
+ * errcode. IOERR is here for the first-launch race on Windows: while one process
+ * performs the journal_mode=WAL switch, a competitor opening the same file can get
+ * "disk I/O error" from the -wal/-shm files being created and unlinked under it
+ * (seen on the Windows 11 VM with 12 concurrent openers). A persistent I/O error
+ * still surfaces: the retry is bounded and re-throws the original error. A false
+ * positive only costs that bounded retry.
  */
 function _isBusyError(err) {
   if (err && (err.errcode === 5 || err.errcode === 6)) return true;
+  if (err && Number.isInteger(err.errcode) && (err.errcode & 0xff) === 10) return true;
   const msg = err && err.message ? err.message : String(err);
-  return /locked|busy/i.test(msg);
+  return /locked|busy|disk I\/O error/i.test(msg);
 }
 
 /** Synchronous sleep (node:sqlite is sync; we must block this thread, not yield it). */
@@ -196,14 +207,14 @@ CREATE TABLE workflows (
 -- preserving unknown top-level keys (e.g. webUiTesting).
 CREATE TABLE project_config (
   project_key        TEXT PRIMARY KEY,
-  steps              TEXT NOT NULL DEFAULT '{}',  -- JSON: { role: {model?,effort?,fanOut?} }
+  steps              TEXT NOT NULL DEFAULT '{}',  -- JSON: { role: {model?,effort?,subagentModel?,fanOut?} }
   custom_models      TEXT NOT NULL DEFAULT '[]',  -- JSON: [ {id,label} ]
   active_workflow_id TEXT,
   extra              TEXT NOT NULL DEFAULT '{}'   -- JSON: unknown top-level keys
 );
 
 -- config_workflow_nodes: normalized per-node overrides (was config.json
--- workflows[wf].nodes[nodeId] = {model?,effort?,fanOut?}). One row per node.
+-- workflows[wf].nodes[nodeId] = {model?,effort?,subagentModel?,fanOut?}). One row per node.
 CREATE TABLE config_workflow_nodes (
   project_key TEXT NOT NULL,
   workflow_id TEXT NOT NULL,
@@ -513,6 +524,29 @@ CREATE TABLE IF NOT EXISTS step_questions (
 );
 `;
 
+/**
+ * v18 (task-source profiles): which PROFILE of a plugin task source a project or
+ * workspace uses. One row per (scope, plugin, source) — a project that pulls from
+ * two different sources binds each independently.
+ *
+ * scope_type is 'project' | 'workspace'; scope_key is projects.key or
+ * workspaces.id respectively. Deliberately NOT a foreign key: a binding must
+ * survive a project being removed and re-added at the same path (the key is a
+ * path hash, so it comes back identical), and source-bindings.mjs already treats
+ * a row whose plugin/profile no longer exists as "no binding".
+ */
+const SOURCE_BINDINGS_DDL = `
+CREATE TABLE IF NOT EXISTS source_bindings (
+  scope_type TEXT NOT NULL,   -- 'project' | 'workspace'
+  scope_key  TEXT NOT NULL,   -- projects.key | workspaces.id
+  plugin     TEXT NOT NULL,
+  source_id  TEXT NOT NULL,
+  profile    TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (scope_type, scope_key, plugin, source_id)
+);
+`;
+
 const GUARDRAIL_SETS_DDL = `
 CREATE TABLE IF NOT EXISTS guardrail_sets (
   id         TEXT PRIMARY KEY,
@@ -549,6 +583,146 @@ CREATE TABLE IF NOT EXISTS model_cost_flags (
 );
 `;
 
+/** v19: Ask Worca — assistant chat threads, messages, attachments and run links
+ *  (ask-worca-design.md §7.1). ALL `IF NOT EXISTS`, because this DDL runs from TWO
+ *  places: the `< 19` ladder step AND the schemaGaps() self-heal — a live DB stamped
+ *  19 by a divergent ladder (another branch) would otherwise never get the tables.
+ *  Nothing here is ALTERed later; a future ask_* column goes into INCREMENTAL_COLUMNS. */
+const ASK_DDL = `
+CREATE TABLE IF NOT EXISTS ask_threads (
+  id          TEXT PRIMARY KEY,            -- 'ask_' + 8 hex
+  title       TEXT,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL,
+  model       TEXT,                        -- last model / effort used
+  effort      TEXT,
+  session_id  TEXT,                        -- claude session for --resume; NULL = fresh
+  context     TEXT,                        -- JSON: last page context
+  totals      TEXT NOT NULL DEFAULT '{}'   -- JSON {costUsd,input,output,cacheRead,cacheCreation,turns,agents}
+);
+CREATE TABLE IF NOT EXISTS ask_messages (
+  id          TEXT PRIMARY KEY,
+  thread_id   TEXT NOT NULL REFERENCES ask_threads(id) ON DELETE CASCADE,
+  seq         INTEGER NOT NULL,            -- MAX(seq)+1 allocated inside tx()
+  role        TEXT NOT NULL,               -- user | assistant | system
+  text        TEXT NOT NULL DEFAULT '',
+  blocks      TEXT,                        -- JSON array (ask-worca-design.md §7.1 block schema)
+  status      TEXT,                        -- assistant: streaming | done | stopped | error
+  reason      TEXT,                        -- stopped: user | max_turns | max_budget
+  model       TEXT,
+  effort      TEXT,
+  usage       TEXT,                        -- JSON {input,output,cacheRead,cacheCreation}
+  cost_usd    REAL,                        -- NULL when the turn ended before a \`result\`
+  duration_ms INTEGER,
+  created_at  TEXT NOT NULL,
+  UNIQUE (thread_id, seq)
+);
+CREATE INDEX IF NOT EXISTS idx_ask_messages_thread ON ask_messages (thread_id, seq);
+CREATE TABLE IF NOT EXISTS ask_attachments (
+  id          TEXT PRIMARY KEY,
+  thread_id   TEXT NOT NULL REFERENCES ask_threads(id) ON DELETE CASCADE,
+  message_id  TEXT,
+  name        TEXT NOT NULL,               -- sanitized basename (display only)
+  bytes       INTEGER NOT NULL,
+  created_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_ask_attachments_thread ON ask_attachments (thread_id);
+CREATE TABLE IF NOT EXISTS ask_run_links (
+  thread_id   TEXT NOT NULL REFERENCES ask_threads(id) ON DELETE CASCADE,
+  run_id      TEXT NOT NULL,               -- runs-Map UUID from POST /api/run
+  pipeline_id TEXT,                        -- short id, from the first \`state\` event
+  card_id     TEXT,
+  status      TEXT,                        -- last seen status
+  phase       TEXT,
+  created_at  TEXT NOT NULL,
+  PRIMARY KEY (thread_id, run_id)
+);
+`;
+
+/** v20: append-only Ask Worca spend ledger (ask-cost-statistics-design.md §6).
+ *  NO foreign key on thread_id: spend is a permanent financial fact and must
+ *  survive thread deletion (cost_ledger precedent). One row per completed turn
+ *  with a finite cost > 0; tokens = input+output+cacheRead+cacheCreation. */
+const ASK_COST_LEDGER_DDL = `
+CREATE TABLE IF NOT EXISTS ask_cost_ledger (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  thread_id  TEXT NOT NULL,
+  message_id TEXT,
+  amount_usd REAL NOT NULL,
+  tokens     INTEGER,
+  model      TEXT,
+  ts         INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_ask_cost_ledger_ts ON ask_cost_ledger (ts);
+`;
+
+/** v21: Ask Worca worktrees — per-thread detached git checkouts
+ *  (ask-worca-worktrees-design.md §4). IF NOT EXISTS + an INCREMENTAL_TABLES entry (the
+ *  ask_cost_ledger precedent): reconcile-safe on divergent-stamp DBs. The git
+ *  state lives on disk under <worcaHome>/ask/<threadId>/wt/<id>; these rows are
+ *  the registry the cascade, the sweep and the UI read. */
+const ASK_WORKTREES_DDL = `
+CREATE TABLE IF NOT EXISTS ask_worktrees (
+  id              TEXT PRIMARY KEY,          -- 'wt_' + 8 hex
+  thread_id       TEXT NOT NULL REFERENCES ask_threads(id) ON DELETE CASCADE,
+  project_key     TEXT NOT NULL,
+  project_dir     TEXT NOT NULL,             -- source repo at creation time
+  ref             TEXT NOT NULL,             -- last ref the model checked out (label)
+  resolved_commit TEXT NOT NULL,             -- HEAD sha after the last navigation
+  run_id          TEXT,                      -- set when created via run-id sugar
+  worktree_dir    TEXT NOT NULL,
+  created_at      TEXT NOT NULL,
+  updated_at      TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_ask_worktrees_thread ON ask_worktrees (thread_id);
+`;
+
+/** v22: internal, line-anchored comments on a run's persisted diff. IF NOT EXISTS
+ *  + INCREMENTAL_TABLES entries (the ask_worktrees precedent): reconcile-safe on divergent-
+ *  stamp DBs. The anchor is (project_key, path, side, line_no) against
+ *  diff-patch.patch; `line_text` is the server-captured snapshot of that row, which
+ *  is what keeps a comment readable after the patch is gone. `source` and
+ *  `external_url` are RESERVED for a future GitHub review-comment sync and are
+ *  written by nothing today.
+ *  NOTE the pipelines cascade is declarative only: pipeline-delete.mjs states
+ *  the pipelines row is never DELETEd, so nothing may DEPEND on it firing — the
+ *  archive path deletes these rows explicitly. The ask_card_comments cascade DOES
+ *  fire (foreign_keys=ON in _configure) and is relied on.
+ *  ask_card_comments carries a proposal's commentIds from propose_run (which never
+ *  touches the card block) to POST /api/run, where they move onto
+ *  ask_run_links.comment_ids and are stamped onto sent_run_id by the first `state`
+ *  event.
+ *  This table is deliberately NOT `WITHOUT ROWID`: its implicit rowid is the
+ *  monotonic insertion counter listDiffComments orders by (D17). */
+const DIFF_COMMENTS_DDL = `
+CREATE TABLE IF NOT EXISTS diff_comments (
+  id           TEXT PRIMARY KEY,            -- 'dc_' + 8 hex
+  store_key    TEXT NOT NULL,               -- '<projectKey>' | 'workspaces/<workspaceId>'
+  pipeline_id  TEXT NOT NULL REFERENCES pipelines(id) ON DELETE CASCADE,
+  project_key  TEXT,                        -- member project of a workspace patch; NULL otherwise
+  path         TEXT NOT NULL,               -- NEW-side path of the anchored section
+  old_path     TEXT,                        -- the section's source path (rename): the read-time both-sides guard
+  side         TEXT NOT NULL,               -- 'old' | 'new'
+  line_no      INTEGER NOT NULL,
+  line_text    TEXT,                        -- snapshot of the anchored row, captured server-side
+  body         TEXT NOT NULL,
+  author       TEXT NOT NULL,               -- 'user' | 'ask'
+  resolved     INTEGER NOT NULL DEFAULT 0,
+  resolved_at  TEXT,
+  sent_run_id  TEXT,                        -- 8-hex pipeline id; NEVER auto-resolves
+  source       TEXT,                        -- RESERVED (GitHub sync) — unused
+  external_url TEXT,                        -- RESERVED (GitHub sync) — unused
+  created_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_diff_comments_run ON diff_comments (store_key, pipeline_id);
+CREATE TABLE IF NOT EXISTS ask_card_comments (
+  card_id    TEXT NOT NULL,                 -- proposal card id; the block itself is JSON in ask_messages
+  comment_id TEXT NOT NULL REFERENCES diff_comments(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (card_id, comment_id)
+);
+`;
+
 const SCHEMA_V11 = `
 ALTER TABLE config_workflow_nodes ADD COLUMN ask_questions INTEGER;
 ${STEP_QUESTIONS_DDL}
@@ -568,22 +742,85 @@ const INCREMENTAL_COLUMNS = {
   pipelines:              { resume_point: 'TEXT', owner_pid: 'INTEGER', owner_host: 'TEXT', heartbeat_at: 'TEXT',
                             source_type: "TEXT DEFAULT 'prompt'", source_ref: 'TEXT', guardrails_id: 'TEXT',
                             archived_at: 'TEXT', cost_cap_override: 'INTEGER NOT NULL DEFAULT 0',
-                            pr_url: 'TEXT', pr_number: 'INTEGER', pr_state: 'TEXT', pr_checked_at: 'TEXT' },
-  pipeline_steps:         { session_id: 'TEXT', skills: 'TEXT', graphify_count: 'INTEGER' },
-  sub_agents:             { ui_phase: 'TEXT', skills: 'TEXT', subagent_type: 'TEXT', graphify_count: 'INTEGER' },
-  workflows:              { domain: 'TEXT', origin: 'TEXT' },
-  config_workflow_nodes:  { ask_questions: 'INTEGER' },
+                            pr_url: 'TEXT', pr_number: 'INTEGER', pr_state: 'TEXT', pr_checked_at: 'TEXT',
+                            outcome: 'TEXT' },
+  pipeline_steps:         { session_id: 'TEXT', skills: 'TEXT', graphify_count: 'INTEGER',
+                            execution_id: 'TEXT', exec_kind: 'TEXT', agent_key: 'TEXT', ended_at: 'TEXT',
+                            exec_trigger: 'TEXT', exec_result: 'TEXT', exec_meta: 'TEXT' },
+  sub_agents:             { ui_phase: 'TEXT', skills: 'TEXT', subagent_type: 'TEXT', graphify_count: 'INTEGER',
+                            run_model: 'TEXT' },   // v25: the model the child actually ran on
+  workflows:              { domain: 'TEXT', origin: 'TEXT', graph: 'TEXT', archived_at: 'TEXT' },
+  config_workflow_nodes:  { ask_questions: 'INTEGER', subagent_model: 'TEXT' },  // v25: sub-agent model policy
+  ask_run_links:          { comment_ids: 'TEXT' },        // v22: JSON array of dc_ ids pending at launch
+  ask_attachments:        { kind: "TEXT NOT NULL DEFAULT 'text'",  // v27: text | image | binary (#398)
+                            mime: 'TEXT' },               // v27: sniffed mime; NULL on pre-v27 rows (= text)
 };
 
+/** v23: per-loop-wire cycle budgets, the graph-engine twin of
+ *  config_workflow_feedbacks (which becomes vestigial at the v1 kill list, never
+ *  dropped). IF NOT EXISTS + an INCREMENTAL_TABLES entry: some DBs already carry
+ *  this table from an earlier branch, with the PK columns in a different ORDER —
+ *  harmless, because every statement names its columns. */
+const CONFIG_WORKFLOW_WIRES_DDL = `
+CREATE TABLE IF NOT EXISTS config_workflow_wires (
+  project_key  TEXT NOT NULL,
+  workflow_id  TEXT NOT NULL,
+  wire_id      TEXT NOT NULL,
+  max_cycles   INTEGER NOT NULL,
+  PRIMARY KEY (project_key, workflow_id, wire_id)
+);
+`;
+
 /**
- * Return [{table, col, type}] for every INCREMENTAL_COLUMNS entry absent from the
- * live schema, plus `stepQuestionsTable`/`guardrailSetsTable: true` flags when
- * those IF-NOT-EXISTS tables are missing (safe to reassert on any stamped DB).
- * Cheap and read-only: one PRAGMA table_info per known table + one sqlite_master
- * probe each, no writes. A table absent from INCREMENTAL_COLUMNS' map (table_info
- * returns []) is skipped — creating base tables is the version ladder's job.
+ * Tables added after v1, keyed by name -> their IF-NOT-EXISTS DDL. Same hazard
+ * as INCREMENTAL_COLUMNS: a divergent ladder in another checkout can stamp the
+ * user_version past the step that creates one, so schemaGaps probes for them
+ * version-independently rather than trusting the stamp. A DDL block that creates
+ * several tables (ASK_DDL, DIFF_COMMENTS_DDL) is listed under EACH of them, so a
+ * DB missing only one is healed; repairSchemaGaps de-duplicates at exec time.
  */
-function schemaGaps(db) {
+const INCREMENTAL_TABLES = {
+  config_workflow_wires: CONFIG_WORKFLOW_WIRES_DDL,
+  step_questions:    STEP_QUESTIONS_DDL,
+  guardrail_sets:    GUARDRAIL_SETS_DDL,
+  cost_ledger:       COST_LEDGER_DDL,
+  model_cost_flags:  MODEL_COST_FLAGS_DDL,
+  source_bindings:   SOURCE_BINDINGS_DDL,
+  ask_threads:       ASK_DDL,
+  ask_messages:      ASK_DDL,
+  ask_attachments:   ASK_DDL,
+  ask_run_links:     ASK_DDL,
+  ask_cost_ledger:   ASK_COST_LEDGER_DDL,
+  ask_worktrees:     ASK_WORKTREES_DDL,
+  diff_comments:     DIFF_COMMENTS_DDL,
+  ask_card_comments: DIFF_COMMENTS_DDL,
+};
+
+/**
+ * Indexes added after their host table shipped, keyed by index name. Same hazard
+ * as INCREMENTAL_TABLES, but a missing index cannot be inferred from a missing
+ * table: idx_ask_attachments_thread was added to ASK_DDL after v19 shipped, so a
+ * DB that already HAS ask_attachments never re-runs that DDL. Probed only when
+ * the host table exists — otherwise INCREMENTAL_TABLES fires the DDL, which
+ * carries the CREATE INDEX itself.
+ */
+const INCREMENTAL_INDEXES = {
+  idx_ask_attachments_thread: {
+    table: 'ask_attachments',
+    ddl: 'CREATE INDEX IF NOT EXISTS idx_ask_attachments_thread ON ask_attachments (thread_id)',
+  },
+};
+
+/**
+ * The INCREMENTAL_COLUMNS entries absent from the live schema, as
+ * [{table, col, type}]. A table absent entirely (table_info returns []) is
+ * skipped — creating base tables is the version ladder's / the gap DDLs' job.
+ * Split out of schemaGaps() so repairSchemaGaps can RE-probe after its CREATEs:
+ * a table one repair pass creates (ask_run_links via ASK_DDL) has an empty
+ * table_info when that pass's gaps were computed, so its incremental columns are
+ * invisible until the tables exist.
+ */
+function missingColumns(db) {
   const missing = [];
   for (const [table, cols] of Object.entries(INCREMENTAL_COLUMNS)) {
     const have = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name));
@@ -592,37 +829,47 @@ function schemaGaps(db) {
       if (!have.has(col)) missing.push({ table, col, type });
     }
   }
-  const hasStepQuestions = db.prepare(
-    "SELECT count(*) AS n FROM sqlite_master WHERE type='table' AND name='step_questions'"
-  ).get().n > 0;
-  const hasGuardrailSets = db.prepare(
-    "SELECT count(*) AS n FROM sqlite_master WHERE type='table' AND name='guardrail_sets'"
-  ).get().n > 0;
-  const hasCostLedger = db.prepare(
-    "SELECT count(*) AS n FROM sqlite_master WHERE type='table' AND name='cost_ledger'"
-  ).get().n > 0;
-  const hasModelCostFlags = db.prepare(
-    "SELECT count(*) AS n FROM sqlite_master WHERE type='table' AND name='model_cost_flags'"
-  ).get().n > 0;
-  return {
-    columns: missing,
-    stepQuestionsTable: !hasStepQuestions,
-    guardrailSetsTable: !hasGuardrailSets,
-    costLedgerTable: !hasCostLedger,
-    modelCostFlagsTable: !hasModelCostFlags,
-  };
+  return missing;
+}
+
+const hasSqliteObject = (db, type, name) => db.prepare(
+  "SELECT count(*) AS n FROM sqlite_master WHERE type=? AND name=?"
+).get(type, name).n > 0;
+
+/**
+ * The INCREMENTAL_COLUMNS gaps plus the names of any INCREMENTAL_TABLES /
+ * INCREMENTAL_INDEXES that do not exist yet (all CREATEs are IF NOT EXISTS, so
+ * reasserting one on any stamped DB is safe). Cheap and read-only: PRAGMA
+ * table_info per known table plus one sqlite_master probe each, no writes.
+ */
+function schemaGaps(db) {
+  const tables = Object.keys(INCREMENTAL_TABLES)
+    .filter((t) => !hasSqliteObject(db, 'table', t));
+  const indexes = Object.entries(INCREMENTAL_INDEXES)
+    .filter(([name, { table }]) => hasSqliteObject(db, 'table', table)
+                                && !hasSqliteObject(db, 'index', name))
+    .map(([name]) => name);
+  return { columns: missingColumns(db), tables, indexes };
 }
 
 /** Apply the gap repairs with NO transaction control of its own — the caller owns
- *  the transaction (the ladder tx in migrate(), or reconcileSchema's own lock). */
+ *  the transaction (the ladder tx in migrate(), or reconcileSchema's own lock).
+ *  ORDER IS LOAD-BEARING: tables and indexes FIRST, then the columns RE-probed
+ *  against the post-CREATE schema. `gaps.columns` was computed BEFORE this pass
+ *  ran, so it cannot see an incremental column on a table this pass is about to
+ *  create (ask_run_links.comment_ids on a >=20-stamped DB missing the ask
+ *  tables) — the ALTER would be skipped and the DB stamped current with the
+ *  column absent, and only a LATER migrate() would heal it. No gap DDL
+ *  references an INCREMENTAL_COLUMNS column, so nothing here needs an ALTER to
+ *  run first. */
 function repairSchemaGaps(db, gaps) {
-  for (const { table, col, type } of gaps.columns) {
+  // One DDL block can create several tables (ASK_DDL, DIFF_COMMENTS_DDL) — the
+  // Set collapses the duplicate keys to a single idempotent exec.
+  for (const ddl of new Set((gaps.tables || []).map((t) => INCREMENTAL_TABLES[t]))) db.exec(ddl);
+  for (const name of gaps.indexes || []) db.exec(INCREMENTAL_INDEXES[name].ddl);
+  for (const { table, col, type } of missingColumns(db)) {
     db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${type}`);
   }
-  if (gaps.stepQuestionsTable) db.exec(STEP_QUESTIONS_DDL);
-  if (gaps.guardrailSetsTable) db.exec(GUARDRAIL_SETS_DDL);
-  if (gaps.costLedgerTable) db.exec(COST_LEDGER_DDL);
-  if (gaps.modelCostFlagsTable) db.exec(MODEL_COST_FLAGS_DDL);
 }
 
 /**
@@ -638,8 +885,8 @@ function repairSchemaGaps(db, gaps) {
  */
 function reconcileSchema(db) {
   const gaps = schemaGaps(db);
-  if (gaps.columns.length === 0 && !gaps.stepQuestionsTable && !gaps.guardrailSetsTable
-      && !gaps.costLedgerTable && !gaps.modelCostFlagsTable) return; // clean — no lock
+  if (gaps.columns.length === 0 && gaps.tables.length === 0
+      && gaps.indexes.length === 0) return; // clean — no lock
   db.exec('BEGIN IMMEDIATE');
   try {
     repairSchemaGaps(db, schemaGaps(db)); // re-probe under the lock: race-safe
@@ -650,6 +897,29 @@ function reconcileSchema(db) {
   }
 }
 
+/**
+ * The fs→db import runs after migrate(), so v1 templates it brings in miss the
+ * V24 archive pass. Cheap probe first (hand-seeded upgrade fixtures reach getDb()
+ * with a partial `workflows` table — without the column probe this throws
+ * "no such column: version" and takes the whole open down), then one idempotent
+ * reconcile in its own transaction. No seeding on this path — the seeds, if any,
+ * landed during the ladder. Its own report key keeps the break's account intact.
+ */
+function reconcileAfterFsImport(db) {
+  const cols = new Set(db.prepare('PRAGMA table_info(workflows)').all().map((c) => c.name));
+  if (!cols.has('version') || !cols.has('archived_at')) return;
+  const hit = db.prepare('SELECT 1 AS n FROM workflows WHERE version = 1 AND archived_at IS NULL LIMIT 1').get();
+  if (!hit) return;
+  db.exec('BEGIN IMMEDIATE');
+  let report;
+  try { report = reconcileV1Workflows(db, { seed: false }); db.exec('COMMIT'); }
+  catch (err) { db.exec('ROLLBACK'); throw err; }
+  if (hasSqliteTable(db, 'store_meta')) {
+    db.prepare('INSERT OR REPLACE INTO store_meta (key, kind, data) VALUES (?, ?, ?)')
+      .run('migration:v24:fs-import', 'migration', JSON.stringify(report));
+  }
+}
+
 /**
  * Incremental v11 -> v12 REPAIR migration for the collision documented on
  * INCREMENTAL_COLUMNS: DBs stamped 11 by the ai-enablement-onboarding branch's
@@ -666,7 +936,7 @@ function applySchemaV12(db) {
 /**
  * Incremental v12 -> v13 migration (plugin task-sources, spec 2026-07-12 §10):
  *   pipelines.source_type TEXT DEFAULT 'prompt'  -- 'prompt' | 'markdown' | 'plugin'
- *   pipelines.source_ref  TEXT                   -- JSON {plugin,sourceId,taskId,url,title}; NULL unless plugin
+ *   pipelines.source_ref  TEXT                   -- JSON {plugin,sourceId,taskId,profile,inputs,url,title}; NULL unless plugin
  *   workflows.origin      TEXT                   -- 'plugin:<name>' provenance; NULL = user-created
  * Implemented as a CONDITIONAL repair (same shape as applySchemaV12), NOT a plain
  * DDL string: the three columns live in INCREMENTAL_COLUMNS (hard rule above), so
@@ -684,7 +954,7 @@ function applySchemaV13(db) {
  *   guardrail_sets table            -- named guardrail sets (built-ins are virtual, never rows)
  *   pipelines.guardrails_id TEXT    -- the run's selected set id; NULL = legacy/pre-entity row
  * A CONDITIONAL repair like applySchemaV12/13, NOT plain DDL: the column lives in
- * INCREMENTAL_COLUMNS and the table in the schemaGaps flags, so earlier heals on a
+ * INCREMENTAL_COLUMNS and the table in INCREMENTAL_TABLES, so earlier heals on a
  * ladder pass from <12 have ALREADY added them — an unconditional ALTER/CREATE
  * would throw "duplicate column"/"table already exists" on every fresh DB.
  */
@@ -742,6 +1012,430 @@ function applySchemaV16(db) {
   }
 }
 
+/**
+ * v19 -> v20 (ask-cost-statistics-design.md §6): ask_cost_ledger — the
+ * append-only, FK-free Ask Worca spend ledger (survives thread deletion) —
+ * plus a backfill of one row per already-persisted costed assistant message,
+ * so pre-upgrade chat spend lands in Statistics. Gap-repair first, v12-v16
+ * style; the NOT EXISTS guard keeps re-runs (divergent stamps) idempotent.
+ * Threads deleted before the upgrade left no messages (CASCADE) — accepted.
+ * The backfill runs only on a ladder pass through <20; a binary downgrade
+ * after v20 leaves its chat spend un-ledgered forever (the stamp stays 20) —
+ * same accepted posture as cost_ledger.
+ */
+function applySchemaV20(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+  // A hand-built or divergent DB (minimal test seeds) can lack ask_messages
+  // columns entirely — such a DB never stored a chat cost, nothing to backfill.
+  const has = (table, col) =>
+    db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === col);
+  if (!has('ask_messages', 'cost_usd')) return;
+  const rows = db.prepare(`
+    SELECT id, thread_id, cost_usd, usage, model, created_at
+    FROM ask_messages
+    WHERE cost_usd > 0
+      AND NOT EXISTS (SELECT 1 FROM ask_cost_ledger l WHERE l.message_id = ask_messages.id)
+  `).all();
+  const ins = db.prepare(
+    'INSERT INTO ask_cost_ledger (thread_id, message_id, amount_usd, tokens, model, ts) VALUES (?, ?, ?, ?, ?, ?)');
+  for (const r of rows) {
+    const ts = Date.parse(r.created_at ?? '');
+    if (!Number.isFinite(ts)) continue;
+    let tokens = null;
+    try {
+      const u = JSON.parse(r.usage ?? 'null');
+      if (u && typeof u === 'object') {
+        tokens = ['input', 'output', 'cacheRead', 'cacheCreation']
+          .reduce((a, k) => a + (Number(u[k]) || 0), 0);
+      }
+    } catch { /* unreadable usage — tokens stay NULL */ }
+    ins.run(r.thread_id, r.id, r.cost_usd, tokens, r.model, ts);
+  }
+}
+
+/** v22: both new tables are IF NOT EXISTS and the one new ask_run_links column
+ *  lives in INCREMENTAL_COLUMNS, so the whole step IS the reconcile — the
+ *  applySchemaV12/13/14/15 shape, with nothing to backfill.
+ *  On a FRESH DB (indeed any ladder pass from <12) this step is already a no-op
+ *  by the time it runs: applySchemaV12 is the ladder's FIRST repairSchemaGaps, so
+ *  it fires ASK_DDL and DIFF_COMMENTS_DDL, and — because repairSchemaGaps ALTERs
+ *  its columns AFTER its CREATEs, against a re-probe — adds
+ *  ask_run_links.comment_ids in that same pass. This step is what serves an
+ *  EXISTING v20/v21 DB (and any stamp that first materialises ask_run_links right
+ *  here), and re-running it is idempotent by construction.
+ */
+function applySchemaV22(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+}
+
+/** v23 (node-graph v2): workflows.graph/archived_at, the pipeline_steps execution
+ *  ledger columns, pipelines.outcome and config_workflow_wires. Every piece lives
+ *  in INCREMENTAL_COLUMNS/INCREMENTAL_TABLES, so the whole step IS the reconcile —
+ *  the applySchemaV22 shape, with nothing to backfill. Purely additive: no row is
+ *  read, rewritten or archived here (that is the v24 break). */
+function applySchemaV23(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+}
+
+/** v25 (sub-agent model policy): config_workflow_nodes.subagent_model holds the
+ *  per-node setting, sub_agents.run_model records the model a spawned child
+ *  actually ran on. Both are plain additive columns declared in
+ *  INCREMENTAL_COLUMNS — and this repairSchemaGaps call is what CREATES them on
+ *  the one real upgrade path: a DB stamped exactly 24 takes the LADDER, where
+ *  this is the only repair before the version stamp (reconcileSchema runs only
+ *  on the fast path, user_version >= SCHEMA_VERSION). Do NOT delete this step
+ *  as redundant; test/db-migrate-v25.test.mjs pins the stamped-24 path. */
+function applySchemaV25(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+}
+
+/** v26 (Fable 5.1 replaces Fable 5 in PREDEFINED_MODELS): a pin left on the
+ *  retired id would render as "(default model)" in every picker — its option is
+ *  gone — and be rejected on the next write (config.mjs `unknown model
+ *  "claude-fable-5"`), while the run itself kept passing the old id to
+ *  `claude --model`. So every stored pin moves to the successor: the
+ *  config_workflow_nodes.model column, the per-role project_config.steps JSON,
+ *  and node defaults inside workflows.graph (nodes[].config.model is the shape
+ *  workflows.mjs validates; a bare nodes[].model is covered too). Ids match
+ *  case-insensitively, as config.mjs compares them. History (pipelines,
+ *  sub_agents.run_model, ask_*) records what actually ran and is left alone.
+ *  A one-word rename is reversible, so unlike V24 it takes no backup. JSON
+ *  that does not parse is left exactly as found — a broken row must not take
+ *  the ladder down. */
+const V26_MODEL_RENAMES = [['claude-fable-5', 'claude-fable-5-1']];
+
+function applySchemaV26(db) {
+  for (const [from, to] of V26_MODEL_RENAMES) renameStoredModelPins(db, from, to);
+}
+
+/** v27 (Ask Worca binary attachments, #398): ask_attachments.kind/mime — plain
+ *  additive columns declared in INCREMENTAL_COLUMNS, applySchemaV25's shape: this
+ *  repairSchemaGaps call is what CREATES them on the ladder path (a DB stamped
+ *  exactly 26), reconcileSchema covers the fast path. Existing rows keep the
+ *  column DEFAULT 'text', which is exactly what every pre-v27 attachment is. */
+function applySchemaV27(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+}
+
+/** Move every stored pin on model id `from` (lower-case) to `to`. Each table
+ *  is guarded like V24's: hand-seeded upgrade fixtures (and a DB from before the
+ *  fs->db import) reach this step without some of them. */
+function renameStoredModelPins(db, from, to) {
+  const hasTable = (t) => hasSqliteTable(db, t);
+  const isFrom = (v) => typeof v === 'string' && v.trim().toLowerCase() === from;
+  const renameIn = (sel) => {
+    if (!sel || typeof sel !== 'object' || !isFrom(sel.model)) return false;
+    sel.model = to;
+    return true;
+  };
+  if (hasTable('config_workflow_nodes')) {
+    db.prepare('UPDATE config_workflow_nodes SET model = ? WHERE lower(trim(model)) = ?').run(to, from);
+  }
+
+  const like = `%${from}%`;   // cheap pre-filter; the JSON walk below decides
+  const setSteps = hasTable('project_config') && db.prepare('UPDATE project_config SET steps = ? WHERE project_key = ?');
+  for (const row of setSteps ? db.prepare('SELECT project_key, steps FROM project_config WHERE steps LIKE ?').all(like) : []) {
+    let steps;
+    try { steps = JSON.parse(row.steps); } catch { continue; }
+    if (!steps || typeof steps !== 'object' || Array.isArray(steps)) continue;
+    let changed = false;
+    for (const sel of Object.values(steps)) changed = renameIn(sel) || changed;
+    if (changed) setSteps.run(JSON.stringify(steps), row.project_key);
+  }
+
+  const hasGraphColumn = () => db.prepare('PRAGMA table_info(workflows)').all().some((c) => c.name === 'graph');
+  const setGraph = hasTable('workflows') && hasGraphColumn()
+    && db.prepare('UPDATE workflows SET graph = ? WHERE id = ?');
+  for (const row of setGraph ? db.prepare('SELECT id, graph FROM workflows WHERE graph LIKE ?').all(like) : []) {
+    let graph;
+    try { graph = JSON.parse(row.graph); } catch { continue; }
+    if (!graph || typeof graph !== 'object' || !Array.isArray(graph.nodes)) continue;
+    let changed = false;
+    for (const node of graph.nodes) {
+      if (!node || typeof node !== 'object') continue;
+      changed = renameIn(node.config) || changed;
+      changed = renameIn(node) || changed;
+    }
+    if (changed) setGraph.run(JSON.stringify(graph), row.id);
+  }
+}
+
+/** Audit channel for V24 (dev convention: one console.warn per decision). */
+const auditV24 = (msg) => console.warn(`[worca] V24: ${msg}`);
+
+/** The pipeline_events line + stderr audit a swept v1 run gets. VERBATIM. */
+export const V1_RUN_RETIRED = 'paused on the v1 engine before the graph rework — not resumable';
+
+/** Absolute path of the OPEN handle's main database file ('' for :memory:). */
+function mainDbFile(db) {
+  try {
+    const row = db.prepare('PRAGMA database_list').all().find((r) => r.name === 'main');
+    return row && typeof row.file === 'string' ? row.file : '';
+  } catch { return ''; }
+}
+
+/** A .pre-v24.bak we would actually restore from: opens as SQLite and is stamped
+ *  BEFORE the break (a partial file fails to open, a 0-byte file reads 0).
+ *  databaseSyncCtor() is db.mjs's own lazy accessor — node:sqlite is deliberately
+ *  NOT imported at module-link time (see the file header), so never write
+ *  `new DatabaseSync(...)` here. */
+function usableBackup(bak) {
+  if (!existsSync(bak)) return false;
+  let probe = null;
+  try {
+    probe = new (databaseSyncCtor())(bak, { readOnly: true });
+    const v = probe.prepare('PRAGMA user_version').get().user_version;
+    return v > 0 && v < 24;
+  } catch { return false; }
+  finally { try { if (probe) probe.close(); } catch { /* ignore */ } }
+}
+
+/**
+ * V24 is the only ladder step that rewrites user data destructively (V26 renames
+ * one model id, reversibly), so an existing DB is
+ * snapshotted BEFORE the transaction opens (`VACUUM INTO` cannot run inside one
+ * — measured: "cannot VACUUM from within a transaction"). Skipped for a fresh
+ * file (nothing to lose) and for `:memory:` (PRAGMA database_list gives file '').
+ * A throw here is FATAL on purpose: no backup, no break.
+ *
+ * Two hazards the naive `existsSync` guard misses, both measured on node 25:
+ *  - a CONCURRENT migrator (CLI + UI first launch) can win the race and leave us
+ *    with `output file already exists` (errcode 1) — NOT a busy-shaped error, so
+ *    getDb()'s retry loop would rethrow and kill this process. A backup someone
+ *    else just took is a SUCCESS, so re-check and return.
+ *  - a 0-byte / half-written .bak from a crashed attempt would be read as "done".
+ *    VACUUM INTO overwrites an empty file happily, so re-take unless the file is
+ *    a readable SQLite DB carrying the pre-break user_version.
+ */
+function backupBeforeV24(db) {
+  const current = db.prepare('PRAGMA user_version').get().user_version;
+  if (current <= 0 || current >= 24) return;
+  const file = mainDbFile(db);
+  if (!file) return;                       // :memory:
+  const bak = `${file}.pre-v24.bak`;
+  if (usableBackup(bak)) return;
+  try {
+    db.exec(`VACUUM INTO '${bak.replace(/'/g, "''")}'`);
+  } catch (err) {
+    // Someone else took it while we were deciding — that is the point of the file.
+    if (usableBackup(bak)) return;
+    throw new Error(`worca cannot take the pre-v24 database backup at ${bak}: `
+      + `${err && err.message ? err.message : err}. The v2 upgrade rewrites saved `
+      + 'pipelines, so it refuses to run without one — free disk space or make '
+      + `${dirname(file)} writable and start worca again.`, { cause: err });
+  }
+}
+
+/** v24: the break. Runs INSIDE the ladder transaction. */
+function applySchemaV24(db, { existing }) {
+  repairSchemaGaps(db, schemaGaps(db));       // heal a divergent stamp first
+  const report = reconcileV1Workflows(db, { seed: existing });
+  report.sweptRuns = sweepV1Runs(db);
+  // Minimal hand-seeded ladders (migrate-v20, db-migrate-v23) have no store_meta
+  // table: there is nothing to audit and the INSERT would abort the ladder tx.
+  if (!hasSqliteTable(db, 'store_meta')) return;
+  // INSERT OR IGNORE, deliberately: this row records THE BREAK. A later
+  // reconcile pass (fs-import, a divergent re-stamp) must not overwrite the
+  // account of what the upgrade actually did — it writes its own key instead.
+  db.prepare('INSERT OR IGNORE INTO store_meta (key, kind, data) VALUES (?, ?, ?)')
+    .run('migration:v24', 'migration', JSON.stringify(report));
+}
+
+/** Does this handle carry a table with that name? (Hand-seeded ladder fixtures build a
+ *  two-column `pipelines` and nothing else, so every V24 pass probes first.) */
+function hasSqliteTable(db, name) {
+  return !!db.prepare("SELECT 1 AS n FROM sqlite_master WHERE type = 'table' AND name = ?").get(name);
+}
+
+/**
+ * Archive every LIVE v1 template row (D7: kept, hidden, never converted, never
+ * deleted), insert the 7 seed graphs on an EXISTING DB, fold the coexistence
+ * alias, re-attach the static overlay maps and reset an archived active
+ * workflow. Fully idempotent: a second run changes nothing.
+ * @param {DatabaseSync} db
+ * @param {{seed?:boolean}} [opts] seed=true only for a DB that existed before V24
+ * @returns {{at:string, archived:string[], seeded:string[], seedsSkipped:string[],
+ *            overlayNodes:number, overlayWires:number, aliasRemapped:number,
+ *            overlaysDisplaced:number, activeReset:string[], sweptRuns:string[]}}
+ */
+export function reconcileV1Workflows(db, { seed = false } = {}) {
+  const report = { at: new Date().toISOString(), archived: [], seeded: [], seedsSkipped: [],
+    overlayNodes: 0, overlayWires: 0, aliasRemapped: 0, overlaysDisplaced: 0,
+    activeReset: [], sweptRuns: [] };
+  const cols = new Set(db.prepare('PRAGMA table_info(workflows)').all().map((c) => c.name));
+  for (const need of ['version', 'steps', 'feedbacks', 'created_at', 'updated_at', 'graph', 'archived_at']) {
+    if (!cols.has(need)) return report;      // minimal hand-seeded test schema: nothing to do
+  }
+  // Hand-seeded upgrade fixtures (subagent-migration*.test.mjs seed a faithful
+  // v1 schema) carry `workflows` + `config_workflow_nodes` but NOT
+  // config_workflow_feedbacks / config_workflow_wires / project_config: the base
+  // DDL that creates them only runs for current < 1. Probe before every pass.
+  const hasTable = (t) => hasSqliteTable(db, t);
+  const now = new Date().toISOString();
+
+  // 1) Archive — the WHERE makes it idempotent and keeps an already-archived row's stamp.
+  const live = db.prepare('SELECT id, name FROM workflows WHERE version = 1 AND archived_at IS NULL').all();
+  const archive = db.prepare('UPDATE workflows SET archived_at = ? WHERE id = ? AND version = 1 AND archived_at IS NULL');
+  for (const row of live) {
+    archive.run(now, row.id);
+    report.archived.push(row.id);
+    auditV24(`archived v1 workflow ${row.id} (${row.name}) — v1 templates are not runnable on the graph engine`);
+  }
+
+  // 2) Seeds — EXISTING DBs only (fresh installs keep Default only, decision D7).
+  if (seed) {
+    const find = db.prepare('SELECT id, archived_at FROM workflows WHERE id = ?');
+    const insert = db.prepare(`INSERT OR IGNORE INTO workflows
+      (id, name, version, domain, origin, steps, feedbacks, graph, created_at, updated_at, archived_at)
+      VALUES (?, ?, 2, ?, NULL, '[]', '[]', ?, ?, ?, NULL)`);
+    for (const t of SEED_TEMPLATES) {
+      const row = find.get(t.id);
+      if (row) {
+        if (row.archived_at) {
+          report.seedsSkipped.push(t.id);
+          auditV24(`seed ${t.id} skipped — id held by an archived template`);
+        }
+        continue;                            // a LIVE v2 row with that id is the user's own
+      }
+      insert.run(t.id, t.name, t.domain, JSON.stringify({ nodes: t.nodes, wires: t.wires }), t.createdAt, now);
+      report.seeded.push(t.id);
+    }
+  }
+  // 3) The coexistence alias dies FIRST, and it WINS: an overlay the user set on
+  //    the graph default under its alias is NEWER than any v1-era row on the same
+  //    workflow id. INSERT OR REPLACE (not UPDATE OR IGNORE) so the alias row
+  //    overwrites a colliding target instead of being silently dropped, then the
+  //    alias rows are removed. Every displaced row is audited.
+  //    Running this BEFORE the NODE_ID_MAP remap is the whole point: the other
+  //    order mints wf_default/n_plan from the LEGACY s0_0 row first, and the
+  //    fold then hits the PK and is skipped — the user's newer value lost,
+  //    aliasRemapped 0, no audit line, the alias rows still there.
+  //    The column list is read from the LIVE schema, never hardcoded: a fixed
+  //    list would silently blank config_workflow_nodes.ask_questions (an
+  //    INCREMENTAL_COLUMNS column) on every folded row.
+  const ALIAS = 'wf_default_v2';
+  const DEFAULT_ID = 'wf_default';
+  for (const [table, keyCol] of [
+    ['config_workflow_nodes', 'node_id'],
+    ['config_workflow_wires', 'wire_id'],
+  ]) {
+    if (!hasTable(table)) continue;
+    const colNames = db.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name);
+    const colList = colNames.join(', ');
+    const sel = colNames.map((c) => (c === 'workflow_id' ? `'${DEFAULT_ID}' AS workflow_id` : c)).join(', ');
+    const displaced = db.prepare(
+      `SELECT count(*) AS n FROM ${table} a WHERE a.workflow_id = ?
+         AND EXISTS (SELECT 1 FROM ${table} b WHERE b.project_key = a.project_key
+           AND b.workflow_id = ? AND b.${keyCol} = a.${keyCol})`).get(ALIAS, DEFAULT_ID).n;
+    if (displaced) auditV24(`${table}: ${displaced} wf_default overlay row(s) replaced by the newer wf_default_v2 value`);
+    report.aliasRemapped += db.prepare(
+      `INSERT OR REPLACE INTO ${table} (${colList}) SELECT ${sel} FROM ${table} WHERE workflow_id = ?`).run(ALIAS).changes;
+    db.prepare(`DELETE FROM ${table} WHERE workflow_id = ?`).run(ALIAS);
+  }
+  if (hasTable('project_config')) {
+    report.aliasRemapped += db.prepare('UPDATE project_config SET active_workflow_id = ? WHERE active_workflow_id = ?')
+      .run(DEFAULT_ID, ALIAS).changes;
+  }
+  const pipeCols = new Set(db.prepare('PRAGMA table_info(pipelines)').all().map((c) => c.name));
+  if (pipeCols.has('resume_point')) {
+    // Only a v2 point can name the alias meaningfully; a v1 point that names it
+    // is swept by sweepV1Runs, so the `version = 2` filter is load-bearing.
+    report.aliasRemapped += db.prepare(`UPDATE pipelines
+        SET resume_point = json_set(resume_point, '$.workflowId', ?)
+      WHERE resume_point IS NOT NULL AND json_valid(resume_point)
+        AND json_extract(resume_point, '$.version') = 2
+        AND json_extract(resume_point, '$.workflowId') = ?`).run(DEFAULT_ID, ALIAS).changes;
+  }
+  if (report.aliasRemapped) {
+    auditV24(`remapped ${report.aliasRemapped} row(s) from the wf_default_v2 alias to wf_default`);
+  }
+
+  // 4) Static overlay maps, AFTER the fold (idempotent). A rename that would
+  //    collide with a row the fold just installed is DROPPED — the v2 value wins
+  //    — and the stale v1-keyed row is deleted so no v1 node id survives.
+  if (hasTable('config_workflow_nodes')) {
+    const remapNode = db.prepare(
+      'UPDATE OR IGNORE config_workflow_nodes SET node_id = ? WHERE workflow_id = ? AND node_id = ?');
+    const dropStale = db.prepare('DELETE FROM config_workflow_nodes WHERE workflow_id = ? AND node_id = ?');
+    for (const [wfId, map] of Object.entries(NODE_ID_MAP)) {
+      for (const [oldId, newId] of Object.entries(map)) {
+        report.overlayNodes += remapNode.run(newId, wfId, oldId).changes;
+        const left = dropStale.run(wfId, oldId).changes;   // 0 unless the rename was ignored
+        if (left) {
+          report.overlaysDisplaced += left;
+          auditV24(`${wfId}: dropped ${left} stale "${oldId}" overlay row(s) — "${newId}" already carries a newer value`);
+        }
+      }
+    }
+  }
+
+  // 5) config_workflow_feedbacks rows are COPIED (never moved) onto their wire
+  //    ids: the table stays vestigial but readable, so the migration is reversible.
+  if (hasTable('config_workflow_feedbacks') && hasTable('config_workflow_wires')) {
+    const copyWire = db.prepare(`INSERT OR IGNORE INTO config_workflow_wires
+        (project_key, workflow_id, wire_id, max_cycles)
+      SELECT project_key, workflow_id, ?, max_cycles
+        FROM config_workflow_feedbacks WHERE workflow_id = ? AND fb_id = ?`);
+    for (const [wfId, map] of Object.entries(FB_WIRE_MAP)) {
+      for (const [fbId, wireId] of Object.entries(map)) {
+        report.overlayWires += copyWire.run(wireId, wfId, fbId).changes;
+      }
+    }
+  }
+
+  // 6) An active workflow that just got archived is not runnable — fall back.
+  //    The WHERE is scoped to ARCHIVED rows: a project pointing at a live seed
+  //    keeps its choice.
+  const stranded = hasTable('project_config') ? db.prepare(`SELECT project_key, active_workflow_id FROM project_config
+    WHERE active_workflow_id IN (SELECT id FROM workflows WHERE archived_at IS NOT NULL)`).all() : [];
+  if (stranded.length) {
+    const reset = db.prepare('UPDATE project_config SET active_workflow_id = ? WHERE project_key = ?');
+    for (const r of stranded) {
+      reset.run(DEFAULT_ID, r.project_key);
+      report.activeReset.push(r.project_key);
+      auditV24(`project ${r.project_key}: active pipeline ${r.active_workflow_id} was archived — reset to wf_default`);
+    }
+  }
+  return report;
+}
+
+/**
+ * Retire every run that can only be resumed by the v1 engine: paused OR
+ * interrupted with a resume point that is not `version: 2`. The row keeps its
+ * honest status trail — status becomes 'interrupted', the resume point is
+ * NULLed (so History hides Resume and removePluginWorkflows can never be
+ * stranded on it) and a pipeline_events line records why. `json_valid` guards a
+ * corrupt blob: it is swept too, and json_extract never throws on it (the spec's
+ * predicate is `!= 2` alone; the guard is this plan's addition so a corrupt blob
+ * cannot abort the migration transaction).
+ * Exported and callable without an argument so boot/reconcile paths can run it
+ * on a DB that a divergent ladder stamped past 24.
+ * @param {DatabaseSync} [db]
+ * @returns {string[]} the ids swept
+ */
+export function sweepV1Runs(db = getDb()) {
+  // Minimal hand-seeded test schemas (migrate-v20, db-migrate-v23 build a
+  // `pipelines (id TEXT PRIMARY KEY)` table and run the whole ladder on it) have
+  // neither the columns nor pipeline_events: nothing to sweep, and the SELECT
+  // below would throw "no such column: status" INSIDE the ladder transaction.
+  const cols = new Set(db.prepare('PRAGMA table_info(pipelines)').all().map((c) => c.name));
+  if (!cols.has('status') || !cols.has('resume_point')) return [];
+  if (!hasSqliteTable(db, 'pipeline_events')) return [];
+  const rows = db.prepare(`SELECT id FROM pipelines
+    WHERE status IN ('paused', 'interrupted') AND resume_point IS NOT NULL
+      AND (json_valid(resume_point) = 0 OR json_extract(resume_point, '$.version') != 2)`).all();
+  if (!rows.length) return [];
+  const clear = db.prepare("UPDATE pipelines SET status = 'interrupted', resume_point = NULL WHERE id = ?");
+  const event = db.prepare('INSERT INTO pipeline_events (pipeline_id, ts, text) VALUES (?, ?, ?)');
+  const now = new Date().toISOString();
+  for (const r of rows) {
+    clear.run(r.id);
+    event.run(r.id, now, V1_RUN_RETIRED);
+    auditV24(`run ${r.id}: ${V1_RUN_RETIRED}`);
+  }
+  return rows.map((r) => r.id);
+}
+
 /**
  * Idempotent, versioned, CONCURRENCY-SAFE schema migration. Fast-path no-op when
  * PRAGMA user_version already == SCHEMA_VERSION. Otherwise it takes the write lock
@@ -770,6 +1464,9 @@ export function migrate(db) {
   // up front (a deferred BEGIN would not lock until the first write, letting two
   // migrators both pass the gate and double-apply SCHEMA_V1 → "table projects already
   // exists"). Under the lock we re-read user_version and no-op if the winner stamped it.
+  // V24 rewrites data (archive + seed + sweep): snapshot the file first. Outside
+  // the tx by necessity — VACUUM cannot run inside one — and fatal on throw.
+  backupBeforeV24(db);
   db.exec('BEGIN IMMEDIATE');
   try {
     const current = db.prepare('PRAGMA user_version').get().user_version; // re-check under lock
@@ -791,6 +1488,18 @@ export function migrate(db) {
     if (current < 15) applySchemaV15(db);
     if (current < 16) applySchemaV16(db);
     if (current < 17) db.exec(MODEL_COST_FLAGS_DDL); // IF NOT EXISTS — reconcile-safe
+    // v17 -> v18 (task-source profiles): source_bindings. IF NOT EXISTS —
+    // reconcileSchema may already have created it on a divergently-stamped DB.
+    if (current < 18) db.exec(SOURCE_BINDINGS_DDL);
+    if (current < 19) db.exec(ASK_DDL);              // IF NOT EXISTS — reconcile-safe
+    if (current < 20) applySchemaV20(db);            // ask_cost_ledger + backfill
+    if (current < 21) db.exec(ASK_WORKTREES_DDL);    // IF NOT EXISTS — reconcile-safe
+    if (current < 22) applySchemaV22(db);            // tables + the ask_run_links column
+    if (current < 23) applySchemaV23(db);            // graph columns + config_workflow_wires
+    if (current < 24) applySchemaV24(db, { existing: current >= 1 });  // the v2 break
+    if (current < 25) applySchemaV25(db);            // sub-agent model policy + recorded child model
+    if (current < 26) applySchemaV26(db);            // Fable 5 pins -> Fable 5.1 (catalog swap)
+    if (current < 27) applySchemaV27(db);            // ask_attachments.kind/mime (#398)
     db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
     db.exec('COMMIT');
   } catch (err) {
@@ -818,6 +1527,17 @@ export function closeDb() {
  * Not re-entrant: SQLite has no nested BEGIN, so a tx() inside a tx() throws
  * rather than silently joining (or corrupting) the outer transaction. Compose by
  * passing data between calls, not by nesting.
+ *
+ * BEGIN IMMEDIATE, not a deferred BEGIN — every tx() here is a WRITE transaction,
+ * and most of them read first (MAX(seq)+1, a read-modify-write of a JSON column, a
+ * uniqueness scan). A deferred BEGIN takes only a WAL read snapshot on that first
+ * SELECT and then has to UPGRADE at the first write; if another process committed
+ * in between, SQLite answers SQLITE_BUSY_SNAPSHOT, which the busy handler does NOT
+ * retry (busy_timeout cannot help: the snapshot is already stale). The whole tx()
+ * threw "database is locked" and the write was silently lost. Taking the write
+ * lock up front makes busy_timeout apply instead, so a second writer QUEUES.
+ * migrate()/reconcileSchema() take the same lock for the same reason. Keep every
+ * tx() body short and synchronous: the lock is held for its whole duration.
  * @template T
  * @param {() => T} fn
  * @returns {T}
@@ -825,7 +1545,7 @@ export function closeDb() {
 export function tx(fn) {
   if (_txDepth > 0) throw new Error('tx(): a transaction is already active (nested tx is not supported)');
   const db = getDb();
-  db.exec('BEGIN');
+  db.exec('BEGIN IMMEDIATE');
   _txDepth = 1;
   try {
     const result = fn();