@yemi33/minions 0.1.2379 → 0.1.2381

package/engine/shared.js

@@ -71,25 +71,16 @@ const ENGINE_DIR = path.join(MINIONS_DIR, 'engine');
 // don't collide with heap-snapshot pruning.
 const CRASH_REPORTS_DIR = path.join(ENGINE_DIR, 'diagnostics', 'crash-reports');
 const CONTROL_PATH = path.join(ENGINE_DIR, 'control.json');
-const COOLDOWNS_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 // W-mp60tw0u000j3931: Persistent cross-restart engine state (migration markers,
 // one-shot reconciliation versions, etc.). Distinct from CONTROL_PATH which is
 // process-lifetime (state/pid/ownerToken). See ENGINE_DEFAULTS.abandonedReconciliationVersion
 // for the first consumer.
-const ENGINE_STATE_PATH = path.join(ENGINE_DIR, 'state.json');
-// Phase 9.3: wrap raw safeWrite callers for kb-checkpoint, kb-swept,
-// kb-sweep-state, and test-results so they go through mutateJsonFileLocked
-// (the same path mutateControl / mutateEngineState / mutateCooldowns use).
-// This sets them up for SQL routing via _SMALL_STATE_MUTATE_ROUTES later, and
-// in the case of kb-sweep-state.json closes a real cross-process race (the
-// dashboard process and the detached kb-sweep-runner child both write it).
+// File-backed coordination and diagnostic state uses lock-safe mutators.
 const KB_CHECKPOINT_PATH = path.join(ENGINE_DIR, 'kb-checkpoint.json');
 const KB_SWEPT_PATH = path.join(ENGINE_DIR, 'kb-swept.json');
 const KB_SWEEP_STATE_PATH = path.join(ENGINE_DIR, 'kb-sweep-state.json');
 const TEST_RESULTS_PATH = path.join(ENGINE_DIR, 'test-results.json');
-const PR_LINKS_PATH = path.join(MINIONS_DIR, 'engine', 'pr-links.json');
 const PINNED_ITEMS_PATH = path.join(MINIONS_DIR, 'engine', 'kb-pins.json');
-const LOG_PATH = path.join(MINIONS_DIR, 'engine', 'log.json');
 // Constellation-bridge cross-repo marker (P-wi1-bridge-readonly). Written by the
 // Constellation agent's bridge on every successful poll; read by `minions bridge
 // status` to surface the last-seen timestamp. The engine itself never writes
@@ -340,7 +331,7 @@ function buildEditsSeen(comments, prev, cap) {
 
 // ── Secret Redaction (SEC-09) ──────────────────────────────────────────────
 // Pure, side-effect-free redactor applied to every entry on the log write path
-// so ADO tokens, JWTs, and azureauth stdout dumps never land in engine/log.json
+// so ADO tokens, JWTs, and azureauth stdout dumps never land in persisted logs
 // (2500-entry ring buffer readable by any local process).
 //
 // Replacements (order matters — azureauth first, then Bearer, then bare JWT):
@@ -464,7 +455,7 @@ let _logFlushTimer = null;
 function log(level, msg, meta = {}) {
   // SEC-09: redact sensitive patterns (ADO tokens, JWTs, azureauth stdout)
   // before both the in-memory buffer push and the console echo — ensures
-  // nothing sensitive is persisted to engine/log.json or engine stdout logs.
+  // nothing sensitive is persisted to the log store or engine stdout logs.
   const safeMsg = typeof msg === 'string' ? _redactString(msg) : msg;
   const safeMeta = redactSecrets(meta) || {};
   const entry = { timestamp: ts(), level, message: safeMsg, ...safeMeta };
@@ -500,30 +491,7 @@ function log(level, msg, meta = {}) {
   }
 }
 
-/**
- * Resolve the log file path at write time, not at module load time.
- *
- * `LOG_PATH` is captured eagerly when shared.js first loads. In production this
- * is fine — there's a single shared.js instance per process. In tests the
- * require cache is busted to swap MINIONS_DIR, but modules NOT in
- * ISOLATED_MODULES (engine/github.js, engine/ado.js, etc.) keep a reference to
- * the OLD shared.js whose `LOG_PATH` still points at `D:/squad/engine/log.json`.
- * That leaked test pollution into the live engine log (e.g. `_test/backoff-*`,
- * `this-playbook-does-not-exist-xyz`, `TEST-EXT-*` meeting IDs).
- *
- * Resolution order:
- *   1. `MINIONS_TEST_DIR` — per-test isolation root (regression tests rely
- *      on this — log goes to `<tmpdir>/engine/log.json`).
- *   2. `MINIONS_LOG_PATH` — default test log target. Set at the top of
- *      `test/unit.test.js` so tests that exercise log() without explicit
- *      isolation (e.g. github backoff helpers, cooldown helpers) still land
- *      in a benign tmp file instead of the live `D:/squad/engine/log.json`.
- *   3. `MINIONS_HOME` / repo root fallback — production behavior.
- *
- * Lazy resolution honors the *current* env at flush time, so even unbussed
- * dependents write to the test dir while the test owns it.
- */
-// Resolve the SQL state.db path at write time.
+// Resolve the SQL database at write time so test roots stay isolated.
 function _currentLogDbPath() {
   if (process.env.MINIONS_TEST_DIR) {
     return path.join(path.resolve(process.env.MINIONS_TEST_DIR), 'engine', 'state.db');
@@ -547,9 +515,9 @@ function resolveEngineCacheDir(fallbackEngineDir) {
 // try/catch and the caller sees them. Dashboard self-open and `minions dash`
 // / `minions restart` post-health open all funnel through here.
 //
-// Every call writes a structured `event: 'browser-open'` entry to log.json
+// Every call writes a structured `event: 'browser-open'` log entry
 // (via shared.log) and bumps a per-reason counter in `_engine.browserOpens`
-// in metrics.json. Callers MUST pass `opts.reason` so the log/metric is
+// in metrics state. Callers MUST pass `opts.reason` so the log/metric is
 // attributable; a missing reason is logged at `warn` level with
 // `reason: 'unknown'` to make a regression loud rather than silent.
 //
@@ -620,7 +588,7 @@ function openUrlInBrowser(url, opts = {}) {
 }
 
 // Bump per-reason counter under metrics._engine.browserOpens. Best-effort —
-// metrics.json writes must never throw out of openUrlInBrowser. Schema:
+// Metrics writes must never throw out of openUrlInBrowser. Schema:
 //   _engine.browserOpens.<reason> = { count, suppressedCount, lastAt }
 function _bumpBrowserOpenMetric(reason, { suppressed = false } = {}) {
   try {
@@ -668,7 +636,7 @@ function _flushLogBuffer() {
     for (const [dbPath, entries] of byDbPath) {
       store.appendLogsToDbFile(dbPath, entries);
     }
-  } catch { /* logs-store unavailable (node<22.5) — JSON mirror still works */ }
+  } catch { /* logging is best-effort */ }
 
 }
 
@@ -684,11 +652,6 @@ function flushLogs() {
 // ── File I/O ─────────────────────────────────────────────────────────────────
 
 function safeRead(p) {
-  const prdStore = require('./prd-store');
-  if (prdStore.parsePrdPath(p)) {
-    const prd = prdStore.readPrd(p);
-    return prd == null ? '' : JSON.stringify(prd, null, 2);
-  }
   try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
 }
 
@@ -698,24 +661,10 @@ function safeRead(p) {
 // the client-sent document body with '' when the file was deleted/moved
 // between panel open and send.
 function safeReadOrNull(p) {
-  const prdStore = require('./prd-store');
-  if (prdStore.parsePrdPath(p)) {
-    const prd = prdStore.readPrd(p);
-    return prd == null ? null : JSON.stringify(prd, null, 2);
-  }
   try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
 }
 
 function safeReadDir(dir) {
-  const resolved = path.resolve(dir);
-  const prdRoot = path.resolve(MINIONS_DIR, 'prd');
-  const prdArchive = path.join(prdRoot, 'archive');
-  if (resolved === prdRoot || resolved === prdArchive) {
-    const archived = resolved === prdArchive;
-    return require('./prd-store').listPrdRows()
-      .filter(row => row.archived === archived)
-      .map(row => row.filename);
-  }
   try { return fs.readdirSync(dir); } catch { return []; }
 }
 
@@ -845,125 +794,9 @@ function isSourcePlanContentStale(plansDir, plan) {
   return out;
 }
 
-// ── SQL-routing shim for migrated state files ──────────────────────────────
-//
-// Phase 9 (post-Phase 8 cleanup): every state file that has a SQL backing
-// (dispatches, work-items, pull-requests, metrics, watches, schedule-runs,
-// pipeline-runs, managed-processes, worktree-pool, qa-runs, qa-sessions)
-// becomes SQL-only at the read API surface. The JSON sidecar files stop
-// being mirror-written; this shim makes existing `safeJson*` callers
-// transparently read from SQL so we don't have to convert ~40 call sites
-// in engine.js / dashboard.js / cleanup.js / etc.
-//
-// Matching is by path suffix rather than full-prefix against MINIONS_DIR,
-// because tests using MINIONS_TEST_DIR re-resolve the dir but use the same
-// suffix pattern. Returns `{value}` on hit, `null` on miss; callers fall
-// through to ordinary file-backed JSON handling.
-//
-// Per-project work-items / pull-requests need scope extraction from the
-// path. `<MINIONS_DIR>/projects/<name>/work-items.json` → scope `<name>`;
-// `<MINIONS_DIR>/work-items.json` → scope `central`.
-function _routeJsonReadToSql(p) {
-  if (!p || typeof p !== 'string') return null;
-  const norm = p.replace(/\\/g, '/');
-  // Only route reads from paths inside MINIONS_DIR. Tests that use
-  // createTmpDir() write to ad-hoc temp paths that shouldn't be hijacked
-  // by the SQL stores (the path-suffix patterns below would otherwise
-  // match e.g. `<tmp>/pull-requests.json` and return empty SQL data).
-  const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
-  if (!norm.startsWith(minionsNorm + '/') && norm !== minionsNorm) return null;
-  let m;
-  try {
-    if (norm.endsWith('/engine/dispatch.json')) {
-      const store = require('./dispatch-store');
-      return { value: store.readDispatchSectioned() };
-    }
-    if (norm.endsWith('/engine/metrics.json')) {
-      const store = require('./metrics-store');
-      return { value: store.readMetrics() };
-    }
-    if (norm.endsWith('/engine/watches.json')) {
-      const store = require('./watches-store');
-      return { value: store.readWatches() };
-    }
-    if (norm.endsWith('/engine/schedule-runs.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readScheduleRuns() };
-    }
-    if (norm.endsWith('/engine/pipeline-runs.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readPipelineRuns() };
-    }
-    if (norm.endsWith('/engine/managed-processes.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readManagedProcesses() };
-    }
-    if (norm.endsWith('/engine/worktree-pool.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readWorktreePool() };
-    }
-    if (norm.endsWith('/engine/qa-runs.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readQaRuns() };
-    }
-    if (norm.endsWith('/engine/qa-sessions.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readQaSessions() };
-    }
-    if (norm.endsWith('/engine/pr-links.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readPrLinks() };
-    }
-    if (norm.endsWith('/engine/cooldowns.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readCooldowns() };
-    }
-    if (norm.endsWith('/engine/pending-rebases.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readPendingRebases() };
-    }
-    if (norm.endsWith('/engine/cc-sessions.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readCcSessions() };
-    }
-    if (norm.endsWith('/engine/doc-sessions.json')) {
-      const store = require('./small-state-store');
-      return { value: store.readDocSessions() };
-    }
-    // Per-project work-items.json — the path is now only a scope identifier.
-    if ((m = norm.match(/\/projects\/([^/]+)\/work-items\.json$/))) {
-      const store = require('./work-items-store');
-      return { value: store.readWorkItemsForScope(m[1]) };
-    }
-    // Per-project pull-requests.json
-    if ((m = norm.match(/\/projects\/([^/]+)\/pull-requests\.json$/))) {
-      const store = require('./pull-requests-store');
-      return { value: store.readPullRequestsForScope(m[1]) };
-    }
-    // Central work-items.json — `<MINIONS_DIR>/work-items.json`. Must not
-    // collide with `/projects/<name>/work-items.json` (handled above).
-    if (/(^|\/)work-items\.json$/.test(norm) && !/\/projects\//.test(norm)) {
-      const store = require('./work-items-store');
-      return { value: store.readWorkItemsForScope('central') };
-    }
-    // Central pull-requests.json
-    if (/(^|\/)pull-requests\.json$/.test(norm) && !/\/projects\//.test(norm)) {
-      const store = require('./pull-requests-store');
-      return { value: store.readPullRequestsForScope('central') };
-    }
-  } catch (e) {
-    // Phase 9.4: store/load failures (not SQLite-unavailable — the CLI shim
-    // in bin/minions.js guarantees node:sqlite is loadable) propagate up so
-    // the caller can decide whether to retry or surface.
-    throw e;
-  }
-  return null;
-}
-
 /**
  * Read a JSON file with **automatic restore from `.backup` sidecar** on
- * missing/corrupt primary. Intended for live, mutable state files
- * (work-items.json, dispatch.json, pull-requests.json, etc.) that are paired
+ * missing/corrupt primary. Intended for intentionally file-backed data paired
  * with a `.backup` sidecar written by `safeWrite`. Returns the parsed JSON,
  * or null when both primary and backup are missing/unparseable.
  *
@@ -972,45 +805,12 @@ function _routeJsonReadToSql(p) {
  * to the primary path (best-effort). This protects live state from torn
  * writes / interrupted saves.
  *
- * **SQL routing (Phase 9):** when the path matches a migrated state file
- * (work-items, pull-requests, dispatch, metrics, watches, schedule-runs,
- * pipeline-runs, managed-processes, worktree-pool, qa-runs, qa-sessions,
- * pr-links), the read is served from SQLite via `_routeJsonReadToSql` — the
- * JSON file on disk is no longer authoritative.
- *
  * Counterpart: `safeJsonNoRestore` for terminal artifacts and "missing == gone"
  * reads (cooldowns, archived PRDs, ephemeral session state) where reviving a
  * stale `.backup` is actively harmful. See its JSDoc for selection guidance.
  */
 
-// PL-prd-no-backup (W-mqub65ez0004b3bd) — PRD `.json` files must NOT auto-restore
-// from a stale `.backup` sidecar: a removed/archived PRD coming back and
-// re-dispatching work is the original resurrection footgun (W-mouptdh1000h9f39).
-// Phase 10 step 4.3 — BROADENED from prd/archive/ to ALL prd/*.json (root +
-// archive). The root-level backup lifecycle previously survived ONLY to recover
-// the enforceDeclaredPlanProject rename-race (a concurrent sweep deleting a
-// just-renamed PRD); that rename is now retired and SQL is the canonical store,
-// so the sidecar is pure resurrection fuel with no remaining benefit:
-//   - prd/*.json AND prd/archive/*.json → no backup write + no safeJson restore.
-// Matches a single filename segment under prd/ (optionally one archive/ level),
-// so nested non-PRD paths and plans/ (which are .md) are unaffected.
-const _NO_BACKUP_JSON_RE = /(?:^|[\\/])prd[\\/](?:archive[\\/])?[^\\/]+\.json$/i;
-function _isNoBackupJsonPath(p) {
-  return typeof p === 'string' && _NO_BACKUP_JSON_RE.test(p);
-}
-
 function safeJson(p) {
-  // Internal opt-out (positional second arg from mutateJsonFileLocked):
-  // when truthy, skip the SQL-routing shim and do a raw disk read. Used
-  // when the caller already holds the file lock and needs the on-disk
-  // bytes as the source of truth (so the read+write pair is atomic).
-  const skipSqlRouting = arguments.length > 1 && arguments[1] && arguments[1].skipSqlRouting;
-  if (!skipSqlRouting) {
-    const prdStore = require('./prd-store');
-    if (prdStore.parsePrdPath(p)) return prdStore.readPrd(p);
-    const routed = _routeJsonReadToSql(p);
-    if (routed) return routed.value;
-  }
   // Split the read from the parse so we can distinguish "file missing" (normal
   // pre-create state — silent) from "file present but corrupt JSON" (real
   // integrity failure — must log). Without this split a `JSON.parse(read)` in
@@ -1034,8 +834,6 @@ function safeJson(p) {
       console.error(`[safeJson] parse failure for ${path.basename(p)}: ${parseErr.message}`);
     }
   }
-  // Archived PRDs (prd/archive/) are permanently gone — skip .backup restore.
-  if (_isNoBackupJsonPath(p)) return null;
   // Primary missing or corrupted — try restoring from .backup sidecar.
   const backupPath = p + '.backup';
   try {
@@ -1070,23 +868,16 @@ function safeJsonArr(p) { return safeJson(p) || []; }
 
 /**
  * Sibling of safeJson for terminal-artifact and "missing == gone" reads
- * (PRDs in `prd/`, archived plans, cooldowns, ephemeral session state —
- * anything where a missing primary should NOT auto-restore from a stale
+ * (archived plans and any other data where a missing primary should not
+ * auto-restore from a stale
  * `.backup` sidecar). Returns the parsed JSON on success, or `defaultValue`
  * (default `null`) on **any** failure: missing file, unparseable JSON, or
  * IO error. The `.backup` sidecar is never consulted.
  *
  * Why a separate primitive: safeJson's restore-on-miss is correct for live
- * state files (work-items.json, dispatch.json, pull-requests.json, etc.) but
+ * file-backed data, but
  * actively harmful for terminal artifacts. Examples of misuse and the bugs
  * they hide:
- *   - Archived PRDs leave a `.backup` sidecar in `prd/`; reading the active
- *     path with safeJson silently restores it and the dashboard sees a
- *     phantom "active" PRD (W-mouptdh1000h9f39). PRDs are end-state — no
- *     resurrection.
- *   - Cooldowns are time-bounded ephemeral state (24h TTL). Restoring a
- *     stale `cooldowns.json.backup` could resurrect expired entries that
- *     should already have been pruned, suppressing legitimate dispatches.
  *   - Restoring corrupt-primary scenarios from `.backup` masks the underlying
  *     write integrity failure and breaks State Integrity tests.
  *
@@ -1105,10 +896,6 @@ function safeJsonArr(p) { return safeJson(p) || []; }
  * @returns {*} Parsed JSON on success, otherwise `defaultValue`.
  */
 function safeJsonNoRestore(p, defaultValue = null) {
-  const prdStore = require('./prd-store');
-  if (prdStore.parsePrdPath(p)) return prdStore.readPrd(p) ?? defaultValue;
-  const routed = _routeJsonReadToSql(p);
-  if (routed) return routed.value ?? defaultValue;
   let raw;
   try {
     raw = fs.readFileSync(p, 'utf8');
@@ -1135,12 +922,6 @@ function safeJsonNoRestore(p, defaultValue = null) {
 let _tmpCounter = 0;
 
 function safeWrite(p, data) {
-  const prdStore = require('./prd-store');
-  if (prdStore.parsePrdPath(p)) {
-    if (typeof data === 'string') data = JSON.parse(data);
-    prdStore.writePrd(p, data);
-    return;
-  }
   const dir = path.dirname(p);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   const content = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
@@ -1235,7 +1016,7 @@ function createDispatchTmpDir(dispatchId) {
 }
 
 // Validate a tmpDir path before destructive ops (rmSync). Defends against a
-// corrupted/poisoned dispatch.json `entry.tmpDir` field pointing at an
+// corrupted/poisoned dispatch `entry.tmpDir` field pointing at an
 // arbitrary directory: must resolve under <MINIONS_DIR>/engine/tmp/, basename
 // must match `dispatch-*`, and lstat must be a real directory (not a symlink).
 function validateDispatchTmpDir(dirPath) {
@@ -1348,42 +1129,10 @@ function forEachPidFile(callback) {
   }
 }
 
-function neutralizeJsonBackupSidecar(filePath, inertData = { status: 'archived' }) {
-  const backupPath = filePath + '.backup';
-  try {
-    // Retry the unlink — on Windows a transient EPERM/EBUSY (AV scanner, lagging
-    // OS handle, indexer) otherwise leaves the .backup sidecar in place, and the
-    // next by-name safeJson() resurrects the just-deleted PRD from it. _retryFsOp
-    // rethrows non-retryable codes (e.g. ENOENT) immediately, so the absent path
-    // below still fires for an already-missing sidecar.
-    _retryFsOp(() => fs.unlinkSync(backupPath), `neutralize backup ${path.basename(backupPath)}`);
-    return { ok: true, action: 'removed', backupPath };
-  } catch (unlinkErr) {
-    if (unlinkErr.code === 'ENOENT') return { ok: true, action: 'absent', backupPath };
-    try {
-      safeWrite(backupPath, inertData);
-      return {
-        ok: true,
-        action: 'neutralized',
-        backupPath,
-        unlinkError: unlinkErr.message,
-      };
-    } catch (writeErr) {
-      return {
-        ok: false,
-        action: 'failed',
-        backupPath,
-        unlinkError: unlinkErr.message,
-        writeError: writeErr.message,
-      };
-    }
-  }
-}
-
 // ── Dispatch Prompt Sidecar (#1167) ─────────────────────────────────────────
 // Large prompts (PR diffs, build error logs, coalesced human feedback) inlined
-// into dispatch.json caused hundreds-of-MB bloat per entry and eventual V8 OOM
-// at startup. Sidecar files keep dispatch.json small while preserving full
+// into dispatch state caused hundreds-of-MB bloat per entry and eventual V8 OOM.
+// Sidecar files keep dispatch rows small while preserving full
 // content for the agent at spawn time.
 
 // Resolve lazily so MINIONS_TEST_DIR overrides work in tests.
@@ -1441,7 +1190,7 @@ function sidecarDispatchPrompt(item, thresholdBytes) {
 /**
  * Read the effective prompt for a dispatch item. Prefers the sidecar file when
  * `_promptFile` is set so spawnAgent always sees the full prompt even though
- * dispatch.json only stores a small stub.
+ * dispatch state only stores a small stub.
  */
 function resolveDispatchPrompt(item) {
   if (!item) return '';
@@ -1472,13 +1221,6 @@ function deleteDispatchPromptSidecar(item) {
   for (const p of paths) safeUnlink(p);
 }
 
-/**
- * Startup guard: throw a clear error when a state file has grown past
- * maxStateFileBytes. Without this the dashboard silently OOMs on JSON.parse
- * (seen on a 491 MB dispatch.json + 509 MB cooldowns.json — #1167).
- * The thrown error points at the bloated file so operators can act instead
- * of chasing V8 heap traces.
- */
 // ── Stop-intent flag (engine/stop-intent.json) ──────────────────────────────
 //
 // File-presence signal used by the external supervisor (engine/supervisor.js)
@@ -1517,25 +1259,6 @@ function isStopIntentSet() {
   return fs.existsSync(STOP_INTENT_PATH);
 }
 
-function assertStateFileSize(filePath, maxBytes) {
-  const limit = Number(maxBytes) > 0 ? Number(maxBytes) : ENGINE_DEFAULTS.maxStateFileBytes;
-  try {
-    const stat = fs.statSync(filePath);
-    if (stat.size > limit) {
-      throw new Error(
-        `State file too large: ${filePath} is ${Math.round(stat.size / (1024 * 1024))} MB ` +
-        `(limit ${Math.round(limit / (1024 * 1024))} MB). ` +
-        `This usually means dispatch prompts or cooldown contexts were inlined and not sidecarred. ` +
-        `Inspect/trim the file manually, then restart. See engine/contexts/ for sidecar files.`
-      );
-    }
-  } catch (e) {
-    if (e.code === 'ENOENT') return; // file absent is fine
-    if (e.message && e.message.startsWith('State file too large:')) throw e;
-    // Other stat errors (permission etc.) — do not block startup
-  }
-}
-
 function sleepMs(ms) {
   try {
     const ab = new SharedArrayBuffer(4);
@@ -1799,127 +1522,28 @@ function withFileLock(lockPath, fn, {
   throw lastErr;
 }
 
-// Route table for small-state files migrated to SQL stores. Each entry
-// declares the SQL store function to invoke and the expected default JSON
-// shape (for the "ensure file exists" fallback below).
-const _STATE_MUTATE_ROUTES = {
-  'dispatch.json':         { module: './dispatch-store', fn: 'applyDispatchMutation' },
-  'metrics.json':          { module: './metrics-store', fn: 'applyMetricsMutation' },
-  'watches.json':          { module: './watches-store', fn: 'applyWatchesMutation' },
-  'schedule-runs.json':    { module: './small-state-store', fn: 'applyScheduleRunsMutation' },
-  'pipeline-runs.json':    { module: './small-state-store', fn: 'applyPipelineRunsMutation' },
-  'managed-processes.json': { module: './small-state-store', fn: 'applyManagedProcessesMutation' },
-  'worktree-pool.json':    { module: './small-state-store', fn: 'applyWorktreePoolMutation' },
-  'qa-runs.json':          { module: './small-state-store', fn: 'applyQaRunsMutation' },
-  'qa-sessions.json':      { module: './small-state-store', fn: 'applyQaSessionsMutation' },
-  'cooldowns.json':        { module: './small-state-store', fn: 'applyCooldownsMutation' },
-  'pending-rebases.json':  { module: './small-state-store', fn: 'applyPendingRebasesMutation' },
-  'cc-sessions.json':      { module: './small-state-store', fn: 'applyCcSessionsMutation' },
-  'doc-sessions.json':     { module: './small-state-store', fn: 'applyDocSessionsMutation' },
-  'pr-links.json':         { module: './small-state-store', fn: 'applyPrLinksMutation' },
-};
-
-function _tryRouteMutateToSql(filePath, mutateFn, onWrote) {
-  const baseName = path.basename(filePath);
-  const stateRoute = _STATE_MUTATE_ROUTES[baseName];
-  if (baseName !== 'work-items.json' && baseName !== 'pull-requests.json' && !stateRoute) return null;
-  const fpNorm = String(filePath).replace(/\\/g, '/');
-  const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
-  const insideMinionsDir = fpNorm.startsWith(minionsNorm + '/') || fpNorm === minionsNorm + '/' + baseName;
-  if (!insideMinionsDir) return null;
-
-  // Small-state files live exclusively under <MINIONS_DIR>/engine/<baseName>.
-  // Don't hijack writes to ad-hoc paths that happen to share the basename.
-  if (stateRoute) {
-    if (!fpNorm.endsWith('/engine/' + baseName)) return null;
-    const store = require(stateRoute.module);
-    try {
-      require('./db').getDb();
-    } catch (e) {
-      throw new Error(`small-state-store: SQLite unavailable — ${e.message}`);
-    }
-    const out = store[stateRoute.fn]((data) => {
-      const next = mutateFn(data);
-      if (onWrote) onWrote();
-      return next;
-    });
-    const result = out && Object.prototype.hasOwnProperty.call(out, 'result') ? out.result : undefined;
-    return { routed: result };
-  }
-
-  let result;
-  if (baseName === 'work-items.json') {
-    result = mutateWorkItems(filePath, (arr) => {
-      const out = mutateFn(arr);
-      if (onWrote) onWrote();
-      return out;
-    });
-  } else {
-    // pull-requests.json: preserve legacy-ID normalization the JSON path
-    // applied before invoking the mutator (parity with mutateJsonFileLocked
-    // body at the pull-requests.json normalization site).
-    const project = resolveProjectForPrPath(filePath);
-    result = mutatePullRequests(filePath, (arr) => {
-      if (Array.isArray(arr)) normalizePrRecords(arr, project);
-      const out = mutateFn(arr);
-      if (onWrote) onWrote();
-      return out;
-    });
-  }
-  return { routed: result };
-}
-
 function mutateJsonFileLocked(filePath, mutateFn, {
   defaultValue = {},
   lockRetries,
   lockRetryBackoffMs,
   skipWriteIfUnchanged = false,
   onWrote = null,
-  _skipSqlRouting = false,
 } = {}) {
   const lockPath = `${filePath}.lock`;
   const retries = lockRetries ?? ENGINE_DEFAULTS.lockRetries;
   const retryBackoffMs = lockRetryBackoffMs ?? ENGINE_DEFAULTS.lockRetryBackoffMs;
-  const prdStore = require('./prd-store');
-  if (!_skipSqlRouting && prdStore.parsePrdPath(filePath)) {
-    return prdStore.mutatePrd(filePath, mutateFn, { defaultValue });
-  }
-  // Route migrated path-shaped state APIs to SQL.
-  if (!_skipSqlRouting) {
-    const routed = _tryRouteMutateToSql(filePath, mutateFn, onWrote);
-    if (routed) return routed.routed;
-  }
   return withFileLock(lockPath, () => {
     const fileExists = fs.existsSync(filePath);
-    let data = safeJson(filePath, { skipSqlRouting: true });
+    let data = safeJson(filePath);
     const parsedInvalid = fileExists && data === null;
     if (data === null || typeof data !== 'object') data = Array.isArray(defaultValue) ? [...defaultValue] : { ...defaultValue };
-    // Normalize BEFORE taking the baseline snapshot so that both `beforeSerialized`
-    // and the post-mutator snapshot reflect post-normalize state. Capturing the
-    // baseline before normalize breaks the `skipWriteIfUnchanged` optimization for
-    // pull-requests.json files: a no-op mutator on a denormalized file would
-    // always trip the write path because normalization itself shifted serialized
-    // bytes between the two snapshots (P-bfa1c-skipwrite-timing). The trade-off
-    // is intentional: when normalization is the ONLY change, we deliberately
-    // leave the on-disk file denormalized — readers re-run normalizePrRecords on
-    // load (see getPrLinks, engine/queries.js:670-674), so the in-memory contract
-    // is preserved without the per-poll mtime bump.
-    if (path.basename(filePath) === 'pull-requests.json' && Array.isArray(data)) {
-      normalizePrRecords(data, resolveProjectForPrPath(filePath));
-    }
     const beforeSerialized = skipWriteIfUnchanged ? JSON.stringify(data) : null;
     const next = mutateFn(data);
     const finalData = next === undefined ? data : next;
     const shouldWrite = !skipWriteIfUnchanged || parsedInvalid || JSON.stringify(finalData) !== beforeSerialized;
     if (shouldWrite) {
-      // Back up last-known-good state before mutation (best-effort). SKIP for
-      // archived PRDs under prd/archive/: a .backup there is resurrection fuel
-      // (PL-prd-no-backup, W-mqub65ez0004b3bd). Root-level prd/*.json retains
-      // the backup lifecycle — concurrent-sweep loss must be recoverable.
-      if (!_isNoBackupJsonPath(filePath)) {
-        const backupPath = filePath + '.backup';
-        try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
-      }
+      const backupPath = filePath + '.backup';
+      try { if (fileExists) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
       safeWrite(filePath, finalData);
       // Side-effect hook fired only when an actual write happened. Callers
       // use this to emit cache-invalidation signals (events table row) so
@@ -2020,33 +1644,34 @@ function recordEngineRespawn(source) {
   return { count, crashLoop };
 }
 
-// W-mp60tw0u000j3931: Lock-safe read-modify-write for engine/state.json — the
-// persistent cross-restart engine-level state file (migration markers,
-// one-shot reconciliation versions, etc.). Mirrors mutateControl's shape.
 function mutateEngineState(mutator) {
-  return mutateJsonFileLocked(ENGINE_STATE_PATH, (data) => {
+  const store = require('./small-state-store');
+  const { result } = store.applyEngineStateMutation((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
     return mutator(data) || data;
-  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+  });
+  return result;
 }
 
 function readEngineState() {
-  const data = safeJson(ENGINE_STATE_PATH);
+  const data = require('./small-state-store').readEngineState();
   if (!data || typeof data !== 'object' || Array.isArray(data)) return {};
   return data;
 }
 
 function mutateCooldowns(mutator) {
-  return mutateJsonFileLocked(COOLDOWNS_PATH, (data) => {
+  const store = require('./small-state-store');
+  const { wrote, result } = store.applyCooldownsMutation((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
     return mutator(data) || data;
-  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+  });
+  if (wrote) {
+    try { require('./db-events').emitStateEvent('cooldowns'); } catch { /* optional */ }
+  }
+  return result;
 }
 
-// Phase 9.3 (W-mp48wxqw / SQL-canonicalization prep): lock-safe RMW wrappers
-// for the small JSON state files that were still going through raw safeWrite.
-// Pattern mirrors mutateControl / mutateEngineState / mutateCooldowns — so a
-// future SQL migration is a mechanical _SMALL_STATE_MUTATE_ROUTES addition.
+// Lock-safe wrappers for intentionally file-backed coordination state.
 
 // KB classification checkpoint counter (consolidation.js post-classify).
 function mutateKbCheckpoint(mutator) {
@@ -2856,6 +2481,80 @@ function classifyInboxItem(name, content) {
 // config.json keep working without an on-disk rewrite. Tracked in
 // docs/deprecated.json (id: worktreemode-field-rename).
 const CHECKOUT_MODES = Object.freeze({ WORKTREE: 'worktree', LIVE: 'live' });
+const LEGACY_LIVE_VALIDATION_TYPE_ALIASES = Object.freeze({
+  'build-and-test': 'test',
+});
+
+function normalizeLiveValidationWorkType(value) {
+  if (typeof value !== 'string') return '';
+  const type = value.trim();
+  return LEGACY_LIVE_VALIDATION_TYPE_ALIASES[type] || type;
+}
+
+function inspectLiveValidation(value) {
+  if (value === undefined || value === null || value === '') {
+    return { configured: false, types: [], normalizedType: undefined, error: null };
+  }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    return {
+      configured: true,
+      types: [],
+      normalizedType: undefined,
+      error: 'Invalid liveValidation: must be an object { type, autoDispatch }.',
+    };
+  }
+
+  const rawType = value.type;
+  const rawTypes = Array.isArray(rawType) ? rawType : [rawType];
+  if (
+    (typeof rawType !== 'string' && !Array.isArray(rawType))
+    || rawTypes.length === 0
+    || !rawTypes.every(type => typeof type === 'string' && type.trim())
+  ) {
+    const accepted = [...LIVE_VALIDATION_WORK_TYPES].sort().join(', ');
+    return {
+      configured: true,
+      types: [],
+      normalizedType: undefined,
+      error: `Invalid liveValidation: "type" is required and must be a non-empty string, or a non-empty array of live-capable work-item types. Accepted values: ${accepted}.`,
+    };
+  }
+
+  const normalizedTypes = [...new Set(rawTypes.map(normalizeLiveValidationWorkType))];
+  const types = normalizedTypes.filter(type => LIVE_VALIDATION_WORK_TYPES.has(type));
+  const invalidTypes = normalizedTypes.filter(type => !LIVE_VALIDATION_WORK_TYPES.has(type));
+  let error = null;
+  if (invalidTypes.length > 0) {
+    const accepted = [...LIVE_VALIDATION_WORK_TYPES].sort().join(', ');
+    error = `Invalid liveValidation type(s): ${invalidTypes.join(', ')}. Accepted values: ${accepted}.`;
+  }
+  if (!error && Object.prototype.hasOwnProperty.call(value, 'autoDispatch')) {
+    if (typeof value.autoDispatch !== 'boolean') {
+      error = 'Invalid liveValidation: "autoDispatch" must be a boolean.';
+    } else if (value.autoDispatch && !normalizedTypes.includes(WORK_TYPE.TEST)) {
+      error = 'Invalid liveValidation: autoDispatch requires "test" in liveValidation.type so the generated validation work item runs on the live checkout.';
+    }
+  }
+  return {
+    configured: true,
+    types,
+    normalizedType: Array.isArray(rawType) ? normalizedTypes : normalizedTypes[0],
+    error,
+  };
+}
+
+// Return the canonical, live-capable work-item types configured for a hybrid
+// project. Raw config is read defensively because config.json can predate the
+// validator; invalid entries are ignored rather than turning hybrid into full
+// live mode. `build-and-test` is retained as a read-compat alias for `test`.
+function resolveLiveValidationTypes(project) {
+  return inspectLiveValidation(project && project.liveValidation).types;
+}
+
+function isLiveValidationConfigInvalid(project) {
+  const inspection = inspectLiveValidation(project && project.liveValidation);
+  return inspection.configured && !!inspection.error;
+}
 
 // Resolve a project's effective checkout mode, honoring the legacy
 // `worktreeMode` field for back-compat. Reading order:
@@ -2867,37 +2566,37 @@ const CHECKOUT_MODES = Object.freeze({ WORKTREE: 'worktree', LIVE: 'live' });
 //
 // Optional second argument `workItemType` enables liveValidation routing:
 //   If checkoutMode === 'live' AND project.liveValidation is set:
-//     - workItemType matches liveValidation.type → 'live' (validation serialized)
-//     - otherwise → 'worktree' (coding escapes the live cap)
+//     - workItemType matches liveValidation.type → 'live'
+//     - otherwise → 'worktree'
 //   liveValidation without checkoutMode: 'live' is ignored with a warn log.
 function resolveCheckoutMode(project, workItemType) {
   if (!project || typeof project !== 'object') return CHECKOUT_MODES.WORKTREE;
   const canonical = project.checkoutMode;
+  const legacy = project.worktreeMode;
+  let effectiveMode = CHECKOUT_MODES.WORKTREE;
+  if (canonical === CHECKOUT_MODES.LIVE || canonical === CHECKOUT_MODES.WORKTREE) {
+    effectiveMode = canonical;
+  } else if (legacy === 'live') {
+    effectiveMode = CHECKOUT_MODES.LIVE;
+  }
   // liveValidation without checkoutMode: 'live' is a misconfiguration — warn and ignore.
-  if (project.liveValidation && canonical !== CHECKOUT_MODES.LIVE) {
+  if (project.liveValidation && effectiveMode !== CHECKOUT_MODES.LIVE) {
     log('warn', 'resolveCheckoutMode: liveValidation is set but checkoutMode is not "live" — liveValidation ignored',
       { projectName: project.name });
   }
-  if (canonical === CHECKOUT_MODES.LIVE) {
+  if (effectiveMode === CHECKOUT_MODES.LIVE) {
     // Apply liveValidation routing when the block is present and workItemType is provided.
     // liveValidation.type may be a single string (legacy / back-compat) or an
     // array of strings (W-mr2m1ute000a9c01, multi-select hybrid types) —
     // normalize to an array and do a membership check so either shape works.
     if (project.liveValidation && workItemType !== undefined) {
-      const lvTypes = Array.isArray(project.liveValidation.type)
-        ? project.liveValidation.type
-        : [project.liveValidation.type];
-      return lvTypes.includes(workItemType)
+      const lvTypes = resolveLiveValidationTypes(project);
+      return lvTypes.includes(normalizeLiveValidationWorkType(workItemType))
         ? CHECKOUT_MODES.LIVE
         : CHECKOUT_MODES.WORKTREE;
     }
     return CHECKOUT_MODES.LIVE;
   }
-  if (canonical === CHECKOUT_MODES.WORKTREE) return CHECKOUT_MODES.WORKTREE;
-  // Legacy field fallback (only consulted when checkoutMode is absent/unknown).
-  const legacy = project.worktreeMode;
-  if (legacy === 'live') return CHECKOUT_MODES.LIVE;
-  // legacy 'isolated' (and anything else) → the default worktree behavior.
   return CHECKOUT_MODES.WORKTREE;
 }
 
@@ -2913,9 +2612,10 @@ function isLiveCheckoutProject(project) {
 // anything else (undefined / null / string) is treated as unset so the next
 // tier (or the `false` default) decides. When ON and a live-checkout tree is
 // dirty, `engine/live-checkout.js#prepareLiveCheckout` runs
-// `git fetch origin` + `git reset --hard origin/<branch>` instead of refusing
-// with LIVE_CHECKOUT_DIRTY (the reset DISCARDS the operator's uncommitted work,
-// so it is opt-in). Sibling of `resolveCheckoutMode` — pure, no I/O.
+// `git reset --hard HEAD` + `git clean -fd` instead of refusing with
+// LIVE_CHECKOUT_DIRTY. This discards uncommitted tracked and untracked work but
+// preserves the current branch and committed history, so it is opt-in. Sibling
+// of `resolveCheckoutMode` — pure, no I/O.
 function resolveLiveCheckoutAutoReset(project, engine) {
   if (project && typeof project === 'object' && typeof project.liveCheckoutAutoReset === 'boolean') {
     return project.liveCheckoutAutoReset;
@@ -2980,16 +2680,14 @@ function validateCheckoutMode(value) {
 }
 
 // Validate + normalize a per-project `liveValidation` block (hybrid mode).
-// Hybrid = checkoutMode:'live' + liveValidation:{ type, autoDispatch }: coding
-// work items author in isolated worktrees (escaping the live cap) while only
-// work items whose type is IN liveValidation.type run in-place on the live
-// checkout. See resolveCheckoutMode (which routes per work-item type) and
-// docs/live-checkout-mode.md.
+// Hybrid = checkoutMode:'live' + liveValidation:{ type, autoDispatch }: only
+// work items whose type is IN liveValidation.type run in-place; all other types
+// use isolated worktrees. See resolveCheckoutMode and docs/live-checkout-mode.md.
 //
 // `type` may be a single work-item-type string (legacy / back-compat) OR a
 // non-empty array of non-empty-string work-item types
 // (W-mr2m1ute000a9c01 — multi-select hybrid types, e.g. both "implement" and
-// "fix" validate live while other types stay in worktrees). Every reader of
+// "fix" run live while other types stay in worktrees). Every reader of
 // liveValidation.type (resolveCheckoutMode, lifecycle.autoDispatchLiveValidationWi,
 // dashboard project mapper / pill / CC label) must handle BOTH shapes —
 // existing config.json entries with a plain string `type` continue to work
@@ -2998,10 +2696,8 @@ function validateCheckoutMode(value) {
 // Returns:
 //   - undefined → caller should clear the field (empty / null / '' input)
 //   - { type, autoDispatch? } normalized object on success, where `type` is
-//     whatever shape the caller passed in (string stays a string; array stays
-//     a deduped array) — we intentionally do NOT force single-string input
-//     into an array so already-persisted single-type configs round-trip
-//     byte-identical through a Settings save that doesn't touch this field.
+//     the caller's input shape (string stays a string; array stays an array),
+//     with values trimmed, normalized, and deduplicated.
 // Throws HTTP 400 (via _httpError) on malformed input, or when the effective
 // checkout mode is not 'live' (liveValidation is meaningless without it — it is
 // silently ignored at resolve time, so we refuse to persist a misconfiguration).
@@ -3011,45 +2707,15 @@ function validateCheckoutMode(value) {
 // applied so the gate sees the intended final mode.
 function validateLiveValidation(value, opts) {
   if (value === undefined || value === null || value === '') return undefined;
-  if (typeof value !== 'object' || Array.isArray(value)) {
-    throw _httpError(400, 'Invalid liveValidation: must be an object { type, autoDispatch }.');
-  }
+  const inspection = inspectLiveValidation(value);
+  if (inspection.error) throw _httpError(400, inspection.error);
   const checkoutMode = opts && opts.checkoutMode;
   if (checkoutMode !== CHECKOUT_MODES.LIVE) {
     throw _httpError(400, 'liveValidation requires checkoutMode "live" (hybrid mode). Set checkoutMode to "live" first, or clear liveValidation.');
   }
-  const typeErrorMsg = 'Invalid liveValidation: "type" is required and must be a non-empty string, or a non-empty array of non-empty-string work-item types — the work-item type(s) that run on the live checkout (e.g. "build-and-test" or ["implement", "fix"]).';
-  const rawType = value.type;
-  let out;
-  if (typeof rawType === 'string') {
-    const trimmed = rawType.trim();
-    if (!trimmed) throw _httpError(400, typeErrorMsg);
-    out = { type: trimmed };
-  } else if (Array.isArray(rawType)) {
-    if (!rawType.every(t => typeof t === 'string' && t.trim().length > 0)) {
-      throw _httpError(400, typeErrorMsg);
-    }
-    // Dedupe (preserving first-seen order) and cap at the number of distinct
-    // work-item types the engine recognizes — a longer array can only be
-    // full of duplicates or invented types.
-    const deduped = [...new Set(rawType.map(t => t.trim()))];
-    if (deduped.length === 0) throw _httpError(400, typeErrorMsg);
-    if (deduped.length > VALID_WORK_TYPES.size) {
-      throw _httpError(400, `Invalid liveValidation: "type" array has ${deduped.length} entries, more than the ${VALID_WORK_TYPES.size} distinct work-item types the engine recognizes — remove duplicates or invalid types.`);
-    }
-    out = { type: deduped };
-  } else {
-    throw _httpError(400, typeErrorMsg);
-  }
-  // autoDispatch (optional): when true, lifecycle auto-creates a SINGLE
-  // validation WI after each coding WI completes with a PR
-  // (engine/lifecycle.js autoDispatchLiveValidationWi). Even when `type` is a
-  // multi-entry array (which drives checkout ROUTING — the types that run live),
-  // exactly one validation WI is filed, of the canonical `test` type when
-  // configured else the first configured live type. Coerce to a strict
-  // boolean; absent leaves it off so the operator opts in explicitly.
+  const out = { type: inspection.normalizedType };
   if (Object.prototype.hasOwnProperty.call(value, 'autoDispatch')) {
-    out.autoDispatch = !!value.autoDispatch;
+    out.autoDispatch = value.autoDispatch;
   }
   return out;
 }
@@ -3351,8 +3017,8 @@ const ENGINE_DEFAULTS = {
   // shared.resolvePollFlag is intentionally NOT used here because no
   // legacy macro bundle ever covered these phases.
   prDiscoveryEnabled: true,             // discoverFromPrs (per-project PR-driven fix/review/test discovery)
-  workItemsDiscoveryEnabled: true,      // discoverFromWorkItems (per-project work-items.json scan)
-  centralWorkDiscoveryEnabled: true,    // discoverCentralWorkItems (top-level work-items.json scan)
+  workItemsDiscoveryEnabled: true,      // discoverFromWorkItems (project SQL scope)
+  centralWorkDiscoveryEnabled: true,    // discoverCentralWorkItems (central SQL scope)
   scheduledWorkDiscoveryEnabled: true,  // discoverScheduledWork (cron-style scheduled tasks + meetings)
   planMaterializationEnabled: true,     // reconcilePrdStatuses + materializePlansAsWorkItems pair
   prPollStatusEvery: 72,   // poll PR build/review/merge status every N ticks for both ADO and GitHub (~12 min at default 10s tick)
@@ -3394,8 +3060,8 @@ const ENGINE_DEFAULTS = {
   prAbandonConfirmCount: 3,
   // W-mp60tw0u000j3931: One-shot startup reconciliation pass for `abandoned` PRs runs
   // exactly once per bump of this constant. The engine compares this value against
-  // engine/state.json:lastAbandonedReconciliationVersion at boot; if the on-disk version
-  // is lower, every project's pull-requests.json is scanned, every abandoned PR is
+  // the persisted lastAbandonedReconciliationVersion at boot; if the version
+  // is lower, every project's PR scope is scanned, every abandoned PR is
   // re-probed, and any false-flipped PRs (e.g. transient 404 victims from before the
   // hardening in W-mp5trwh60008386d shipped) are flipped back to active/merged/closed
   // based on their live API state. Bump this when reconciliation logic itself changes
@@ -3459,7 +3125,7 @@ const ENGINE_DEFAULTS = {
   // re-queued into review again.
   preDispatchEvalMaxRejections: 5,
   completionNonceRequired: false, // P-d2a8f6c1 (agent trust boundary F8): when true, a missing `nonce` field in the completion JSON hard-fails the dispatch with failure_class:'completion-nonce-mismatch'. Default false for one release so older agents/runtime caches that haven't picked up the prompt change degrade with a warning instead of breaking. Mismatched nonces hard-fail regardless of this flag. See docs/completion-reports.md → "Trust boundary".
-  autoApplyReviewVote: false, // W-mpea9fyb0010febf / P-f7splitgate: master gate for ALL engine platform vote mutations. When true, the engine (a) mirrors live platform vote state into local pull-requests.json reviewStatus, (b) re-applies its own ADO +10 approval when ADO resets votes on target-branch advance (pollPrStatus), (c) reconciles its own prior negative on a verdict flip to APPROVE (ADO resetReviewerNegativeVote / GitHub dismissPriorViewerChangesRequestedReviews), and (d) instructs ADO review agents to cast `az repos pr set-vote`. When false (default), the verdict is recorded in pull-requests.json reviewStatus from the agent's completion ONLY — informational — and Minions never cast, re-cast, or clear a platform vote/review (ADO agents post the verdict as a comment only, parity with GitHub self-approval block).
+  autoApplyReviewVote: false, // Master gate for platform vote mutations; local verdicts remain informational when false.
 
   // ── Runtime fleet (P-3b8e5f1d) ──────────────────────────────────────────────
   // Single source of truth for which CLI runtime + model every spawn uses.
@@ -3473,7 +3139,7 @@ const ENGINE_DEFAULTS = {
   claudeBareMode: false,         // Claude --bare: suppress CLAUDE.md auto-discovery (per-agent override: agents.<id>.bareMode)
   claudeFallbackModel: undefined,// Claude --fallback-model — Claude CLI honors this on rate-limit (429) only; engine retry on FAILURE_CLASS.MODEL_UNAVAILABLE keeps the flag passed so the CLI can swap internally
   copilotFallbackModel: undefined,// W-mpg6isvy000xca4d: Copilot has no --fallback-model flag; engine retry on FAILURE_CLASS.MODEL_UNAVAILABLE OVERRIDES --model directly with this value (separate knob from claudeFallbackModel because model namespaces differ across runtimes)
-  copilotDisableBuiltinMcps: true,   // Copilot --disable-builtin-mcps: keep github-mcp-server out so it can't bypass pull-requests.json tracking
+  copilotDisableBuiltinMcps: true,   // Keep github-mcp-server from bypassing Minions PR tracking.
   // P-7d31a06b — Claude pre-approves workspace .mcp.json servers in ~/.claude.json on every spawn into a fresh
   // worktree cwd. Without this, the first Claude invocation in a brand-new worktree shows a project-scoped MCP
   // "trust this server?" prompt that blocks until a human accepts — invisible behind --dangerously-skip-permissions
@@ -3489,13 +3155,6 @@ const ENGINE_DEFAULTS = {
   agentUseWorkerPool: false,         // P-9b3d5f61: mirrors ccUseWorkerPool's shape but for the fleet agent-dispatch path (engine/agent-worker-pool.js). Opt-in, default OFF — see resolveAgentUseWorkerPool in engine/shared.js for the full priority chain and rationale.
   maxBudgetUsd: undefined,       // fleet USD ceiling for --max-budget-usd (per-agent override: agents.<id>.maxBudgetUsd). Honors 0 via ?? so a literal cap of $0 works
   disableModelDiscovery: false,  // skip runtime.listModels() REST calls fleet-wide (settings UI falls back to free-text)
-  // Phase 8 (qa-runs.json + qa-sessions.json → SQL). When true, every QA
-  // mutation also writes the JSON sidecar at engine/qa-runs.json and
-  // engine/qa-sessions.json for back-compat with external tooling. SQL is
-  // always the source of truth — flip this OFF once operators trust the
-  // SQL store and want to drop the dual-write cost. Sunset tracked in
-  // docs/deprecated.json (qa-json-sidecars).
-  qaDualWriteJson: true,
   // W-mpmwxkrw000872ec — dashboard global font-size scale. Drives the
   // [data-font-size] attribute on <html> via the inline bootstrap script in
   // layout.html (localStorage fast path) and is reconciled from the server
@@ -3503,10 +3162,9 @@ const ENGINE_DEFAULTS = {
   // 'xlarge'. Allowlist validation lives in handleSettingsUpdate so invalid
   // values are clamped rather than silently breaking the bootstrap.
   fontSize: 'small',
-  maxPendingContexts: 20, // cap pendingContexts arrays in cooldowns.json to prevent unbounded growth
-  maxPendingContextEntryBytes: 256 * 1024, // 256 KB — cap each pendingContexts entry to prevent huge PR comments from bloating cooldowns.json
-  maxDispatchPromptBytes: 1024 * 1024, // 1 MB — dispatch items with prompts larger than this sidecar to engine/contexts/ to prevent dispatch.json OOM (#1167)
-  maxStateFileBytes: 100 * 1024 * 1024, // 100 MB — fail startup with a clear error when dispatch.json / cooldowns.json exceed this, rather than silently OOMing on JSON.parse (#1167)
+  maxPendingContexts: 20, // cap pendingContexts arrays to prevent unbounded growth
+  maxPendingContextEntryBytes: 256 * 1024, // cap each pending context entry
+  maxDispatchPromptBytes: 1024 * 1024, // sidecar oversized prompts under engine/contexts/
   mainBranchCacheTtlMs: 300000, // 5min — cache git default-branch detection, then prune expired entries
   mainBranchCacheMaxEntries: 100, // bound repo/branch detection cache in long-lived dashboard/engine processes
   removeWorktreeFailureTtlMs: 24 * 60 * 60 * 1000, // stale failed paths are forgotten after a day
@@ -3565,7 +3223,7 @@ const ENGINE_DEFAULTS = {
   ccTurnTimeoutMs: 300000, // W-mpmwxni2000c25c7-b/-d: 5min per-turn no-progress watchdog. The window resets on every liveness signal — token chunk, tool-call notification, tool-update — so an actively-streaming CC/doc-chat turn (long shell command, deep search, sub-agent loop) survives indefinitely up to the outer CC_CALL_TIMEOUT_MS (~1h) ceiling. Only true silence past this window with no progress fires the cancel: the in-flight LLM call is aborted and the handler surfaces `{code:'cc-turn-timeout', retryable:true}` via the typed error envelope so the UI can stop the spinner and offer Retry. Clamped to [10000, 3600000] in the settings POST handler. Independent of CC_CALL_TIMEOUT_MS. Non-streaming doc-chat is the lone wall-clock exception (no progress hooks); see _raceCcDocChatTimeout in dashboard.js for the dual factory/promise shape.
   docSessionMaxEntries: 200, // cap doc-chat session map/disk store by least-recent activity (LRU; sessions are non-expiring otherwise)
   ccLiveStreamMaxAgeMs: 30 * 60 * 1000, // hard cap reconnect buffers if abort/cleanup stalls
-  metricsFlushIntervalMs: 10000, // batch trackEngineUsage writes to metrics.json — flushed every 10s instead of per-call to cut lock contention and dashboard mtime churn
+  metricsFlushIntervalMs: 10000, // batch trackEngineUsage SQL writes
   maxLlmRawBytes: 256 * 1024, // keep only a bounded stdout tail from direct Claude calls
   maxLlmStderrBytes: 64 * 1024, // keep only a bounded stderr tail from direct Claude calls
   maxLlmLineBufferBytes: 128 * 1024, // cap the incremental JSON line buffer to avoid malformed-stream OOMs
@@ -4285,6 +3943,15 @@ const WORK_TYPE = {
   BUILD_FIX_COMPLEX: 'build-fix-complex',
 };
 
+const FIX_LIKE_WORK_TYPES = new Set([
+  WORK_TYPE.FIX,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
+]);
+
+function isFixLikeWorkType(type) {
+  return FIX_LIKE_WORK_TYPES.has(type);
+}
+
 // Work types whose dispatch path requires a per-project git worktree. The
 // engine's spawnAgent uses the project's `localPath` as the worktree root —
 // without an owning project the rootDir falls back to MINIONS_DIR's parent,
@@ -4323,6 +3990,21 @@ const WORKTREE_REQUIRING_TYPES = new Set([
   WORK_TYPE.DOCS,
 ]);
 
+// Hybrid routing is meaningful only for work types that would otherwise need
+// an isolated project worktree. Read-only root tasks already run from the
+// project/root path and therefore gain nothing from a live-validation entry.
+const LIVE_VALIDATION_WORK_TYPES = new Set(WORKTREE_REQUIRING_TYPES);
+
+function resolveLiveValidationAutoDispatchType(project) {
+  if (!project?.liveValidation || project.liveValidation.autoDispatch !== true) return null;
+  if (resolveCheckoutMode(project) !== CHECKOUT_MODES.LIVE) return null;
+  const inspection = inspectLiveValidation(project.liveValidation);
+  if (inspection.error) return null;
+  return inspection.types.includes(WORK_TYPE.TEST)
+    ? WORK_TYPE.TEST
+    : null;
+}
+
 // W-mpxqkkn300121d21 — Valid `type` strings the materializer will honor when a
 // PRD missing_feature carries one. Excludes orchestration-only types that the
 // plan→PRD→materializer pipeline never produces (PLAN, PLAN_TO_PRD, MEETING)
@@ -4402,7 +4084,7 @@ const PR_PENDING_REASON = {
   MISSING_BRANCH: 'missing_pr_branch',
 };
 // PR build-status enum — single source of truth for the literal strings written to
-// pull-requests.json `buildStatus`. Previously drifted across engine/ado.js,
+// PR `buildStatus`. Previously drifted across engine/ado.js,
 // engine/github.js, engine/lifecycle.js, engine/watches.js, engine/queries.js, engine/cli.js
 // (P-bfa3d-constants-eslint, audit items #68-#82).
 const BUILD_STATUS = {
@@ -4412,7 +4094,7 @@ const BUILD_STATUS = {
   NONE: 'none',
 };
 // PR review-status enum — single source of truth for the literal strings written to
-// pull-requests.json `reviewStatus`. Previously drifted across engine/ado.js,
+// PR `reviewStatus`. Previously drifted across engine/ado.js,
 // engine/github.js, engine/lifecycle.js, engine/watches.js, engine/queries.js, engine/cli.js
 // (P-bfa3d-constants-eslint, audit items #68-#82).
 const REVIEW_STATUS = {
@@ -4666,14 +4348,10 @@ function trackReviewMetric(pr, newReviewStatus, config) {
  * just a boolean caused the toast to render "queued undefined" (issue #2375).
  */
 function queuePlanToPrd({ planFile, prdFile, title, description, project, createdBy, extra }) {
-  // Use MINIONS_DIR (honors MINIONS_TEST_DIR override) instead of resolving from
-  // __dirname — otherwise tests that exercise this helper leak work items into
-  // the real package-root work-items.json even after createTestMinionsDir().
-  const centralWiPath = path.join(MINIONS_DIR, 'work-items.json');
   let queued = false;
   let id = null;
   let item = null;
-  mutateJsonFileLocked(centralWiPath, items => {
+  mutateWorkItems('central', items => {
     if (!Array.isArray(items)) items = [];
     const existing = items.find(w => w.type === WORK_TYPE.PLAN_TO_PRD && w.planFile === planFile && (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.DISPATCHED));
     if (existing) {
@@ -4820,7 +4498,7 @@ const FAILURE_CLASS = {
   WORKSPACE_MANIFEST_URL: 'workspace-manifest-url-forbidden',   // W-mq07avbk000m5543: out-of-scope external URL fetch. Non-retryable as-is.
   SPAWN_PHASE_STALL: 'spawn-phase-stall', // W-mq0e2dae000a003d: process spawned and ran startup-only events (MCP init / hooks) but never emitted real task progress; CPU usage stayed below threshold past the grace window. Engine kills the wedged child and treats this as retryable (fresh-session) so a re-spawn can clear a transient MCP wedge.
   OUTPUT_TRUNCATED: 'output-truncated',   // P-8e4c2a17: the agent streamed more stdout than the engine's hard capture cap (engine.js AGENT_OUTPUT_CAP_BYTES, 1MB) BEFORE the terminal `result` event arrived. The result (session id, completion block, final text) lives at the END of the stream, so it fell outside the captured window and parseOutput found nothing — the dispatch would otherwise fail as an opaque UNKNOWN and retry to death. Surfaced loudly with an actionable message; non-retryable (mechanical retry just reproduces the overflow — the agent must reduce output volume or the task must be split).
-  VERIFY_MISSING_PR: 'verify-missing-pr', // W-mqsk1ip00006cbae: a verify WI exited done but no PR was attached (neither _prUrl/_pr on the item nor a matching pull-requests.json entry for the plan). Flipped to failed so the plan doesn't silently advance without an E2E PR. Retryable — agent may have phantom-crashed before pushing the branch.
+  VERIFY_MISSING_PR: 'verify-missing-pr', // Verify completed without an attached or tracked PR.
   PROJECT_NOT_FOUND: 'project_not_found', // W-mqv2wsy30002e090: a work item's `project` field names a project that is not configured (resolveConfiguredProject / formatUnknownProjectError → `Project "<name>" not found. Known projects: …`). Stamped at discovery time so the dashboard PR-column renderer surfaces the red failReason snippet like other non-retryable failures instead of burying it in the Agent column. Non-retryable — operator must fix the WI's project field or configure the project.
   PRE_DISPATCH_EVAL_STUCK: 'pre-dispatch-eval-stuck', // W-mrcrh5hj0017d22f: pre-dispatch-eval rejected the SAME (unchanged) description ENGINE_DEFAULTS.preDispatchEvalMaxRejections times in a row without the WI status ever leaving pending — previously this burned an LLM validation call every discovery tick forever with nothing surfaced to the dashboard (constant-bug-bash's file-fixes stage wedged 16+ consecutive rejections, one/minute, until a human manually cancelled it). Engine now flips the WI to failed with this class so the stalled item is visible and stops silently re-evaluating; non-retryable until the description changes.
   UNKNOWN: 'unknown',                     // Unclassified failure
@@ -4857,9 +4535,8 @@ const DEFAULT_CLAUDE = {
 // engine/cleanup.js:1200-1213 _engine.legacyStatusMigrations.
 function _bumpPruneDefaultClaudeStrip() {
   try {
-    const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
     const dateKey = new Date().toISOString().slice(0, 10);
-    mutateJsonFileLocked(metricsPath, (metrics) => {
+    mutateMetrics((metrics) => {
       metrics = metrics || {};
       if (!metrics._engine) metrics._engine = {};
       if (!metrics._engine.pruneDefaultClaudeConfigStrips) metrics._engine.pruneDefaultClaudeConfigStrips = {};
@@ -5168,18 +4845,9 @@ function resolveConfiguredProject(projectName, projectsOrConfig, options = {}) {
   return { project: null, explicit: false, value: '' };
 }
 
-function centralWorkItemsPath(minionsDir = MINIONS_DIR) {
-  return path.join(minionsDir, 'work-items.json');
-}
-
-function centralPullRequestsPath(minionsDir = MINIONS_DIR) {
-  return path.join(minionsDir, 'pull-requests.json');
-}
-
 function _projectSourceRawValue(source) {
   if (source && typeof source === 'object') {
     return source.name ?? source.project ?? source._project ?? source.source ?? source._source ??
-      source.wiPath ?? source.workItemsPath ?? source.prPath ?? source.pullRequestsPath ??
       source.stateDir ?? source.path ?? source.localPath ?? '';
   }
   return source;
@@ -5193,18 +4861,15 @@ function _sameSourcePath(value, targetPath, minionsDir = MINIONS_DIR) {
 }
 
 function _projectSourceDescriptor(project, value, explicit, minionsDir = MINIONS_DIR) {
-  const wiPath = project ? projectWorkItemsPath(project) : centralWorkItemsPath(minionsDir);
-  const prPath = project ? projectPrPath(project) : centralPullRequestsPath(minionsDir);
   const stateDir = project ? projectStateDir(project) : minionsDir;
   return {
     project: project || null,
     explicit: !!explicit,
     value: value || '',
     sourceName: project?.name || 'central',
+    scope: project?.name || 'central',
     isCentral: !project,
     stateDir,
-    wiPath,
-    prPath,
   };
 }
 
@@ -5221,17 +4886,13 @@ function resolveProjectSource(source, projectsOrConfig, options = {}) {
       return _projectSourceDescriptor(projects[0], '', false, minionsDir);
     }
     if (allowCentral) return _projectSourceDescriptor(null, '', false, minionsDir);
-    return { project: null, explicit: false, value: '', sourceName: '', isCentral: false, wiPath: null, prPath: null, stateDir: null };
+    return { project: null, explicit: false, value: '', sourceName: '', isCentral: false, scope: null, stateDir: null };
   }
 
-  const centralWorkPath = centralWorkItemsPath(minionsDir);
-  const centralPrPath = centralPullRequestsPath(minionsDir);
   const centralNames = new Set(['central', 'root']);
   const lowerValue = value.toLowerCase();
   const isCentral = centralNames.has(lowerValue) ||
-    _sameSourcePath(value, minionsDir, minionsDir) ||
-    _sameSourcePath(value, centralWorkPath, minionsDir) ||
-    _sameSourcePath(value, centralPrPath, minionsDir);
+    _sameSourcePath(value, minionsDir, minionsDir);
   if (isCentral) {
     if (allowCentral) return _projectSourceDescriptor(null, value, true, minionsDir);
     return {
@@ -5240,8 +4901,7 @@ function resolveProjectSource(source, projectsOrConfig, options = {}) {
       value,
       sourceName: '',
       isCentral: false,
-      wiPath: null,
-      prPath: null,
+      scope: null,
       stateDir: null,
       error: 'central source is not allowed here',
     };
@@ -5255,8 +4915,6 @@ function resolveProjectSource(source, projectsOrConfig, options = {}) {
     const candidates = [
       project.localPath,
       projectStateDir(project),
-      projectWorkItemsPath(project),
-      projectPrPath(project),
     ].filter(Boolean);
     if (candidates.some(candidate => _sameSourcePath(value, candidate, minionsDir))) {
       return _projectSourceDescriptor(project, value, explicit, minionsDir);
@@ -5269,8 +4927,7 @@ function resolveProjectSource(source, projectsOrConfig, options = {}) {
     value,
     sourceName: '',
     isCentral: false,
-    wiPath: null,
-    prPath: null,
+    scope: null,
     stateDir: null,
     error: formatUnknownProjectError(value, projects),
   };
@@ -5280,15 +4937,8 @@ function projectRoot(project) {
   return path.resolve(project.localPath);
 }
 
-// All project state files live centrally in .minions/projects/{name}/
-// No state files in project repos — avoids worktree/git interference.
-//
-// projectStateDir is path-only (no fs side effects) — safe to call with stale
-// project references after `removeProject` archived the data dir. Write paths
-// (safeWrite, withFileLock, mutateJsonFileLocked) already mkdir the parent dir
-// at write time, so the dir is created lazily only when something is actually
-// written. Use projectStateDirEnsure() when a caller specifically needs the
-// directory to exist before doing its own fs ops.
+// Project-local definitions and artifacts live under projects/{name}/.
+// Runtime records use the project's SQL scope.
 function projectStateDir(project) {
   const name = project.name || path.basename(project.localPath);
   return path.join(MINIONS_DIR, 'projects', name);
@@ -5302,14 +4952,6 @@ function projectStateDirEnsure(project) {
   return dir;
 }
 
-function projectWorkItemsPath(project) {
-  return path.join(projectStateDir(project), 'work-items.json');
-}
-
-function projectPrPath(project) {
-  return path.join(projectStateDir(project), 'pull-requests.json');
-}
-
 function sameResolvedPath(a, b) {
   if (!a || !b) return false;
   try {
@@ -5321,7 +4963,7 @@ function sameResolvedPath(a, b) {
   }
 }
 
-function ensureProjectStateFiles(project) {
+function initializeProjectState(project) {
   const result = { created: [] };
   projectStateDirEnsure(project);
   // SQL scopes need no empty sentinel rows. Touch both stores so migrations
@@ -5355,33 +4997,6 @@ function realPathForComparison(filePath) {
   }
 }
 
-function prPathComparisonCandidates(filePath) {
-  const candidates = new Set();
-  const addCandidate = (candidate) => {
-    const resolved = path.resolve(candidate);
-    candidates.add(resolved);
-    candidates.add(realPathForComparison(resolved));
-  };
-
-  addCandidate(filePath);
-  if (!path.isAbsolute(filePath)) {
-    addCandidate(path.resolve(MINIONS_DIR, filePath));
-  }
-  return candidates;
-}
-
-function resolveProjectForPrPath(filePath, config = null) {
-  const fileCandidates = prPathComparisonCandidates(filePath);
-  const projects = getProjects(config);
-  for (const project of projects) {
-    for (const projectPath of prPathComparisonCandidates(projectPrPath(project))) {
-      if (fileCandidates.has(projectPath)) return project;
-    }
-  }
-  if (projects.length === 1) return projects[0];
-  return null;
-}
-
 // ── ID Generation ────────────────────────────────────────────────────────────
 
 function nextWorkItemId(items, prefix) {
@@ -5421,7 +5036,7 @@ function getAdoOrgBase(project) {
  *
  *   - "basenames": exact relative paths under the live root (engine.js, dashboard.js,
  *     minions.js, config.json — and the runtime state files engine/control.json
- *     and engine/dispatch.json).
+ *     and engine/control.json).
  *   - "globs":     direct-child JS files under protected live directories
  *     (engine/*.js, bin/*.js).
  *   - "prefixes":  relative directory prefixes whose entire subtree is read-only
@@ -5443,7 +5058,6 @@ const _CC_PROTECTED_BASENAMES = Object.freeze([
   'minions.js',
   'config.json',
   'engine/control.json',
-  'engine/dispatch.json',
 ]);
 const _CC_PROTECTED_FILE_GLOBS = Object.freeze([
   'engine/*.js',
@@ -6581,8 +6195,8 @@ function extractStructuredWorkItemPrRef(item) {
 // W-mq1j85cj00055a8f — when an inbox note (notes/inbox/<name>) leaves the
 // inbox (persisted to notes.md, promoted to knowledge/, or auto-archived by
 // consolidation), any work-item reference pointing at the old inbox path
-// turns into a broken link. Rewrite those references across every project's
-// work-items.json + the central one to the new canonical location.
+// turns into a broken link. Rewrite those references across every work-item
+// scope to the new canonical location.
 //
 // Match semantics (intentionally narrow per the WI scope):
 //   - item.references[]: string 'notes/inbox/<inboxName>' (anchored on start
@@ -6600,15 +6214,14 @@ function extractStructuredWorkItemPrRef(item) {
 //   - Trailing `?query` or `#fragment` is tolerated; substring overlaps in
 //     unrelated path segments (e.g. .../notes/inbox/foobar for foo.md) are
 //     NOT rewritten.
-//   - Archived work-items files are skipped — only live work-items.json paths
-//     surfaced by getProjects() + the central path are touched.
+//   - Archived work items are skipped.
 //
 // Idempotent: re-running with the same inboxName after the rewrite is a
 // no-op (the references already read newLocation, which won't match the
 // notes/inbox/<inboxName> regex).
 //
-// Returns the count of references rewritten across all files (for logging).
-// Each file's mutate is wrapped in try/catch so one corrupt project can't
+// Returns the count of references rewritten across all scopes (for logging).
+// Each scope's mutate is wrapped in try/catch so one corrupt project can't
 // block the others.
 //
 // `opts._mutate` is an undocumented test seam — production callers always
@@ -6645,14 +6258,14 @@ function rewriteInboxRefsAcrossProjects(inboxName, newLocation, opts = {}) {
   const candidates = [];
   try {
     for (const project of getProjects(config)) {
-      try { candidates.push(projectWorkItemsPath(project)); } catch { /* skip bad project entry */ }
+      if (project?.name) candidates.push(project);
     }
   } catch { /* getProjects failed — fall back to central only */ }
-  candidates.push(centralWorkItemsPath());
+  candidates.push('central');
 
-  for (const wiPath of candidates) {
+  for (const scope of candidates) {
     try {
-      _mutate(wiPath, items => {
+      _mutate(scope, items => {
         if (!Array.isArray(items)) return items;
         for (const item of items) {
           if (!item) continue;
@@ -6709,7 +6322,7 @@ function rewriteInboxRefsAcrossProjects(inboxName, newLocation, opts = {}) {
         return items;
       });
     } catch (e) {
-      try { console.warn(`rewriteInboxRefsAcrossProjects(${wiPath}): ${e.message}`); } catch { /* logging best-effort */ }
+      try { console.warn(`rewriteInboxRefsAcrossProjects(${stateScope(scope)}): ${e.message}`); } catch { /* logging best-effort */ }
     }
   }
   return rewritten;
@@ -7347,18 +6960,14 @@ function addPrLink(prId, itemId, { project = null, url = '', prNumber = null } =
     links[effectivePrId] = [...mergedCurrent];
     return links;
   };
-  // Phase 9.4 + W-mpz7lbb600012d4f: pr-links is SQL-canonical via small-state-store;
-  // the JSON file is a write-only mirror. Route through mutateJsonFileLocked so
-  // _tryRouteMutateToSql serializes the SQL apply + JSON mirror under the same
-  // cross-process file lock every other small-state mutation uses.
-  mutateJsonFileLocked(PR_LINKS_PATH, mutator, { defaultValue: {} });
+  const { wrote } = require('./small-state-store').applyPrLinksMutation(mutator);
+  if (wrote) {
+    try { require('./db-events').emitStateEvent('pr_links'); } catch { /* optional */ }
+  }
 
   if (!project) return;
-  const prPath = projectPrPath(project);
   const effectivePrNumber = getPrNumber(prNumber ?? effectivePrId);
-  // Phase 9 SQL routing: mutatePullRequests writes through pull-requests-store
-  // so SQL stays canonical; the JSON mirror is regenerated by the store.
-  mutatePullRequests(prPath, (prs) => {
+  mutatePullRequests(project, (prs) => {
     if (!Array.isArray(prs) || prs.length === 0) return prs;
     normalizePrRecords(prs, project);
     const existingPr = prs.find(pr =>
@@ -7428,13 +7037,13 @@ function _mergeDuplicatePrInto(winner, loser) {
  *     • scalar fields: filled only when the winner's field is empty
  *     • prdItems: union-merged
  *
- * @param {string} prPath  Path to the pull-requests.json file.
+ * @param {object|string|null} source  Project, scope name, or central.
  * @param {{ project?: object|null }} opts  Optional project config for normalization.
  * @returns {{ collapsed: number }}  Number of duplicate records removed.
  */
-function collapseDuplicatePrRecords(prPath, { project = null } = {}) {
+function collapseDuplicatePrRecords(source, { project = null } = {}) {
   let collapsed = 0;
-  mutatePullRequests(prPath, (prs) => {
+  mutatePullRequests(source, (prs) => {
     normalizePrRecords(prs, project);
     // PR numbers are only unique within a repository. Grouping by number alone
     // merges unrelated GitHub/ADO repositories and can discard a tombstone.
@@ -7476,12 +7085,12 @@ function _clearPrTombstonesForIdentity(identity) {
       ? projectsByName.get(pr._scope) || null
       : null;
     if (getPrIdentityKey(pr, project) !== identity) continue;
-    const prPath = store._filePathForScope(pr._scope || 'central');
-    scopes.set(path.resolve(prPath), { prPath, project });
+    const scope = pr._scope || 'central';
+    scopes.set(scope, { scope, project });
   }
   let cleared = 0;
-  for (const { prPath, project } of scopes.values()) {
-    mutatePullRequests(prPath, (prs) => {
+  for (const { scope, project } of scopes.values()) {
+    mutatePullRequests(scope, (prs) => {
       for (const pr of prs) {
         if (pr?.userDeleted !== true || getPrIdentityKey(pr, project) !== identity) continue;
         delete pr.userDeleted;
@@ -7523,13 +7132,10 @@ function shouldAdoptPlatformCreated(storedCreated, platformCreated) {
 /**
  * Canonical PR-producing work contract helper.
  *
- * Dashboard rendering derives work-item PR columns from PR.prdItems (with
- * engine/pr-links.json as a compatibility fallback). Any path that discovers or
- * manually records a PR for a work item must use this helper so the PR record
- * and the canonical work-item attachment are created together and idempotently.
+ * Any path that discovers or manually records a PR for a work item must use
+ * this helper so the PR record and work-item attachment stay consistent.
  */
-function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null, itemIds = null, beforeInsert = null, allowResurrect = false } = {}) {
-  if (!prPath) throw new Error('prPath required');
+function upsertPullRequestRecord(source, entry, { project = null, itemId = null, itemIds = null, beforeInsert = null, allowResurrect = false } = {}) {
   if (!entry || typeof entry !== 'object') throw new Error('entry required');
 
   const linkedItemIds = normalizePrLinkItems([
@@ -7553,9 +7159,7 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
     prNumber: prNumber ?? entry.prNumber ?? null,
     prdItems: linkedItemIds,
   };
-  // Issue #348: backfill `project` from the project option when the entry
-  // doesn't carry one. The file path already encodes the project name (e.g.
-  // projects/<name>/pull-requests.json), so it is always deterministic.
+  // Backfill `project` from the resolved project when the entry omits it.
   // Without this, PRs linked via /api/pull-requests/link had project:null on
   // the record, which broke any downstream path that reads pr.project to
   // resolve the owning project.
@@ -7572,7 +7176,7 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
   let resurrected = allowResurrect && _clearPrTombstonesForIdentity(canonicalId) > 0;
   let record = null;
 
-  mutatePullRequests(prPath, (prs) => {
+  mutatePullRequests(source, (prs) => {
     normalizePrRecords(prs, project);
     const identityMatches = prs.filter(pr => getPrIdentityKey(pr, project) === canonicalId);
     let target = identityMatches.length > 0 ? _pickBestPrRecord(identityMatches) : null;
@@ -7736,7 +7340,7 @@ function classifyPrRefForVerification(prRef, project = null) {
   return null;
 }
 
-// W-mq5wfh1v000e0da9 — Auto-enroll a PR into pull-requests.json when a
+// W-mq5wfh1v000e0da9 — Auto-enroll a PR into tracked state when a
 // `type: fix` work item is created with a structured PR pointer. Without
 // this, fix WIs against untracked PRs bypass the polling / review / build
 // pipelines (the engine `pr_not_found` gate blocks dispatch entirely, and
@@ -7754,17 +7358,22 @@ function classifyPrRefForVerification(prRef, project = null) {
 //
 // Returns:
 //   { skipped: true, reason }            — not a pr-requiring type / no ref / no URL / upsert error
-//   { alreadyEnrolled: true, id }        — PR already in pull-requests.json
-//   { enrolled: true, id, prPath }       — newly enrolled
-const _PR_REQUIRING_TYPES = new Set([WORK_TYPE.FIX, WORK_TYPE.REVIEW, WORK_TYPE.TEST]);
+//   { alreadyEnrolled: true, id }        — PR already tracked
+//   { enrolled: true, id, scope }        — newly enrolled
+const _PR_REQUIRING_TYPES = new Set([
+  WORK_TYPE.FIX,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
+  WORK_TYPE.REVIEW,
+  WORK_TYPE.TEST,
+]);
 function autoEnrollPrFromWorkItem(item, project, minionsDir) {
   if (!item || !_PR_REQUIRING_TYPES.has(item.type)) return { skipped: true, reason: 'not-pr-requiring-type' };
   const prRef = extractStructuredWorkItemPrRef(item);
   if (!prRef) return { skipped: true, reason: 'no-structured-ref' };
   const url = deriveUrlForPrRef(prRef, project);
   if (!url) return { skipped: true, reason: 'no-url' };
-  const prPath = project ? projectPrPath(project) : centralPullRequestsPath(minionsDir);
-  const existing = safeJsonArr(prPath);
+  const source = project || 'central';
+  const existing = readPullRequests(source);
   if (findPrRecord(existing, prRef, project)) {
     return { alreadyEnrolled: true, id: getCanonicalPrId(project, prRef, url) };
   }
@@ -7772,7 +7381,7 @@ function autoEnrollPrFromWorkItem(item, project, minionsDir) {
   const prNum = parsedUrl ? parsedUrl.prNumber : null;
   const prId = getCanonicalPrId(project, prRef, url);
   try {
-    const result = upsertPullRequestRecord(prPath, {
+    const result = upsertPullRequestRecord(source, {
       id: prId,
       prNumber: prNum,
       title: `PR #${prNum != null ? prNum : '?'} (polling...)`,
@@ -7786,7 +7395,7 @@ function autoEnrollPrFromWorkItem(item, project, minionsDir) {
       contextOnly: false,
     }, { project, itemId: item.id });
     return result.created
-      ? { enrolled: true, id: result.id, prPath }
+      ? { enrolled: true, id: result.id, scope: stateScope(source) }
       : { alreadyEnrolled: true, id: result.id };
   } catch (e) {
     log('warn', `autoEnrollPrFromWorkItem ${item.id}: ${e.message}`);
@@ -7820,47 +7429,35 @@ function clearWorktreeFailureCache(wtPath) {
 
 // ─── Work Items & Pull Requests Mutation Helpers ────────────────────────────
 
-/**
- * Atomic read-modify-write for work-items JSON files.
- * Wraps mutateJsonFileLocked with defaultValue of [].
- * @param {string} filePath - Path to the work-items JSON file
- * @param {Function} mutator - Receives the array, mutates in place or returns new value
- */
-function mutateWorkItems(filePath, mutator) {
-  // Phase 9.4 SQL-only. Route through work-items-store; SQL is the canonical
-  // (and only) store. The legacy JSON path below remains ONLY for ad-hoc
-  // file paths outside the MINIONS_DIR layout (e.g. tests using
-  // createTmpDir()) that can't be mapped to a stable scope. Production
-  // callers always use shared.projectWorkItemsPath(p) / MINIONS_DIR/work-items.json.
-  const fpNorm = String(filePath).replace(/\\/g, '/');
-  const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
-  const insideMinionsDir = fpNorm.startsWith(minionsNorm + '/') || fpNorm === minionsNorm + '/work-items.json';
-  if (insideMinionsDir) {
-    const store = require('./work-items-store');
-    const scope = store.scopeForFilePath(filePath);
-    const { wrote, result } = store.applyWorkItemsMutation(scope, (items) => {
-      if (!Array.isArray(items)) items = [];
-      return mutator(items) || items;
-    });
-    if (wrote) {
-      try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
-      try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
-    }
-    return result;
+function stateScope(source) {
+  if (source == null || source === '') return 'central';
+  if (source && typeof source === 'object') {
+    if (source.isCentral) return 'central';
+    source = source.scope ?? source.name ?? source.project;
+  }
+  if (typeof source !== 'string') throw new TypeError('state scope requires a project, scope name, or null');
+  const scope = source.trim();
+  if (!scope || scope === 'central') return 'central';
+  if (/[\\/]/.test(scope) || /\.json$/i.test(scope)) {
+    throw new TypeError('state scope must be a project name, not a file path');
   }
+  return scope;
+}
 
-  const result = mutateJsonFileLocked(filePath, (data) => {
-    if (!Array.isArray(data)) data = [];
-    return mutator(data) || data;
-  }, {
-    defaultValue: [],
-    skipWriteIfUnchanged: true,
-    _skipSqlRouting: true,
-    onWrote: () => {
-      try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
-      try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
-    },
+function readWorkItems(source = null) {
+  return require('./work-items-store').readWorkItemsForScope(stateScope(source));
+}
+
+function mutateWorkItems(source, mutator) {
+  const store = require('./work-items-store');
+  const { wrote, result } = store.applyWorkItemsMutation(stateScope(source), (items) => {
+    if (!Array.isArray(items)) items = [];
+    return mutator(items) || items;
   });
+  if (wrote) {
+    try { require('./db-events').emitStateEvent('work_items'); } catch { /* optional */ }
+    try { require('./queries').invalidateWorkItemsCache(); } catch { /* queries not loaded */ }
+  }
   return result;
 }
 
@@ -7877,43 +7474,20 @@ function reopenWorkItem(wi) {
   wi._retryCount = 0;
 }
 
-/**
- * Atomic read-modify-write for pull-requests JSON files.
- * Wraps mutateJsonFileLocked with defaultValue of [].
- * @param {string} filePath - Path to the pull-requests JSON file
- * @param {Function} mutator - Receives the array, mutates in place or returns new value
- */
-function mutatePullRequests(filePath, mutator) {
-  // Phase 9.4 SQL-only. Route through pull-requests-store when filePath sits
-  // under MINIONS_DIR. Ad-hoc tmp paths (legacy tests using createTmpDir)
-  // still fall through to the JSON path.
-  const fpNorm = String(filePath).replace(/\\/g, '/');
-  const minionsNorm = String(MINIONS_DIR).replace(/\\/g, '/');
-  const insideMinionsDir = fpNorm.startsWith(minionsNorm + '/') || fpNorm === minionsNorm + '/pull-requests.json';
-  if (insideMinionsDir) {
-    const store = require('./pull-requests-store');
-    const scope = store.scopeForFilePath(filePath);
-    const { wrote, result } = store.applyPullRequestsMutation(scope, (prs) => {
-      if (!Array.isArray(prs)) prs = [];
-      return mutator(prs) || prs;
-    });
-    if (wrote) {
-      try { require('./db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
-    }
-    return result;
-  }
+function readPullRequests(source = null) {
+  return require('./pull-requests-store').readPullRequestsForScope(stateScope(source));
+}
 
-  return mutateJsonFileLocked(filePath, (data) => {
-    if (!Array.isArray(data)) data = [];
-    return mutator(data) || data;
-  }, {
-    defaultValue: [],
-    skipWriteIfUnchanged: true,
-    _skipSqlRouting: true,
-    onWrote: () => {
-      try { require('./db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
-    },
+function mutatePullRequests(source, mutator) {
+  const store = require('./pull-requests-store');
+  const { wrote, result } = store.applyPullRequestsMutation(stateScope(source), (prs) => {
+    if (!Array.isArray(prs)) prs = [];
+    return mutator(prs) || prs;
   });
+  if (wrote) {
+    try { require('./db-events').emitStateEvent('pull_requests'); } catch { /* optional */ }
+  }
+  return result;
 }
 
 /**
@@ -8818,11 +8392,7 @@ module.exports = {
   writeStopIntent,
   clearStopIntent,
   isStopIntentSet,
-  COOLDOWNS_PATH,
-  ENGINE_STATE_PATH, // W-mp60tw0u000j3931
-  PR_LINKS_PATH,
   PINNED_ITEMS_PATH,
-  LOG_PATH,
   CONSTELLATION_BRIDGE_MARKER_PATH,
   CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
   DEFAULT_DASHBOARD_PORT,
@@ -8860,14 +8430,12 @@ module.exports = {
   forEachPidFile,
   resolveMinionsHome,
   saveMinionsRootPointer,
-  neutralizeJsonBackupSidecar,
   PROMPT_CONTEXTS_DIR,
   dispatchPromptSidecarPath,
   dispatchCompletionReportPath,
   sidecarDispatchPrompt,
   resolveDispatchPrompt,
   deleteDispatchPromptSidecar,
-  assertStateFileSize,
   withFileLock,
   mutateJsonFileLocked,
   mutateControl, recordEngineRespawn,
@@ -8878,8 +8446,11 @@ module.exports = {
   mutateKbSwept,        // Phase 9.3
   mutateKbSweepState,   // Phase 9.3
   mutateTestResults,    // Phase 9.3
+  stateScope,
+  readWorkItems,
   mutateWorkItems,
   reopenWorkItem,
+  readPullRequests,
   mutatePullRequests,
   uid,
   uniquePath,
@@ -8925,7 +8496,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, isPrdArchived, isDefunctPrd, WORK_TYPE, WORKTREE_REQUIRING_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject, extractPlanTargetProjects,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, isPrdArchived, isDefunctPrd, WORK_TYPE, isFixLikeWorkType, WORKTREE_REQUIRING_TYPES, LIVE_VALIDATION_WORK_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject, extractPlanTargetProjects,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
@@ -8950,17 +8521,11 @@ module.exports = {
   resolveConfiguredProject,
   resolveProjectSource,
   projectRoot,
-  centralWorkItemsPath,
-  centralPullRequestsPath,
   projectStateDir,
   projectStateDirEnsure,
-  projectWorkItemsPath,
-  projectPrPath,
-  ensureProjectStateFiles,
+  initializeProjectState,
   sameResolvedPath,
   realPathForComparison, // exported for testing
-  prPathComparisonCandidates, // exported for testing
-  resolveProjectForPrPath, // exported for testing
   getPrLinks,
   addPrLink,
   normalizePrScopeSegment, // exported for testing
@@ -9051,6 +8616,10 @@ module.exports = {
   CHECKOUT_MODES,
   validateCheckoutMode,
   validateLiveValidation,
+  normalizeLiveValidationWorkType,
+  resolveLiveValidationTypes,
+  isLiveValidationConfigInvalid,
+  resolveLiveValidationAutoDispatchType,
   resolveCheckoutMode,
   isLiveCheckoutProject,
   resolveLiveCheckoutAutoReset,