@yemi33/minions 0.1.2379 → 0.1.2381

package/dashboard.js

@@ -66,13 +66,14 @@ const features = require('./engine/features');
 const ccWorkerPool = require('./engine/cc-worker-pool');
 const diagnosticsMemory = require('./engine/diagnostics-memory');
 const memoryStore = require('./engine/memory-store');
+const smallStateStore = require('./engine/small-state-store');
 const os = require('os');
 
 const { safeRead, safeReadOrNull, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore, safeUnlink, mutateJsonFileLocked, mutateTextFileLocked, mutateControl, mutateCooldowns, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, WORK_TYPE, WORKTREE_REQUIRING_TYPES, reopenWorkItem } = shared;
 const { getAgents, getAgentDetail, getPrdInfo, getWorkItems, getDispatchQueue,
   getSkills, getCommands, getInbox, getNotesWithMeta, getPullRequests,
   getEngineLog, getMetrics, getKnowledgeBaseEntries, getKnowledgeBaseEntriesSnapshot, getProjectGitStatus, timeSince,
-  MINIONS_DIR, AGENTS_DIR, ENGINE_DIR, INBOX_DIR, DISPATCH_PATH, PRD_DIR } = queries;
+  MINIONS_DIR, AGENTS_DIR, ENGINE_DIR, INBOX_DIR, PRD_DIR } = queries;
 
 // Dev vs binary differentiation. When two dashboards run side-by-side (npm
 // install on 7331, local checkout on 7332), the favicon and title need to
@@ -230,7 +231,7 @@ function ensureConfiguredProjectStateFiles() {
     const root = p.localPath ? path.resolve(p.localPath) : null;
     if (!root || !fs.existsSync(root)) continue;
     try {
-      shared.ensureProjectStateFiles(p);
+      shared.initializeProjectState(p);
     } catch (e) {
       console.warn(`[dashboard] project state setup failed for "${p.name}": ${e.message}`);
     }
@@ -420,8 +421,14 @@ function mergeSettingsConfigUpdate(current, candidate, body, patch = {}) {
       // `candidate` in handleSettingsUpdate) is silently dropped on the way
       // through mergeSettingsConfigUpdate → mutateDashboardConfig and never
       // reaches disk — the endpoint would return 200 but persist nothing.
+      const modeWasRequested = Object.prototype.hasOwnProperty.call(update, 'checkoutMode')
+        || Object.prototype.hasOwnProperty.call(update, 'worktreeMode');
       if (Object.prototype.hasOwnProperty.call(candidateProject, 'checkoutMode')) {
         currentProject.checkoutMode = candidateProject.checkoutMode;
+      } else if (Object.prototype.hasOwnProperty.call(candidateProject, 'worktreeMode')) {
+        currentProject.checkoutMode = shared.resolveCheckoutMode(candidateProject);
+      } else if (!modeWasRequested && Object.prototype.hasOwnProperty.call(currentProject, 'worktreeMode')) {
+        currentProject.checkoutMode = shared.resolveCheckoutMode(currentProject);
       } else {
         delete currentProject.checkoutMode;
       }
@@ -609,7 +616,7 @@ function inferActionPrRecord(action, prs, project = null) {
 // real pull request before `copyWorkItemPrFields` promotes it to structured
 // targetPr/pr_id/prNumber fields. GitHub & ADO issues share the PR number
 // namespace, so a bare `owner/repo#244` / `#244` can be an ISSUE. Stamping an
-// issue mints a phantom pull-requests.json record (agent 'human', goes
+// issue mints a phantom tracked PR record (agent 'human', goes
 // abandoned) AND routes the dispatch through the PR-fix path instead of
 // implement-and-open-a-fresh-PR.
 //
@@ -767,7 +774,7 @@ async function _fetchLivePrRecord(canonicalId, opts) {
 function _findTrackedPrRecord(prRef, project) {
   if (!project) return null;
   try {
-    const prs = shared.safeJsonArr(shared.projectPrPath(project));
+    const prs = shared.readPullRequests(project);
     return shared.findPrRecord(prs, prRef, project);
   } catch { return null; }
 }
@@ -831,7 +838,7 @@ async function copyWorkItemPrFields(item, input, pr = null, opts = {}) {
     if (structuredRef) {
       prRef = structuredRef; // explicit operator intent — trusted, no verification
     } else {
-      if (String(item?.type || '').toLowerCase() !== WORK_TYPE.FIX) return;
+      if (!shared.isFixLikeWorkType(String(item?.type || '').toLowerCase())) return;
       const looseRef = getWorkItemPrRef(input);
       if (!looseRef) return;
       // issue #246 — confirm the loose ref is a PR (not an issue) before stamping.
@@ -919,14 +926,13 @@ function normalizeWorkItemDedupTitle(value) {
     .toLowerCase();
 }
 
-function resolveWorkItemDedupProject(item, wiPath = '') {
+function resolveWorkItemDedupProject(item, project = null) {
   const projectName = normalizeWorkItemDedupText(item?.project || item?._project || item?._source);
   if (projectName) {
     const namedProject = shared.resolveProjectSource(projectName, PROJECTS, { allowCentral: false });
     if (namedProject.project) return namedProject.project;
   }
-  if (!wiPath) return null;
-  return shared.resolveProjectSource(wiPath, PROJECTS, { allowCentral: false }).project || null;
+  return project;
 }
 
 function getWorkItemPrRefCandidates(item) {
@@ -962,7 +968,7 @@ function normalizeWorkItemDedupPrIdentity(item, project = null) {
 }
 
 function workItemCreateFingerprint(item, options = {}) {
-  const project = resolveWorkItemDedupProject(item, options.wiPath);
+  const project = resolveWorkItemDedupProject(item, options.project);
   return {
     title: normalizeWorkItemDedupTitle(item?.title),
     type: routing.normalizeWorkType(item?.type || item?.workType, WORK_TYPE.IMPLEMENT),
@@ -1015,10 +1021,11 @@ function findDuplicateWorkItemCreate(items, candidate, options = {}) {
   }) || null;
 }
 
-function createWorkItemWithDedup(wiPath, item, options = {}) {
+function createWorkItemWithDedup(source, item, options = {}) {
+  const project = options.project || (source && typeof source === 'object' ? source : null);
   let result = null;
-  mutateWorkItems(wiPath, items => {
-    const existing = findDuplicateWorkItemCreate(items, item, { ...options, wiPath });
+  mutateWorkItems(source, items => {
+    const existing = findDuplicateWorkItemCreate(items, item, { ...options, project });
     if (existing) {
       result = { created: false, item: existing, duplicateOf: existing.id };
       return items;
@@ -1153,21 +1160,26 @@ function dispatchPrefixForResolvedSource(target) {
   return target?.project ? `work-${target.project.name}-` : 'central-work-';
 }
 
+function matchesResolvedWorkItemDispatch(entry, target, id) {
+  const dispatchKey = dispatchPrefixForResolvedSource(target) + id;
+  return entry?.meta?.dispatchKey === dispatchKey || entry?.meta?.parentKey === dispatchKey;
+}
+
 function findWorkItemsTargetById(id, source, projects = PROJECTS) {
   const explicitSource = source !== undefined && source !== null && String(source).trim() !== '';
   if (explicitSource) {
     const target = resolveProjectSourceTarget(source, projects);
     if (target.error) return { error: target.error };
-    const items = shared.safeJsonArr(target.wiPath);
+    const items = shared.readWorkItems(target.scope);
     return { ...target, found: items.some(i => i.id === id) };
   }
 
   const central = resolveProjectSourceTarget('central', projects);
-  const centralItems = shared.safeJsonArr(central.wiPath);
+  const centralItems = shared.readWorkItems(central.scope);
   if (centralItems.some(i => i.id === id)) return { ...central, found: true };
   for (const project of projects) {
     const target = resolveProjectSourceTarget(project.name, projects);
-    const items = shared.safeJsonArr(target.wiPath);
+    const items = shared.readWorkItems(target.scope);
     if (items.some(i => i.id === id)) return { ...target, found: true };
   }
   return { found: false };
@@ -1314,23 +1326,18 @@ function validatePipelineProjects(pipeline, projects = PROJECTS) {
 }
 
 /**
- * Aggregate archived work items from the central archive plus every project
- * archive. Each item is tagged with `_source` (`'central'` or the project name)
- * so the UI can group/filter. Reads via `safeJsonArr` — a corrupt archive
- * surfaces a logged parse failure and contributes zero items, instead of
- * throwing 500 or silently dropping the file.
+ * Aggregate archived work items from central and project SQL scopes.
  *
  * Exported for testing (P-h3arch-8c19).
  */
-function collectArchivedWorkItems(minionsDir = MINIONS_DIR, projects = PROJECTS) {
+function collectArchivedWorkItems(projects = PROJECTS) {
+  const store = require('./engine/work-items-store');
   const archived = [];
-  const centralPath = path.join(minionsDir, 'work-items-archive.json');
-  for (const item of safeJsonArr(centralPath)) {
+  for (const item of store.readArchivedWorkItemsForScope('central')) {
     archived.push({ ...item, _source: 'central' });
   }
   for (const project of projects) {
-    const archPath = shared.projectWorkItemsPath(project).replace('.json', '-archive.json');
-    for (const item of safeJsonArr(archPath)) {
+    for (const item of store.readArchivedWorkItemsForScope(project.name)) {
       archived.push({ ...item, _source: project.name });
     }
   }
@@ -1344,7 +1351,7 @@ function linkPullRequestForTracking({ url, title, project: projectName, contextO
   }
   const projects = shared.getProjects(config);
   const { project: targetProject, resolution: projectResolution } = resolveManualPrLinkProject(url, projectName, projects);
-  const prPath = targetProject ? shared.projectPrPath(targetProject) : shared.centralPullRequestsPath(MINIONS_DIR);
+  const source = targetProject || 'central';
 
   const prNumMatch = url.match(/\/pull\/(\d+)|pullrequest\/(\d+)/);
   const prNum = prNumMatch ? (prNumMatch[1] || prNumMatch[2]) : Date.now().toString().slice(-6);
@@ -1353,7 +1360,7 @@ function linkPullRequestForTracking({ url, title, project: projectName, contextO
   const contextText = typeof context === 'string' ? context : (context == null ? '' : JSON.stringify(context));
   const metadata = normalizePrMetadata(options.metadata);
   const resolvedContextOnly = typeof contextOnly === 'boolean' ? contextOnly : false;
-  const result = shared.upsertPullRequestRecord(prPath, {
+  const result = shared.upsertPullRequestRecord(source, {
     id: prId,
     prNumber: parseInt(prNum, 10) || null,
     title: (metadata?.title || title || 'PR #' + prNum + ' (polling...)').slice(0, 120),
@@ -1382,7 +1389,7 @@ function linkPullRequestForTracking({ url, title, project: projectName, contextO
     // tombstone left by a prior explicit delete rather than silently no-op.
     allowResurrect: true,
   });
-  return { ...result, prPath, targetProject, projectResolution, prNum };
+  return { ...result, scope: shared.stateScope(source), targetProject, projectResolution, prNum };
 }
 
 // W-mpmwxkzm0009ba0b — Per-row auto-observe toggle backing helper for
@@ -1394,9 +1401,9 @@ function linkPullRequestForTracking({ url, title, project: projectName, contextO
 // fallback (`contextOnly = !observe`) for any caller that still sends it —
 // the dashboard client itself now sends `contextOnly` exclusively
 // (P-2b6e4d81; see docs/deprecated.json#pr-observe-observe-body-param).
-// Returns the updated record + the PR path that was touched. Throws an
+// Returns the updated record + SQL scope. Throws an
 // Error with `statusCode` for the route handler to map to an HTTP status.
-function updatePullRequestObserveFlag({ host, slug, number, observe, contextOnly } = {}, config = CONFIG, minionsDir = MINIONS_DIR) {
+function updatePullRequestObserveFlag({ host, slug, number, observe, contextOnly } = {}, config = CONFIG) {
   const hostStr = String(host || '').trim().toLowerCase();
   const slugStr = String(slug || '').trim();
   const numberInt = Number.parseInt(number, 10);
@@ -1428,21 +1435,18 @@ function updatePullRequestObserveFlag({ host, slug, number, observe, contextOnly
 
   const canonicalId = `${hostStr}:${slugStr}#${numberInt}`;
   const projects = shared.getProjects(config);
-  const prPaths = [
-    ...projects.map(p => shared.projectPrPath(p)),
-    shared.centralPullRequestsPath(minionsDir),
-  ];
+  const sources = [...projects, 'central'];
 
   let updated = null;
-  let updatedPath = null;
-  for (const prPath of prPaths) {
+  let updatedScope = null;
+  for (const source of sources) {
     if (updated) break;
-    shared.mutatePullRequests(prPath, (prs) => {
+    shared.mutatePullRequests(source, (prs) => {
       const pr = prs.find(p => p && p.id === canonicalId);
       if (!pr) return prs;
       pr.contextOnly = contextOnlyValue;
       updated = { id: pr.id, contextOnly: pr.contextOnly };
-      updatedPath = prPath;
+      updatedScope = shared.stateScope(source);
       return prs;
     });
   }
@@ -1452,7 +1456,7 @@ function updatePullRequestObserveFlag({ host, slug, number, observe, contextOnly
     err.statusCode = 404;
     throw err;
   }
-  return { ...updated, prPath: updatedPath };
+  return { ...updated, scope: updatedScope };
 }
 
 function _normalizeSkillDirForCompare(dir) {
@@ -1659,24 +1663,12 @@ const PLANS_CACHE_TTL_MS = 5000;
 function invalidatePlansCache() { _plansCache = null; _plansCacheTs = 0; }
 
 function statePathExists(filePath) {
-  if (prdStore.parsePrdPath(filePath)) return prdStore.readPrd(filePath) != null;
   return fs.existsSync(filePath);
 }
 
-// Resolve a plan/PRD file path: .json files live in prd/, .md files in plans/
-// Validates that the file stays within the expected directory to prevent path traversal.
+// Resolve a human-authored Markdown plan path.
 function resolvePlanPath(file) {
-  if (file.endsWith('.json')) {
-    // Validate against both prd/ and prd/archive/
-    shared.sanitizePath(file, PRD_DIR);
-    const active = path.join(PRD_DIR, file);
-    if (prdStore.readPrd(active)) return active;
-    const archived = path.join(PRD_DIR, 'archive', file);
-    if (prdStore.readPrd(archived)) return archived;
-    return active;
-  }
-
-  // Validate against both plans/ and plans/archive/
+  if (!file.endsWith('.md')) throw new Error('expected a Markdown plan filename');
   shared.sanitizePath(file, PLANS_DIR);
   const active = path.join(PLANS_DIR, file);
   if (fs.existsSync(active)) return active;
@@ -1685,72 +1677,36 @@ function resolvePlanPath(file) {
   return active;
 }
 
-// W-mqa13ulk0002def5 — PRD post-archive: flip status+archivedAt, neutralize
-// the .backup sidecar, and move the source plan markdown to plans/archive/.
-// Each concern runs in its own try/catch so a failure in one (e.g. lock
-// contention from the engine's plan-completion scan throwing in
-// mutateJsonFileLocked) does not silently swallow the others — the bug that
-// orphaned plans/killswitches-and-granular-controls.md on 2026-06-11 after its
-// PRD archived OK. Failures are pushed into archiveWarnings (returned to the
-// dashboard as `warnings: [...]`) so the user sees them instead of a silent
-// `archivedSource: null`. _mutate / _safeJsonObj injection points are test
-// seams; production callers omit them.
-function _archivePrdPostProcess({ planFile, archivePath, planPath, plansDir, _mutate, _safeJsonObj } = {}) {
-  const mutate = typeof _mutate === 'function' ? _mutate : mutateJsonFileLocked;
-  const readObj = typeof _safeJsonObj === 'function' ? _safeJsonObj : safeJsonObj;
+// Archive a PRD in SQL, then move its source Markdown plan.
+function _archivePrdPostProcess({ planFile, plansDir, _mutate, _read } = {}) {
+  const mutate = typeof _mutate === 'function' ? _mutate : prdStore.mutatePrd;
+  const read = typeof _read === 'function' ? _read : prdStore.readPrd;
   const archiveWarnings = [];
   let plan = {};
   let archivedSource = null;
 
-  // (a) Flip the archived FLAG + status + archivedAt. Phase 10 step 4.2b:
-  // archived-ness is the flag now (not the directory), so set `archived:true`
-  // explicitly. The path-shaped mutator routes PRDs into SQL.
-  // When archivePath === planPath (in-place archive) this flags the PRD where it
-  // sits; when they differ (.md-cascade / legacy move) it flags the moved copy.
   try {
-    plan = mutate(archivePath, (data) => {
+    plan = mutate(planFile, (data) => {
       if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
       data.status = 'archived';
       data.archived = true;
       data.archivedAt = new Date().toISOString();
       return data;
-    }, { defaultValue: {} }) || {};
+    }) || {};
   } catch (e) {
     const warning = `Archive status flip failed for ${planFile}: ${e.message}`;
     archiveWarnings.push(warning);
     console.warn(warning);
   }
 
-  // Re-read the PRD from disk if mutate threw or returned an empty object —
-  // the file was already renamed into the archive dir, so the source_plan
-  // field is still on disk and the markdown move below needs it.
   if (!plan.source_plan) {
     try {
-      const disk = readObj(archivePath);
-      if (disk && typeof disk === 'object' && disk.source_plan) plan = disk;
-    } catch { /* readObj fallback is best-effort */ }
+      const stored = read(planFile);
+      if (stored && typeof stored === 'object' && stored.source_plan) plan = stored;
+    } catch { /* best-effort */ }
   }
 
-  // (b) Neutralize the .backup sidecar at the OLD live path ONLY when the file
-  // actually moved (archivePath !== planPath) — a stale prd/<f>.json.backup left
-  // behind by a move is resurrection fuel. For an in-place archive the file (and
-  // its current .backup) stay put and are valid, so there is nothing to neutralize.
-  if (planPath !== archivePath) {
-    try {
-      const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
-      if (!backupCleanup.ok) {
-        const warning = `Archive backup cleanup failed for ${planFile}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`;
-        archiveWarnings.push(warning);
-        console.warn(warning);
-      }
-    } catch (e) {
-      const warning = `Archive backup cleanup failed for ${planFile}: ${e.message}`;
-      archiveWarnings.push(warning);
-      console.warn(warning);
-    }
-  }
-
-  // (c) Move the source plan markdown into plans/archive/.
+  // Move the source plan Markdown into plans/archive/.
   if (plan.source_plan) {
     try {
       // Canonical key: a `plans/`-prefixed source_plan would otherwise join to
@@ -2398,18 +2354,15 @@ function _ifNoneMatchHasEtag(headerValue, currentEtag) {
   return false;
 }
 
-// mtime-based cache invalidation.
+// Cross-process cache invalidation.
 //
 // Engine and dashboard are independent processes; `invalidateStatusCache()`
 // lives in dashboard.js memory and is unreachable from engine code. We
-// detect engine-side state flips (WI pending→done, PR status changes,
-// dispatch.json mutations, PRD progress derived from work-items, …) by
-// statSync'ing a registry of input files on every status request. Any
-// mtime advance → cache busted → fresh rebuild on the same poll.
+// SQL mutations advance the events table; intentionally file-backed inputs
+// still use mtime tracking.
 //
 // The two source-of-truth lists live in `engine/queries.js`:
-//   - getStatusFastStateMtimePaths — engine-driven hot writes (dispatch,
-//     work-items, PR files, watches, qa runs, inbox, notes, meetings, …).
+//   - getStatusFastStateMtimePaths — file-backed hot inputs.
 //   - getStatusSlowStateMtimePaths — slower-cadence writes (PRD JSON,
 //     schedule/pipeline runs, pinned, skill discovery roots, MCP configs,
 //     git refs, …).
@@ -2591,26 +2544,7 @@ function _buildStatusSlowState() {
         ...status,
         mainBranch,
         branchMismatch,
-        // P-a3f9b209 / W-mqgzcrln002613b3 — surface the per-project dispatch
-        // mode so the Projects view can render a "Worktrees" vs "Live checkout"
-        // pill. resolveCheckoutMode honors the legacy worktreeMode field and
-        // defaults to 'worktree' when unset (matches engine spawn behavior).
-        checkoutMode: shared.resolveCheckoutMode(p),
-        // Surface the hybrid live-validation type (when configured) so the
-        // Projects view can render a distinct "Hybrid" pill: coding WIs author
-        // in isolated worktrees while only the named validation type runs
-        // in-place on the live checkout. Only meaningful when checkoutMode is
-        // 'live'; null otherwise (full-live or worktree projects).
-        liveValidationType: (shared.resolveCheckoutMode(p) === 'live' && p.liveValidation && p.liveValidation.type)
-          ? p.liveValidation.type
-          : null,
-        // W-mr2q361a00097e5c — surface liveValidation.autoDispatch alongside
-        // .type so the hybrid picker can preselect the "auto-validate"
-        // checkbox and the pill can visibly distinguish manual vs
-        // auto-validating hybrid projects. Only meaningful when checkoutMode
-        // is 'live'; false otherwise (matches the implicit today-default of
-        // autoDispatch being absent/false).
-        liveValidationAutoDispatch: !!(shared.resolveCheckoutMode(p) === 'live' && p.liveValidation && p.liveValidation.autoDispatch === true),
+        ..._projectCheckoutConfigView(p),
       };
     }),
     autoMode: {
@@ -2937,18 +2871,10 @@ const STATE_READ_ALLOWED_FILES = new Set([
 const STATE_READ_DENIED_BASENAMES = new Set([
   'session.json',
   'sessions.json',
-  'cc-session.json',
-  'cc-sessions.json',
-  'qa-sessions.json',
   'qa-sessions-history.json',
   'session-state.json',
   'session-token.json',
   'keep-pids.json',
-  // doc-sessions.json holds user-authored doc-chat conversation state
-  // (questions + document context + LLM responses). Was previously denied
-  // via a broad *sessions?.json regex that round-2 #9 narrowed; restoring
-  // explicit coverage here. (Round-3 review finding #2.)
-  'doc-sessions.json',
 ]);
 const STATE_READ_DENIED_PATTERNS = [
   /(^|[\\/])state\.db($|-wal$|-shm$)/i,
@@ -2989,7 +2915,7 @@ function _stateReadContentType(ext) {
 // serveFreshJson is "run server-side enrichment, ETag off input mtimes."
 //
 // Used for slices whose payload joins multiple files (agents derived from
-// config + dispatch + inbox + steering, metrics derived from metrics.json
+// config + dispatch + inbox + steering, with SQL-backed metrics
 // + dispatch + PRs, PRD derived from PRD dir + work-items + PRs, etc.).
 // Replicating those joins in browser JS would be brittle, and shipping the
 // fully-enriched result through /api/status pays the staleness tax that
@@ -3079,6 +3005,44 @@ async function serveFreshJson(req, res, opts) {
   res.end(JSON.stringify(payload));
 }
 
+function _buildConstellationBridgeSnapshot() {
+  const config = queries.getConfig() || {};
+  const scheduleRuns = smallStateStore.readScheduleRuns();
+  const schedules = (Array.isArray(config.schedules) ? config.schedules : []).map(schedule => {
+    const run = scheduleRuns[schedule.id];
+    const lastRun = typeof run === 'string'
+      ? run
+      : (run?.lastRun || run?.lastCompletedAt || null);
+    return { ...schedule, _lastRun: lastRun };
+  });
+  const plans = prdStore.listPrdRows().map(row => {
+    const plan = row.plan && typeof row.plan === 'object' ? row.plan : {};
+    return {
+      id: row.filename,
+      title: plan.plan_summary || plan.title || row.filename,
+      status: row.archived
+        ? 'archived'
+        : (plan.status || (plan.requires_approval && !plan.approvedAt ? 'awaiting-approval' : 'active')),
+      agent: plan.generated_by || null,
+      project: plan.project || null,
+      createdAt: plan.generated_at || null,
+      updatedAt: row.updatedAt || null,
+    };
+  });
+
+  return require('./engine/bridge').buildBridgeSnapshot({
+    minionsVersion: _dashboardVersion.codeVersion,
+    control: queries.getControl(),
+    projects: shared.getProjects(config),
+    workItems: queries.getWorkItems(config, { enrich: false }),
+    pullRequests: queries.getPullRequests(config),
+    plans,
+    schedules,
+    agents: queries.getAgents(config),
+    dispatch: queries.getDispatch(),
+  });
+}
+
 function handleStateRead(req, res) {
   const urlPath = req.url.split('?')[0];
   const rel = decodeURIComponent(urlPath.slice('/state/'.length));
@@ -3285,7 +3249,7 @@ async function _handleStatusRequest(req, res) {
   }
 }
 
-// Periodic push for engine-driven changes (dispatch.json, work-items.json, pull-requests.json) that bypass invalidateStatusCache
+// Periodic push for engine-driven SQL state changes that bypass invalidateStatusCache.
 setInterval(() => {
   if (_statusStreamClients.size === 0) return;
   const data = getStatusJson();
@@ -3836,14 +3800,12 @@ function _filterCcTabSessions(sessions) {
 }
 
 function _readCcTabSessions({ prune = true } = {}) {
-  if (!prune) return _filterCcTabSessions(shared.safeJsonArr(CC_SESSIONS_PATH));
-  // P-c2sess-1d8e: read+filter+write atomically under the file lock so a
-  // concurrent tab upsert/delete cannot lose entries to last-write-wins.
+  if (!prune) return _filterCcTabSessions(smallStateStore.readCcSessions());
   let sessions;
-  mutateJsonFileLocked(CC_SESSIONS_PATH, (raw) => {
+  smallStateStore.applyCcSessionsMutation((raw) => {
     sessions = _filterCcTabSessions(raw);
     return sessions;
-  }, { defaultValue: [] });
+  });
   return sessions;
 }
 
@@ -3951,7 +3913,7 @@ function _joinCcPromptParts(...parts) {
 // only restore-time validity checks here are sessionId presence (anything
 // else would auto-expire the user's chat without their consent).
 try {
-  const saved = safeJson(path.join(ENGINE_DIR, 'cc-session.json'));
+  const saved = smallStateStore.readCcGlobalSession();
   if (saved && saved.sessionId) ccSession = saved;
 } catch { /* optional */ }
 
@@ -4138,20 +4100,40 @@ function _resetPreambleCache() {
   _preambleCacheTs = 0;
 }
 
-// Compact one-word-ish label for a project's effective dispatch checkout mode,
-// for CC state surfaces (preamble + refresh). 'worktree' | 'live' |
-// 'hybrid (live-validation: <type>)' so CC can see at a glance whether a project
-// authors in isolated worktrees, runs in-place on the operator tree, or splits
-// the two (coding → worktree, validation type → live). See resolveCheckoutMode.
+function _projectLiveValidationTypeValue(p) {
+  const types = shared.resolveLiveValidationTypes(p);
+  if (types.length === 0) return null;
+  return Array.isArray(p?.liveValidation?.type) ? types : types[0];
+}
+
+function _projectCheckoutConfigView(p) {
+  const checkoutMode = shared.resolveCheckoutMode(p);
+  return {
+    checkoutMode,
+    liveValidationType: checkoutMode === 'live' ? _projectLiveValidationTypeValue(p) : null,
+    liveValidationInvalid: checkoutMode === 'live' && shared.isLiveValidationConfigInvalid(p),
+    liveValidationAutoDispatch: !!shared.resolveLiveValidationAutoDispatchType(p),
+  };
+}
+
+// Compact checkout-mode label for Command Center state surfaces.
 function _projectCheckoutModeLabel(p) {
-  const mode = shared.resolveCheckoutMode(p);
-  if (mode === 'live' && p && p.liveValidation && p.liveValidation.type) {
-    // liveValidation.type may be a single string (legacy) or an array of
-    // strings (W-mr2m1ute000a9c01 — multi-select hybrid types); render all.
-    const types = Array.isArray(p.liveValidation.type) ? p.liveValidation.type : [p.liveValidation.type];
+  const {
+    checkoutMode,
+    liveValidationType,
+    liveValidationInvalid,
+  } = _projectCheckoutConfigView(p);
+  if (liveValidationInvalid) {
+    const effectiveTypes = liveValidationType
+      ? (Array.isArray(liveValidationType) ? liveValidationType : [liveValidationType])
+      : [];
+    return `hybrid (invalid liveValidation; effective live types: ${effectiveTypes.join(', ') || 'none'})`;
+  }
+  if (checkoutMode === 'live' && liveValidationType) {
+    const types = Array.isArray(liveValidationType) ? liveValidationType : [liveValidationType];
     return `hybrid (live-validation: ${types.join(', ')})`;
   }
-  return mode;
+  return checkoutMode;
 }
 
 function buildCCStatePreamble() {
@@ -4168,7 +4150,10 @@ function buildCCStatePreamble() {
   const prCount = getPullRequests().length;
   const wiCount = getWorkItems(null, { enrich: false }).length;
 
-  const planFiles = [...safeReadDir(PLANS_DIR), ...safeReadDir(PRD_DIR)].filter(f => f.endsWith('.md') || f.endsWith('.json'));
+  const planFiles = [
+    ...safeReadDir(PLANS_DIR).filter(file => file.endsWith('.md')),
+    ...prdStore.listPrdRows().map(row => row.filename),
+  ];
 
   const schedules = CONFIG.schedules || [];
   const enabledSchedules = schedules.filter(s => s.enabled !== false).length;
@@ -4321,13 +4306,13 @@ function getWorkItemPrRef(input) {
   // afford to be loose because gating would still require explicit
   // operator intent.
   //
-  // FIX-TYPE GATE on the stamp path (W-mqbaby2a000pa8ee): in practice
+  // FIX-LIKE GATE on the stamp path (W-mqbaby2a000pa8ee): in practice
   // the asymmetry leaked — the loose stamp writes to `item.pr_id` (a
   // canonical structured field), and the strict gate later reads
   // `item.pr_id` and sees the loose stamp AS IF it were structured
   // intent. To stop that leak without changing the loose detector
   // (which has other legitimate callers), `copyWorkItemPrFields` now
-  // gates the loose result on `item.type === "fix"`. Non-fix WIs only
+  // gates the loose result through `isFixLikeWorkType`. Other WIs only
   // get stamped from structured fields (incl. references/follow-up).
   // See the comment block on `copyWorkItemPrFields` above for details.
   return shared.extractWorkItemPrRef(input);
@@ -4340,12 +4325,13 @@ function getWorkItemPrRef(input) {
 // invalidation paths are prompt-hash mismatch (correctness — a stale system
 // prompt would carry the old persona/rules into resume turns) and the
 // LRU cap below (storage hygiene). Users can resume a doc-chat any time.
-const CC_SESSIONS_PATH = path.join(ENGINE_DIR, 'cc-sessions.json');
-const DOC_SESSIONS_PATH = path.join(ENGINE_DIR, 'doc-sessions.json');
-const CC_SESSION_PATH = path.join(ENGINE_DIR, 'cc-session.json');
 const DOC_SESSION_MAX_ENTRIES = shared.ENGINE_DEFAULTS.docSessionMaxEntries;
 const docSessions = new Map(); // key → { sessionId, lastActiveAt, turnCount }
 
+function persistCcSession() {
+  smallStateStore.applyCcGlobalSessionMutation(() => ccSession);
+}
+
 function _docSessionLastActiveMs(session) {
   const ms = Date.parse(session?.lastActiveAt || session?.createdAt || '');
   return Number.isFinite(ms) ? ms : 0;
@@ -4374,7 +4360,7 @@ function pruneDocSessions() {
 // Load persisted doc sessions on startup — no TTL/turn filtering, sessions
 // are non-expiring. Stale prompt-hash entries are dropped by pruneDocSessions.
 try {
-  const saved = safeJson(DOC_SESSIONS_PATH);
+  const saved = smallStateStore.readDocSessions();
   if (saved && typeof saved === 'object') {
     for (const [key, s] of Object.entries(saved)) {
       docSessions.set(key, s);
@@ -4387,8 +4373,7 @@ function persistDocSessions() {
   pruneDocSessions();
   const obj = {};
   for (const [key, s] of docSessions) obj[key] = s;
-  // P-c2sess-1d8e: lock against engine/cleanup.js's cap-trim RMW.
-  mutateJsonFileLocked(DOC_SESSIONS_PATH, () => obj, { defaultValue: {} });
+  smallStateStore.applyDocSessionsMutation(() => obj);
 }
 
 // Hourly hygiene sweep — drops prompt-hash mismatches and trims the LRU cap.
@@ -4456,7 +4441,7 @@ function updateSession(store, key, sessionId, existing) {
       turnCount: (existing ? ccSession.turnCount : 0) + 1,
       _promptHash: _ccPromptHash,
     };
-    mutateJsonFileLocked(CC_SESSION_PATH, () => ccSession, { defaultValue: {} });
+    persistCcSession();
   } else if (key) {
     const prev = docSessions.get(key);
     docSessions.set(key, {
@@ -4831,7 +4816,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
     // Invalidate the dead session so future calls don't try to resume it
     if (store === 'cc') {
       ccSession = { sessionId: null, createdAt: null, lastActiveAt: null, turnCount: 0 };
-      mutateJsonFileLocked(CC_SESSION_PATH, () => ccSession, { defaultValue: {} });
+      persistCcSession();
     } else if (sessionKey) {
       docSessions.delete(sessionKey);
       schedulePersistDocSessions();
@@ -4980,7 +4965,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
     sessionId = null;
     if (store === 'cc') {
       ccSession = { sessionId: null, createdAt: null, lastActiveAt: null, turnCount: 0 };
-      mutateJsonFileLocked(CC_SESSION_PATH, () => ccSession, { defaultValue: {} });
+      persistCcSession();
     } else if (sessionKey) {
       docSessions.delete(sessionKey);
       schedulePersistDocSessions();
@@ -6061,36 +6046,20 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
-      shared.sanitizePath(body.file, PRD_DIR);
-
-      // Find the PRD — check active and archive
-      const prdDir = path.join(MINIONS_DIR, 'prd');
-      let prdPath = path.join(prdDir, body.file);
-      let fromArchive = false;
-      if (!statePathExists(prdPath)) {
-        prdPath = path.join(prdDir, 'archive', body.file);
-        fromArchive = true;
-      }
-      if (!statePathExists(prdPath)) return jsonReply(res, 404, { error: 'PRD not found' });
-
-      // If archived, temporarily restore to active so checkPlanCompletion can find it
-      const activePath = path.join(prdDir, body.file);
-      if (fromArchive) {
-        const archivedPlan = safeJson(prdPath);
-        if (!archivedPlan) return jsonReply(res, 500, { error: 'Could not parse PRD file' });
-        mutateJsonFileLocked(activePath, () => {
-          archivedPlan.status = 'approved';
-          delete archivedPlan.completedAt;
-          delete archivedPlan.planStale;
-          return archivedPlan;
-        }, { defaultValue: archivedPlan });
+      let projectPlan = prdStore.readPrd(body.file);
+      if (!projectPlan && prdStore.readPrd(body.file, { archived: true })) {
+        projectPlan = prdStore.restorePrdFromArchive(body.file);
+        prdStore.mutatePrd(body.file, (data) => {
+          data.status = 'approved';
+          delete data.completedAt;
+          delete data.planStale;
+          return data;
+        });
+        projectPlan = prdStore.readPrd(body.file);
       }
+      if (!projectPlan) return jsonReply(res, 404, { error: 'PRD not found' });
 
       const config = queries.getConfig();
-      // safeJsonNoRestore — never resurrect an archived PRD's .backup sidecar
-      // during project resolution (W-mouptdh1000h9f39). The active-from-archive
-      // write above (mutateJsonFileLocked) already created activePath when needed.
-      const projectPlan = safeJsonNoRestore(activePath) || safeJsonNoRestore(prdPath);
       const projectTarget = projectPlan?.project
         ? resolveProjectSourceTarget(projectPlan.project, PROJECTS, { allowCentral: false })
         : null;
@@ -6098,9 +6067,8 @@ const server = http.createServer(async (req, res) => {
 
       // Check for existing verify WI — reset to pending if already done (re-verify)
       if (project) {
-        const wiPath = shared.projectWorkItemsPath(project);
         let existingVerify = null;
-        mutateWorkItems(wiPath, items => {
+        mutateWorkItems(project, items => {
           const v = items.find(w => w.sourcePlan === body.file && w.itemType === WORK_TYPE.VERIFY);
           if (v && (v.status === WI_STATUS.DONE || v.status === WI_STATUS.FAILED)) {
             // BUG-M10: use shared.reopenWorkItem so re-verify resets mirror
@@ -6119,17 +6087,16 @@ const server = http.createServer(async (req, res) => {
       }
 
       // No existing verify — clear completion flag and trigger fresh creation
-      mutateJsonFileLocked(activePath, (planData) => {
+      prdStore.mutatePrd(body.file, (planData) => {
         if (planData?._completionNotified) planData._completionNotified = false;
         return planData;
-      }, { defaultValue: {}, skipWriteIfUnchanged: true });
+      });
 
       const lifecycle = require('./engine/lifecycle');
       lifecycle.checkPlanCompletion({ item: { sourcePlan: body.file, id: 'manual' } }, config);
 
       if (project) {
-        const wiPath = shared.projectWorkItemsPath(project);
-        const items = safeJsonArr(wiPath);
+        const items = shared.readWorkItems(project);
         const verify = items.find(w => w.sourcePlan === body.file && w.itemType === WORK_TYPE.VERIFY);
         if (verify) {
           invalidateStatusCache();
@@ -6147,36 +6114,24 @@ const server = http.createServer(async (req, res) => {
       const { id, source } = body;
       if (!id) return jsonReply(res, 400, { error: 'id required' });
 
-      // Find the right file — check source first, then search all project files
+      // Resolve the owning SQL scope.
       let resolvedTarget = findWorkItemsTargetById(id, source, PROJECTS);
       if (resolvedTarget.error) return jsonReply(res, 404, { error: resolvedTarget.error });
-      let wiPath = resolvedTarget.found ? resolvedTarget.wiPath : null;
+      let wiScope = resolvedTarget.found ? resolvedTarget.scope : null;
       // If no work item found, attempt to re-materialize from PRD item definition
-      if (!wiPath) {
+      if (!wiScope) {
         const prdFile = body.prdFile;
         if (!prdFile) return jsonReply(res, 404, { error: 'work item not found in any source' });
-        // W-mrdykt9m0006e459 — prdFile is unauthenticated client input; reject
-        // traversal/absolute paths and anything that resolves outside PRD_DIR
-        // before it ever reaches a filesystem read.
-        try { shared.sanitizePath(prdFile, PRD_DIR); }
-        catch { return jsonReply(res, 400, { error: 'invalid prdFile path' }); }
-
-        // Look up PRD item to create a new work item on-demand.
-        // safeJsonNoRestore — PRDs are terminal artifacts; a stale .backup
-        // sidecar from an archived PRD must not resurrect the active PRD
-        // just because a user clicked retry on a stray work item
-        // (W-mouptdh1000h9f39).
-        const prdPath = path.join(PRD_DIR, prdFile);
-        const plan = shared.safeJsonNoRestore(prdPath);
+        const plan = prdStore.readPrd(prdFile);
         if (!plan?.missing_features) return jsonReply(res, 404, { error: 'PRD file not found or invalid' });
         const prdItem = plan.missing_features.find(f => f.id === id);
         if (!prdItem) return jsonReply(res, 404, { error: 'PRD item not found in ' + prdFile });
 
-        // Determine target work-items file (project from PRD item or plan, fallback to central)
+        // Determine target scope (project from PRD item or plan, fallback to central).
         const projName = prdItem.project || plan.project || prdFile.replace(/-\d{4}-\d{2}-\d{2}\.json$/, '');
         const prdTarget = resolveProjectSourceTarget(projName, PROJECTS, { allowCentral: false });
         const proj = prdTarget.project;
-        const targetWiPath = proj ? shared.projectWorkItemsPath(proj) : shared.centralWorkItemsPath(MINIONS_DIR);
+        const targetScope = proj || 'central';
 
         // Create new work item from PRD item definition (same logic as materializePlansAsWorkItems)
         const complexity = prdItem.estimated_complexity || 'medium';
@@ -6201,7 +6156,7 @@ const server = http.createServer(async (req, res) => {
           _source: proj?.name || 'central',
           _retryCount: 0,
         };
-        mutateWorkItems(targetWiPath, items => { items.push(newItem); });
+        mutateWorkItems(targetScope, items => { items.push(newItem); });
 
         // Reset PRD item status to pending
         try {
@@ -6210,15 +6165,14 @@ const server = http.createServer(async (req, res) => {
         } catch (e) { console.error('PRD status sync:', e.message); }
 
         // Clear dispatch history and cooldowns for this item
-        const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
         const dispatchKey = (proj ? `work-${proj.name}-` : 'central-work-') + id;
         try {
-          mutateJsonFileLocked(dispatchPath, (dispatch) => {
+          dispatchMod.mutateDispatch((dispatch) => {
             dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
             dispatch.completed = dispatch.completed.filter(d => d.meta?.dispatchKey !== dispatchKey);
             dispatch.completed = dispatch.completed.filter(d => !d.meta?.parentKey || d.meta.parentKey !== dispatchKey);
             return dispatch;
-          }, { defaultValue: { pending: [], active: [], completed: [] } });
+          });
         } catch (e) { console.error('dispatch cleanup:', e.message); }
         try {
           mutateCooldowns(cooldowns => {
@@ -6232,7 +6186,7 @@ const server = http.createServer(async (req, res) => {
 
       let found = false;
       let blocked = null;
-      mutateJsonFileLocked(wiPath, (items) => {
+      mutateWorkItems(wiScope, (items) => {
         if (!Array.isArray(items)) items = [];
         const item = items.find(i => i.id === id);
         if (!item) return items;
@@ -6279,15 +6233,14 @@ const server = http.createServer(async (req, res) => {
       if (!found) return jsonReply(res, 404, { error: 'item not found' });
 
       // Clear completed dispatch entries so the engine doesn't dedup this item
-      const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
       const dispatchKey = dispatchPrefixForResolvedSource(resolvedTarget) + id;
       try {
-        mutateJsonFileLocked(dispatchPath, (dispatch) => {
+        dispatchMod.mutateDispatch((dispatch) => {
           dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
           dispatch.completed = dispatch.completed.filter(d => d.meta?.dispatchKey !== dispatchKey);
           dispatch.completed = dispatch.completed.filter(d => !d.meta?.parentKey || d.meta.parentKey !== dispatchKey);
           return dispatch;
-        }, { defaultValue: { pending: [], active: [], completed: [] } });
+        });
       } catch (e) { console.error('dispatch cleanup:', e.message); }
 
       // Clear cooldown so item isn't blocked by exponential backoff
@@ -6310,11 +6263,10 @@ const server = http.createServer(async (req, res) => {
 
       const target = resolveProjectSourceTarget(source, PROJECTS);
       if (target.error) return jsonReply(res, 404, { error: target.error });
-      const wiPath = target.wiPath;
 
       let item = null;
       let found = false;
-      mutateJsonFileLocked(wiPath, (items) => {
+      mutateWorkItems(target.scope, (items) => {
         if (!Array.isArray(items)) return items;
         const idx = items.findIndex(i => i.id === id);
         if (idx === -1) return items;
@@ -6322,21 +6274,16 @@ const server = http.createServer(async (req, res) => {
         items.splice(idx, 1);
         found = true;
         return items;
-      }, { defaultValue: [] });
+      });
       if (!found) return jsonReply(res, 404, { error: 'item not found' });
 
       // Clean dispatch entries + kill running agent (outside lock)
-      const dispatchRemoved = cleanDispatchEntries(d =>
-        d.meta?.item?.id === id ||
-        d.meta?.dispatchKey?.endsWith(id)
-      );
+      const dispatchRemoved = cleanDispatchEntries(d => matchesResolvedWorkItemDispatch(d, target, id));
 
       // Clean cooldown entries so item can be re-created immediately
       try {
         mutateCooldowns(cooldowns => {
-          for (const key of Object.keys(cooldowns)) {
-            if (key.includes(id)) delete cooldowns[key];
-          }
+          delete cooldowns[dispatchPrefixForResolvedSource(target) + id];
           return cooldowns;
         });
       } catch (e) { console.error('cooldown cleanup:', e.message); }
@@ -6362,10 +6309,9 @@ const server = http.createServer(async (req, res) => {
 
       const target = resolveProjectSourceTarget(source, PROJECTS);
       if (target.error) return jsonReply(res, 404, { error: target.error });
-      const wiPath = target.wiPath;
 
       let result = null;
-      mutateJsonFileLocked(wiPath, (items) => {
+      mutateWorkItems(target.scope, (items) => {
         if (!Array.isArray(items)) items = [];
         const item = items.find(i => i.id === id);
         if (!item) { result = { code: 404, body: { error: 'item not found' } }; return items; }
@@ -6384,17 +6330,12 @@ const server = http.createServer(async (req, res) => {
       if (result.code !== 200) return jsonReply(res, result.code, result.body);
 
       // Clean dispatch entries + kill running agent (outside lock)
-      const dispatchRemoved = cleanDispatchEntries(d =>
-        d.meta?.item?.id === id ||
-        d.meta?.dispatchKey?.endsWith(id)
-      );
+      const dispatchRemoved = cleanDispatchEntries(d => matchesResolvedWorkItemDispatch(d, target, id));
 
       // Clean cooldown entries
       try {
         mutateCooldowns(cooldowns => {
-          for (const key of Object.keys(cooldowns)) {
-            if (key.includes(id)) delete cooldowns[key];
-          }
+          delete cooldowns[dispatchPrefixForResolvedSource(target) + id];
           return cooldowns;
         });
       } catch (e) { console.error('cooldown cleanup on cancel:', e.message); }
@@ -6412,37 +6353,13 @@ const server = http.createServer(async (req, res) => {
 
       const target = resolveProjectSourceTarget(source, PROJECTS);
       if (target.error) return jsonReply(res, 404, { error: target.error });
-      const wiPath = target.wiPath;
-
-      let archivedItem = null;
-      mutateJsonFileLocked(wiPath, (items) => {
-        if (!Array.isArray(items)) items = [];
-        const idx = items.findIndex(i => i.id === id);
-        if (idx === -1) return items;
-        archivedItem = items.splice(idx, 1)[0];
-        archivedItem.archivedAt = new Date().toISOString();
-        return items;
-      });
+      const archivedItem = require('./engine/work-items-store').archiveWorkItem(target.scope, id);
       if (!archivedItem) return jsonReply(res, 404, { error: 'item not found' });
 
-      // Append to archive file (outside lock)
-      const archivePath = wiPath.replace('.json', '-archive.json');
-      mutateJsonFileLocked(archivePath, (archive) => {
-        if (!Array.isArray(archive)) archive = [];
-        archive.push(archivedItem);
-        return archive;
-      }, { defaultValue: [] });
-
       // Clean dispatch entries for archived item
-      const sourcePrefix = dispatchPrefixForResolvedSource(target);
-      cleanDispatchEntries(d =>
-        d.meta?.dispatchKey === sourcePrefix + id ||
-        d.meta?.item?.id === id
-      );
+      cleanDispatchEntries(d => matchesResolvedWorkItemDispatch(d, target, id));
 
-      // (W-mpfsl2rw000m9469) Archiving removes a row from work-items.json, which
-      // is part of /api/status fast-state. Match every other mutating handler
-      // and invalidate so the dashboard reflects the archive immediately.
+      // Archiving removes the item from the active status snapshot.
       invalidateStatusCache();
       return jsonReply(res, 200, { ok: true, id });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
@@ -6453,7 +6370,7 @@ const server = http.createServer(async (req, res) => {
       // collectArchivedWorkItems uses safeJsonArr (typed default + logged parse
       // failure), so a corrupt archive file is surfaced via console.error and
       // contributes zero items instead of taking down the whole listing.
-      return jsonReply(res, 200, collectArchivedWorkItems(MINIONS_DIR, PROJECTS));
+      return jsonReply(res, 200, collectArchivedWorkItems(PROJECTS));
     } catch (e) { console.error('Archive fetch error:', e.message); return jsonReply(res, e.statusCode || 500, { error: e.message }); }
   }
 
@@ -6474,10 +6391,15 @@ const server = http.createServer(async (req, res) => {
           id === 'cancel' || id === 'reopen' || id === 'feedback') {
         return jsonReply(res, 404, { error: 'work item not found' });
       }
-      // Search central + every project's work-items.json for this id. The
-      // engine never enforces global id uniqueness in the file system, but
-      // collisions in practice are nil — first hit wins.
-      const found = getWorkItems().find(w => w && w.id === id);
+      const source = (new URL(req.url, 'http://localhost').searchParams.get('source') || '').trim();
+      const matches = getWorkItems().filter(w => w && w.id === id && (!source || w._source === source));
+      if (!source && matches.length > 1) {
+        return jsonReply(res, 409, {
+          error: 'work item id is ambiguous; provide source',
+          sources: matches.map(w => w._source),
+        });
+      }
+      const found = matches[0];
       if (!found) return jsonReply(res, 404, { error: 'work item not found' });
       return jsonReply(res, 200, { item: found });
     } catch (e) { return jsonReply(res, 500, { error: e.message }); }
@@ -6526,10 +6448,9 @@ const server = http.createServer(async (req, res) => {
 
       const target = resolveProjectSourceTarget(project, PROJECTS);
       if (target.error) return jsonReply(res, 404, { error: target.error });
-      const wiPath = target.wiPath;
 
       let result = null;
-      mutateJsonFileLocked(wiPath, (items) => {
+      mutateWorkItems(target.scope, (items) => {
         if (!Array.isArray(items)) items = [];
         const item = items.find(i => i.id === id);
         if (!item) { result = { code: 404, body: { error: 'item not found' } }; return items; }
@@ -6548,13 +6469,12 @@ const server = http.createServer(async (req, res) => {
       // Clear dispatch history and cooldowns outside lock
       const dispatchKey = dispatchPrefixForResolvedSource(target) + id;
       try {
-        const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
-        mutateJsonFileLocked(dispatchPath, (dispatch) => {
+        dispatchMod.mutateDispatch((dispatch) => {
           dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
           dispatch.completed = dispatch.completed.filter(d => d.meta?.dispatchKey !== dispatchKey);
           dispatch.completed = dispatch.completed.filter(d => !d.meta?.parentKey || d.meta.parentKey !== dispatchKey);
           return dispatch;
-        }, { defaultValue: { pending: [], active: [], completed: [] } });
+        });
       } catch (e) { console.error('dispatch cleanup on reopen:', e.message); }
       try {
         mutateCooldowns(cooldowns => {
@@ -6624,7 +6544,7 @@ const server = http.createServer(async (req, res) => {
       }
       const target = resolveWorkItemsCreateTarget(body.project);
       if (target.error) return jsonReply(res, 400, { error: target.error });
-      const wiPath = target.wiPath;
+      const wiScope = target.scope;
       const targetProject = target.project;
       const id = 'W-' + shared.uid();
       const item = {
@@ -6701,7 +6621,7 @@ const server = http.createServer(async (req, res) => {
       if (originAgent) item._originAgent = originAgent;
       if (originWi) item._originWi = originWi;
       await copyWorkItemPrFields(item, body, null, { project: targetProject });
-      // W-mq5wfh1v000e0da9 — Auto-enroll the PR into pull-requests.json when
+      // W-mq5wfh1v000e0da9 — Auto-enroll the PR into tracked state when
       // this is a `type: fix/review/test` WI carrying a structured PR pointer and
       // the PR isn't tracked yet. Without this, the engine's `pr_not_found` gate
       // skips the WI forever (engine.js dispatch loop). Idempotent — safe to
@@ -6732,7 +6652,7 @@ const server = http.createServer(async (req, res) => {
       // statuses) and takes precedence when matched.
       if (validatedFollowup) {
         let followupConflict = null;
-        mutateWorkItems(wiPath, items => {
+        mutateWorkItems(wiScope, items => {
           followupConflict = findExistingFollowupForComment(items, validatedFollowup.parent_comment_id);
           if (followupConflict) return items;
           items.push(item);
@@ -6751,7 +6671,7 @@ const server = http.createServer(async (req, res) => {
         invalidateStatusCache();
         return jsonReply(res, 200, { ok: true, id });
       }
-      const createResult = createWorkItemWithDedup(wiPath, item);
+      const createResult = createWorkItemWithDedup(wiScope, item, { project: targetProject });
       if (!createResult.created) {
         const duplicateId = createResult.duplicateOf || createResult.item?.id;
         // W-mr466ocx000l1191 — record the CC turn creation on the dedup path
@@ -6803,10 +6723,9 @@ const server = http.createServer(async (req, res) => {
 
       const target = resolveProjectSourceTarget(source, PROJECTS);
       if (target.error) return jsonReply(res, 404, { error: target.error });
-      const wiPath = target.wiPath;
+      const wiScope = target.scope;
 
-      // W-mrazefzz000358e3 — body.project reassigns which projects/<name>/
-      // work-items.json (or central) file owns this item. Resolve + validate
+      // W-mrazefzz000358e3 — body.project reassigns the owning SQL scope.
       // it up front (mirrors resolveWorkItemsCreateTarget's create-path
       // contract) so an unknown project name 400s cleanly instead of the
       // historical silent no-op. `projectMove` stays null when body.project
@@ -6820,19 +6739,14 @@ const server = http.createServer(async (req, res) => {
             knownProjects: PROJECTS.map(p => p.name),
           });
         }
-        projectMove = { wiPath: projTarget.wiPath, projectName: projTarget.project ? projTarget.project.name : null };
+        projectMove = { scope: projTarget.scope, projectName: projTarget.project ? projTarget.project.name : null };
       }
 
       let result = null;
       let agentChanged = false;
-      // Set inside the source-file lock below when a project move is
-      // needed. W-mrbbmltq000fce9f: the move itself (target push + source
-      // removal) is executed AFTER this lock releases, target-write-first,
-      // so a failure never straddles "spliced from source, not yet in
-      // target" — see the two-phase block below.
       let movedItem = null;
       let needsMove = false;
-      mutateJsonFileLocked(wiPath, (items) => {
+      mutateWorkItems(wiScope, (items) => {
         if (!Array.isArray(items)) items = [];
         const idx = items.findIndex(i => i.id === id);
         if (idx === -1) { result = { code: 404, body: { error: 'item not found' } }; return items; }
@@ -6869,23 +6783,7 @@ const server = http.createServer(async (req, res) => {
         }
         item.updatedAt = new Date().toISOString();
 
-        // W-mrazefzz000358e3 — a cross-project move actually MOVEs the item
-        // between work-items.json files when the resolved target differs
-        // from where it lives today, rather than just stamping item.project
-        // in place. Only trip this when the resolved wiPath actually
-        // changes — re-assigning the same project the item already lives in
-        // is a no-op move.
-        //
-        // W-mrbbmltq000fce9f — do NOT splice the item out of the source
-        // array here. Doing the splice-then-push as two independent locked
-        // calls (the historical bug) means a target-write failure after
-        // this callback commits leaves the item spliced from source and
-        // never written to target: silently lost from both stores. Instead
-        // only STAGE the move — clone the (already field-edited) item with
-        // its new `project` value — and leave the source array untouched.
-        // The actual splice happens in a later, separate lock, only once
-        // the target push below has durably committed.
-        if (projectMove && path.resolve(projectMove.wiPath) !== path.resolve(wiPath)) {
+        if (projectMove && projectMove.scope !== wiScope) {
           needsMove = true;
           movedItem = { ...item };
           if (projectMove.projectName) movedItem.project = projectMove.projectName;
@@ -6899,79 +6797,14 @@ const server = http.createServer(async (req, res) => {
 
       if (needsMove && result.code === 200) {
         try {
-          // Phase 1 of the move: durably write the item into the TARGET
-          // store first. If this throws (lock timeout, storage error,
-          // process crash), the source store still holds the item
-          // untouched (aside from the field edits already committed above)
-          // — nothing to roll back, nothing lost.
-          mutateJsonFileLocked(projectMove.wiPath, (targetItems) => {
-            if (!Array.isArray(targetItems)) targetItems = [];
-            targetItems.push(movedItem);
-            return targetItems;
-          });
-        } catch (targetErr) {
-          return jsonReply(res, 500, {
-            error: `project move failed while writing to target store; item left unchanged in its original project: ${targetErr.message}`,
-          });
-        }
-
-        try {
-          // Phase 2: the target write is confirmed durable — now it's safe
-          // to remove the item from the source store.
-          mutateJsonFileLocked(wiPath, (items) => {
-            if (!Array.isArray(items)) items = [];
-            const spliceIdx = items.findIndex(i => i.id === id);
-            if (spliceIdx !== -1) items.splice(spliceIdx, 1);
-            return items;
-          });
-        } catch (spliceErr) {
-          // Removing from source failed AFTER the target write already
-          // committed. Compensate by removing the item from the target
-          // store again, so the item ends up in exactly one store (its
-          // original) instead of duplicated across two.
-          //
-          // W-mrciooy1000e2ac3 — the compensating rollback write can ITSELF
-          // fail (double-failure: destination insert succeeded, source
-          // splice failed, and the compensating removal from destination
-          // also failed). Swallowing that second error and unconditionally
-          // reporting "move was rolled back" is a lie: the item is still
-          // duplicated in both stores. Track the rollback outcome and
-          // surface the double-failure distinctly so the caller/UI never
-          // believes a rollback happened when it didn't.
-          let rollbackErr = null;
-          try {
-            mutateJsonFileLocked(projectMove.wiPath, (targetItems) => {
-              if (!Array.isArray(targetItems)) targetItems = [];
-              const ti = targetItems.findIndex(i => i.id === id);
-              if (ti !== -1) targetItems.splice(ti, 1);
-              return targetItems;
-            });
-          } catch (rbErr) { rollbackErr = rbErr; }
-
-          if (rollbackErr) {
-            console.error(
-              `[work-items/update] DOUBLE FAILURE on cross-project move of ${id}: ` +
-              `source-splice failed (${spliceErr.message}) AND compensating rollback ` +
-              `from target store also failed (${rollbackErr.message}). Item may now be ` +
-              `duplicated across source (${wiPath}) and target (${projectMove.wiPath}) ` +
-              `— manual reconciliation required.`
-            );
-            return jsonReply(res, 500, {
-              error: `project move failed while removing from source store, and the compensating rollback also failed: ${rollbackErr.message}. ` +
-                `Item may be duplicated across both stores — manual reconciliation required.`,
-              reconciliation: {
-                required: true,
-                id,
-                sourceStore: wiPath,
-                targetStore: projectMove.wiPath,
-                spliceError: spliceErr.message,
-                rollbackError: rollbackErr.message,
-              },
-            });
+          const moved = require('./engine/work-items-store')
+            .moveWorkItem(wiScope, projectMove.scope, id, movedItem);
+          if (!moved) {
+            return jsonReply(res, 404, { error: 'item disappeared before project move' });
           }
-
+        } catch (moveErr) {
           return jsonReply(res, 500, {
-            error: `project move failed while removing from source store; move was rolled back: ${spliceErr.message}`,
+            error: `project move failed; item remains in its original scope: ${moveErr.message}`,
           });
         }
       }
@@ -7015,8 +6848,7 @@ const server = http.createServer(async (req, res) => {
       const planWorkItem = buildPlanWorkItem(body);
       if (planWorkItem.error) return jsonReply(res, 400, { error: planWorkItem.error });
       // Write as a work item with type 'plan' — user must explicitly execute plan-to-prd after reviewing
-      const wiPath = path.join(MINIONS_DIR, 'work-items.json');
-      mutateWorkItems(wiPath, items => { items.push(planWorkItem.item); });
+      mutateWorkItems('central', items => { items.push(planWorkItem.item); });
       recordCcTurnIfPresent(req, {
         kind: 'plan', id: planWorkItem.id, title: planWorkItem.item?.title || body.title.trim(), project: planWorkItem.item?.project || null,
       });
@@ -7032,8 +6864,7 @@ const server = http.createServer(async (req, res) => {
       if (manualPrd.error) return jsonReply(res, 400, { error: manualPrd.error });
 
       const planFile = 'manual-' + shared.uid() + '.json';
-      const manualPrdPath = path.join(PRD_DIR, planFile);
-      safeWrite(manualPrdPath, manualPrd.plan);
+      prdStore.writePrd(planFile, manualPrd.plan);
       invalidatePlansCache();
       return jsonReply(res, 200, { ok: true, id: manualPrd.id, file: planFile });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
@@ -7043,19 +6874,14 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       if (!body.source || !body.itemId) return jsonReply(res, 400, { error: 'source and itemId required' });
-      // Reject markdown filenames — mutateJsonFileLocked below silently overwrites
-      // the file with JSON, destroying source plans (see /api/plans/approve trap).
       if (!body.source.endsWith('.json')) return jsonReply(res, 400, { error: 'expected a PRD JSON filename in `source` (got `' + body.source + '`). Pass prd/<plan>.json, not plans/<plan>.md.' });
-      const planPath = resolvePlanPath(body.source);
-      if (!statePathExists(planPath)) return jsonReply(res, 404, { error: 'plan file not found' });
-      // Pre-check: verify item exists before taking the lock
-      const preCheck = safeJsonObj(planPath);
+      const preCheck = prdStore.readPrd(body.source);
+      if (!preCheck) return jsonReply(res, 404, { error: 'plan not found' });
       const preItem = (preCheck.missing_features || []).find(f => f.id === body.itemId);
       if (!preItem) return jsonReply(res, 404, { error: 'item not found in plan' });
 
-      // Atomically read-modify-write under file lock
       let item;
-      mutateJsonFileLocked(planPath, (plan) => {
+      prdStore.mutatePrd(body.source, (plan) => {
         const target = (plan.missing_features || []).find(f => f.id === body.itemId);
         if (!target) return plan; // TOCTOU: item deleted between pre-check and lock acquisition
         if (body.name !== undefined) target.name = body.name;
@@ -7072,13 +6898,10 @@ const server = http.createServer(async (req, res) => {
 
       // Feature 3: Sync edits to materialized work item if still pending
       let workItemSynced = false;
-      const wiSyncPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-      for (const proj of PROJECTS) {
-        wiSyncPaths.push(shared.projectWorkItemsPath(proj));
-      }
-      for (const wiPath of wiSyncPaths) {
+      const workItemScopes = ['central', ...PROJECTS];
+      for (const scope of workItemScopes) {
         try {
-          mutateWorkItems(wiPath, items => {
+          mutateWorkItems(scope, items => {
             const wi = items.find(w => w.sourcePlan === body.source && w.id === body.itemId);
             if (wi && wi.status === WI_STATUS.PENDING) {
               if (body.name !== undefined) wi.title = 'Implement: ' + body.name;
@@ -7103,10 +6926,9 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.source || !body.itemId) return jsonReply(res, 400, { error: 'source and itemId required' });
       if (!body.source.endsWith('.json')) return jsonReply(res, 400, { error: 'expected a PRD JSON filename in `source` (got `' + body.source + '`). Pass prd/<plan>.json, not plans/<plan>.md.' });
-      const planPath = resolvePlanPath(body.source);
-      if (!statePathExists(planPath)) return jsonReply(res, 404, { error: 'plan file not found' });
+      if (!prdStore.readPrd(body.source)) return jsonReply(res, 404, { error: 'plan not found' });
       let removed = false;
-      mutateJsonFileLocked(planPath, (plan) => {
+      prdStore.mutatePrd(body.source, (plan) => {
         if (!plan || Array.isArray(plan) || typeof plan !== 'object') plan = { missing_features: [] };
         const features = Array.isArray(plan.missing_features) ? plan.missing_features : [];
         const idx = features.findIndex(f => f.id === body.itemId);
@@ -7120,13 +6942,10 @@ const server = http.createServer(async (req, res) => {
 
       // Also remove any materialized work item for this plan item
       let cancelled = false;
-      const allWiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-      for (const proj of PROJECTS) {
-        allWiPaths.push(shared.projectWorkItemsPath(proj));
-      }
-      for (const wiPath of allWiPaths) {
+      const workItemScopes = ['central', ...PROJECTS];
+      for (const scope of workItemScopes) {
         try {
-          mutateWorkItems(wiPath, items => {
+          mutateWorkItems(scope, items => {
             const filtered = items.filter(w => !(w.sourcePlan === body.source && w.id === body.itemId));
             if (filtered.length < items.length) {
               cancelled = true;
@@ -7170,22 +6989,20 @@ const server = http.createServer(async (req, res) => {
       try { fs.unlinkSync(path.join(agentDir, 'steer.md')); } catch { /* optional */ }
 
       // 3. Remove all active dispatch entries for this agent
-      const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
       const removedIds = [];
-      mutateJsonFileLocked(dispatchPath, (dp) => {
+      dispatchMod.mutateDispatch((dp) => {
         const removed = (dp.active || []).filter(d => d.agent === agentId);
         removed.forEach(d => removedIds.push(d.id));
         dp.active = (dp.active || []).filter(d => d.agent !== agentId);
         return dp;
-      }, { defaultValue: { pending: [], active: [], completed: [] } });
+      });
 
       // 4. Reset work items from dispatched → pending so they can be retried
-      const allWiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-      for (const proj of PROJECTS) allWiPaths.push(shared.projectWorkItemsPath(proj));
+      const workItemScopes = ['central', ...PROJECTS];
       let resetCount = 0;
-      for (const wiPath of allWiPaths) {
+      for (const scope of workItemScopes) {
         try {
-          mutateWorkItems(wiPath, items => {
+          mutateWorkItems(scope, items => {
             for (const item of items) {
               if (item.dispatched_to === agentId && item.status === WI_STATUS.DISPATCHED) {
                 item.status = WI_STATUS.PENDING;
@@ -7214,8 +7031,7 @@ const server = http.createServer(async (req, res) => {
       if (!requestedAgent && !requestedTask) return jsonReply(res, 400, { error: 'agent or task required' });
 
       // Pre-read for response snapshot. Lockless — cleanDispatchEntries owns the actual mutation.
-      const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
-      const dispatch = safeJsonObj(dispatchPath);
+      const dispatch = queries.getDispatch();
       const active = Array.isArray(dispatch.active) ? dispatch.active : [];
       const matchFn = (d) => {
         const matchAgent = requestedAgent && d.agent === requestedAgent;
@@ -7227,7 +7043,7 @@ const server = http.createServer(async (req, res) => {
       // Route PID resolution + kill + dispatch removal through the canonical primitive.
       // cleanDispatchEntries resolves the PID from engine/tmp/dispatch-<id>-*/pid-<id>.pid
       // (see shared.findDispatchPidFile), kills outside the dispatch lock, and removes
-      // the entry via mutateDispatch (SQL + JSON mirror in one atomic write).
+      // the entry through the transactional dispatch store.
       // The defunct per-agent status sidecar reads/writes that used to live here are gone
       // (engine/queries.js documents that file no longer exists).
       if (cancelled.length > 0) {
@@ -7751,7 +7567,7 @@ const server = http.createServer(async (req, res) => {
     // path.join. Without this, cat='..' collapses kbCatDir to MINIONS_DIR
     // (path.join normalizes '..') and the next sanitizePath('config.json',
     // MINIONS_DIR) check still passes, allowing safeRead to disclose
-    // config.json / work-items.json / engine state to any browser the
+    // config.json / runtime state to any browser the
     // operator has open. The whitelist also rejects encoded variants
     // (`%2e%2e`, `..%2f`, etc.) since none of those are valid category
     // names. Single source of truth lives in shared.KB_READABLE_CATEGORIES.
@@ -7991,12 +7807,17 @@ const server = http.createServer(async (req, res) => {
 
   async function handlePlansArchiveRead(req, res, match) {
     const file = decodeURIComponent(match[1]);
-    if (file.includes('..') || file.includes('\0')) return jsonReply(res, 400, { error: 'invalid' });
-    // Check prd/archive/ first for .json, then plans/archive/ for .md
-    const archiveDir = file.endsWith('.json') ? path.join(PRD_DIR, 'archive') : path.join(PLANS_DIR, 'archive');
-    let content = safeRead(path.join(archiveDir, file));
-    // Fallback: check the other archive dir
-    if (!content) content = safeRead(path.join(file.endsWith('.json') ? path.join(PLANS_DIR, 'archive') : path.join(PRD_DIR, 'archive'), file));
+    if (file.includes('..') || file.includes('\0') || file.includes('/') || file.includes('\\')) {
+      return jsonReply(res, 400, { error: 'invalid' });
+    }
+    let content = '';
+    if (file.endsWith('.json')) {
+      const row = prdStore.listPrdRows()
+        .find(candidate => candidate.filename === file && (candidate.archived || shared.isPrdArchived(candidate.plan)));
+      if (row) content = JSON.stringify(row.plan, null, 2);
+    } else {
+      content = safeRead(path.join(PLANS_DIR, 'archive', file));
+    }
     if (!content) return jsonReply(res, 404, { error: 'not found' });
     const contentType = file.endsWith('.json') ? 'application/json' : 'text/plain';
     res.setHeader('Content-Type', contentType + '; charset=utf-8');
@@ -8007,17 +7828,30 @@ const server = http.createServer(async (req, res) => {
   async function handlePlansRead(req, res, match) {
     const file = decodeURIComponent(match[1]);
     if (file.includes('..') || file.includes('\0') || file.includes('/') || file.includes('\\')) return jsonReply(res, 400, { error: 'invalid' });
-    let content = safeRead(resolvePlanPath(file));
-    // Fallback: check all directories (prd/, plans/, guides/, archives)
-    if (!content) content = safeRead(path.join(PRD_DIR, file));
-    if (!content) content = safeRead(path.join(PRD_DIR, 'guides', file));
-    if (!content) content = safeRead(path.join(PLANS_DIR, file));
-    if (!content) content = safeRead(path.join(PRD_DIR, 'archive', file));
-    if (!content) content = safeRead(path.join(PLANS_DIR, 'archive', file));
+    let content = '';
+    let resolvedPath = null;
+    if (file.endsWith('.json')) {
+      const row = prdStore.listPrdRows().find(candidate => candidate.filename === file);
+      if (row) {
+        content = JSON.stringify(row.plan, null, 2);
+        res.setHeader('Last-Modified', new Date(row.updatedAt).toISOString());
+        res.setHeader('X-Resolved-Path', `sql:prd/${row.archived ? 'archive/' : ''}${file}`);
+      }
+    } else {
+      const candidates = [
+        resolvePlanPath(file),
+        path.join(PRD_DIR, 'guides', file),
+        path.join(PLANS_DIR, 'archive', file),
+      ];
+      resolvedPath = candidates.find(candidate => fs.existsSync(candidate)) || null;
+      if (resolvedPath) content = safeRead(resolvedPath);
+    }
     if (!content) return jsonReply(res, 404, { error: 'not found' });
-    // Find the actual file path for Last-Modified header + expose resolved relative path
-    const planCandidates = [resolvePlanPath(file), path.join(PRD_DIR, file), path.join(PRD_DIR, 'guides', file), path.join(PLANS_DIR, file), path.join(PRD_DIR, 'archive', file), path.join(PLANS_DIR, 'archive', file)];
-    for (const p of planCandidates) { try { const st = fs.statSync(p); if (st) { res.setHeader('Last-Modified', st.mtime.toISOString()); res.setHeader('X-Resolved-Path', path.relative(MINIONS_DIR, p).replace(/\\/g, '/')); break; } } catch { /* optional */ } }
+    if (resolvedPath) {
+      const stat = fs.statSync(resolvedPath);
+      res.setHeader('Last-Modified', stat.mtime.toISOString());
+      res.setHeader('X-Resolved-Path', path.relative(MINIONS_DIR, resolvedPath).replace(/\\/g, '/'));
+    }
     const contentType = file.endsWith('.json') ? 'application/json' : 'text/plain';
     res.setHeader('Content-Type', contentType + '; charset=utf-8');
     res.setHeader('Cache-Control', 'no-cache');
@@ -8030,9 +7864,8 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       if (!body.file.endsWith('.json')) return jsonReply(res, 400, { error: 'expected a PRD JSON filename (got `' + body.file + '`). To approve a plan, pass prd/<plan>.json, not the source plans/<plan>.md.' });
-      const planPath = resolvePlanPath(body.file);
       let wasStale = false;
-      const plan = mutateJsonFileLocked(planPath, (data) => {
+      const plan = prdStore.mutatePrd(body.file, (data) => {
         if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
         wasStale = !!data.planStale;
         data.status = 'approved';
@@ -8042,7 +7875,7 @@ const server = http.createServer(async (req, res) => {
         delete data.planStale;
         delete data._completionNotified;
         return data;
-      }, { defaultValue: {} });
+      });
 
       // W-mqacrzis0003df4a + W-mqfevwr60018bd09 — Fresh source-plan
       // staleness check (content-hash gated). Approve is the last gate
@@ -8064,13 +7897,10 @@ const server = http.createServer(async (req, res) => {
       // Resume paused work items across all projects
       let resumed = 0;
       const resumedItemIds = [];
-      const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-      for (const proj of PROJECTS) {
-        wiPaths.push(shared.projectWorkItemsPath(proj));
-      }
-      for (const wiPath of wiPaths) {
+      const workItemScopes = ['central', ...PROJECTS];
+      for (const scope of workItemScopes) {
         try {
-          mutateJsonFileLocked(wiPath, (items) => {
+          mutateWorkItems(scope, (items) => {
             if (!Array.isArray(items)) return items;
             for (const w of items) {
               if (w.sourcePlan === body.file && w.status === WI_STATUS.PAUSED && w._pausedBy === 'prd-pause') {
@@ -8082,19 +7912,18 @@ const server = http.createServer(async (req, res) => {
               }
             }
             return items;
-          }, { defaultValue: [] });
+          });
         } catch (e) { console.error('resume work items:', e.message); }
       }
 
       // Clear dispatch completed entries for resumed items so they aren't dedup-blocked
       if (resumedItemIds.length > 0) {
-        const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
         const resumedSet = new Set(resumedItemIds);
-        mutateJsonFileLocked(dispatchPath, (dispatch) => {
+        dispatchMod.mutateDispatch((dispatch) => {
           dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
           dispatch.completed = dispatch.completed.filter(d => !resumedSet.has(d.meta?.item?.id));
           return dispatch;
-        }, { defaultValue: { pending: [], active: [], completed: [] } });
+        });
       }
 
       // Diff-aware PRD update: if plan was stale (source .md revised), dispatch plan-to-prd
@@ -8104,7 +7933,7 @@ const server = http.createServer(async (req, res) => {
         const config = queries.getConfig();
         const allWorkItems = queries.getWorkItems(config);
         const planWis = allWorkItems.filter(w => w.sourcePlan === body.file && w.itemType !== 'pr' && w.itemType !== 'verify');
-        const allPrs = PROJECTS.flatMap(p => shared.safeJsonArr(shared.projectPrPath(p)));
+        const allPrs = PROJECTS.flatMap(p => shared.readPullRequests(p));
         const prLinks = shared.getPrLinks();
         const implContext = (plan.missing_features || []).map(f => {
           const wi = planWis.find(w => w.id === f.id);
@@ -8146,19 +7975,18 @@ const server = http.createServer(async (req, res) => {
   // cleanup; pause never stopped regeneration.)
   function stopPlanMaterializedWork(prdFile, prdSourcePlan, opts) {
     const targetStatus = opts.targetStatus;
-    const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-    for (const proj of PROJECTS) wiPaths.push(shared.projectWorkItemsPath(proj));
+    const workItemScopes = ['central', ...PROJECTS];
 
     // Step 1: find dispatched item ids (read-only, no lock).
     const dispatchedItemIds = new Set();
-    for (const wiPath of wiPaths) {
+    for (const scope of workItemScopes) {
       try {
-        for (const w of safeJsonArr(wiPath)) {
+        for (const w of shared.readWorkItems(scope)) {
           if (w.sourcePlan !== prdFile) continue;
           if (w.completedAt || DONE_STATUSES.has(w.status)) continue;
           if (w.status === WI_STATUS.DISPATCHED && w.id) dispatchedItemIds.add(w.id);
         }
-      } catch { /* file may not exist */ }
+      } catch { /* scope may be unavailable */ }
     }
 
     // Step 2: kill active dispatches via the canonical primitive (resolves PIDs from
@@ -8172,11 +8000,11 @@ const server = http.createServer(async (req, res) => {
       });
     }
 
-    // Step 3: transition WIs per path (each lock held briefly, no nesting).
+    // Step 3: transition WIs per scope.
     let affected = 0;
-    for (const wiPath of wiPaths) {
+    for (const scope of workItemScopes) {
       try {
-        mutateWorkItems(wiPath, items => {
+        mutateWorkItems(scope, items => {
           for (const w of items) {
             if (w.sourcePlan !== prdFile) continue;
             if (w.completedAt || DONE_STATUSES.has(w.status)) continue;
@@ -8198,8 +8026,7 @@ const server = http.createServer(async (req, res) => {
     // stopped. (delete handles the DONE plan-to-prd WI separately to revert to draft.)
     if (prdSourcePlan) {
       try {
-        const centralPath = path.join(MINIONS_DIR, 'work-items.json');
-        mutateWorkItems(centralPath, items => {
+        mutateWorkItems('central', items => {
           for (const w of items) {
             if (w.type === WORK_TYPE.PLAN_TO_PRD && w.planFile === prdSourcePlan &&
                 !DONE_STATUSES.has(w.status) && w.status !== WI_STATUS.CANCELLED) {
@@ -8218,14 +8045,13 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       if (!body.file.endsWith('.json')) return jsonReply(res, 400, { error: 'expected a PRD JSON filename (got `' + body.file + '`). Pass prd/<plan>.json, not the source plans/<plan>.md.' });
-      const planPath = resolvePlanPath(body.file);
       let prdSourcePlan = null;
-      const updated = mutateJsonFileLocked(planPath, (plan) => {
+      const updated = prdStore.mutatePrd(body.file, (plan) => {
         if (!plan || Array.isArray(plan) || typeof plan !== 'object') plan = {};
         plan.status = 'paused';
         plan.pausedAt = new Date().toISOString();
         return plan;
-      }, { defaultValue: {} });
+      });
       prdSourcePlan = updated?.source_plan || null;
 
       // Propagate pause to materialized work items across all projects + cancel the
@@ -8279,15 +8105,14 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       if (!body.file.endsWith('.json')) return jsonReply(res, 400, { error: 'expected a PRD JSON filename (got `' + body.file + '`). Pass prd/<plan>.json, not the source plans/<plan>.md.' });
-      const planPath = resolvePlanPath(body.file);
-      const plan = mutateJsonFileLocked(planPath, (data) => {
+      const plan = prdStore.mutatePrd(body.file, (data) => {
         if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
         data.status = 'rejected';
         data.rejectedAt = new Date().toISOString();
         data.rejectedBy = body.rejectedBy || os.userInfo().username;
         if (body.reason) data.rejectionReason = body.reason;
         return data;
-      }, { defaultValue: {} });
+      });
 
       // RC3: reject used to flip only the PRD status — its materialized work items
       // kept dispatching and any active agent kept running, and a pending plan-to-prd
@@ -8307,26 +8132,26 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       if (!body.source) return jsonReply(res, 400, { error: 'source required' });
-      const planPath = resolvePlanPath(body.source);
-      if (!statePathExists(planPath)) return jsonReply(res, 404, { error: 'plan file not found' });
-      const plan = safeJsonObj(planPath);
+      if (!body.source.endsWith('.json')) return jsonReply(res, 400, { error: 'expected a PRD JSON filename' });
+      const plan = prdStore.readPrd(body.source);
+      if (!plan) return jsonReply(res, 404, { error: 'plan not found' });
       const planItems = plan.missing_features || [];
 
       let reset = 0, kept = 0, newCount = 0;
       const deletedItemIds = [];
 
       // Scan all work item sources for materialized items from this plan
-      const wiPaths = [{ path: path.join(MINIONS_DIR, 'work-items.json'), label: 'central' }];
+      const workItemScopes = [{ scope: 'central', label: 'central' }];
       for (const proj of PROJECTS) {
-        wiPaths.push({ path: shared.projectWorkItemsPath(proj), label: proj.name });
+        workItemScopes.push({ scope: proj, label: proj.name });
       }
 
       // Track which plan items have materialized work items
       const materializedPlanItemIds = new Set();
 
-      for (const wiInfo of wiPaths) {
+      for (const wiInfo of workItemScopes) {
         try {
-          mutateWorkItems(wiInfo.path, items => {
+          mutateWorkItems(wiInfo.scope, items => {
             const filtered = [];
             for (const w of items) {
               if (w.sourcePlan === body.source) {
@@ -8372,7 +8197,7 @@ const server = http.createServer(async (req, res) => {
       }
       if (orphanPendingIds.size > 0) {
         try {
-          mutateJsonFileLocked(planPath, (current) => {
+          prdStore.mutatePrd(body.source, (current) => {
             if (!current || !Array.isArray(current.missing_features)) return current;
             const stamp = new Date().toISOString();
             for (const f of current.missing_features) {
@@ -8402,50 +8227,37 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
-      shared.sanitizePath(body.file, body.file.endsWith('.json') ? PRD_DIR : PLANS_DIR);
-      const planPath = resolvePlanPath(body.file);
-      if (!statePathExists(planPath)) return jsonReply(res, 404, { error: 'plan not found' });
-      // Read plan content before deleting — needed for worktree cleanup and source_plan
+      const isPrd = body.file.endsWith('.json');
+      let planPath = null;
       let planObj = null;
       let prdSourcePlan = null;
-      if (body.file.endsWith('.json')) {
-        try { planObj = safeJsonObj(planPath); prdSourcePlan = planObj?.source_plan || null; } catch {}
+      let archivedPrd = false;
+      if (isPrd) {
+        planObj = prdStore.readPrd(body.file);
+        if (!planObj) {
+          archivedPrd = true;
+          planObj = prdStore.readPrd(body.file, { archived: true });
+        }
+        if (!planObj) return jsonReply(res, 404, { error: 'plan not found' });
+        prdSourcePlan = planObj.source_plan || null;
+      } else {
+        planPath = resolvePlanPath(body.file);
+        if (!statePathExists(planPath)) return jsonReply(res, 404, { error: 'plan not found' });
       }
       // Clean up worktrees before deleting work items (needs branch info from work items)
       try {
         const { cleanupPlanWorktrees } = require('./engine/lifecycle');
         cleanupPlanWorktrees(body.file, planObj || {}, PROJECTS, queries.getConfig());
       } catch (e) { console.error('plan worktree cleanup:', e.message); }
-      safeUnlink(planPath);
-      // Phase 10 step 2 — a deleted PRD must also leave SQL, or the read-flip
-      // (step 3) would resurrect it from a stale mirror row. Best-effort; no-op
-      // for non-PRD paths (parsePrdPath returns null for plan .md deletes).
-      if (body.file.endsWith('.json')) prdStore.deletePrd(planPath);
-      // Neutralize the `.backup` sidecar so `safeJson` auto-restore can't
-      // RESURRECT the PRD we just deleted (the live file is gone, but a stray
-      // `prd/<plan>.json.backup` would be auto-restored on the next safeJson read
-      // — the PRD comes back, with its prior `status: approved/active`, and the
-      // materializer re-dispatches its work items). Mirrors the Archive handler's
-      // backup cleanup (handlePlansArchive). A PRD delete must remove the restore
-      // fuel, not just the live file.
-      if (body.file.endsWith('.json')) {
-        try {
-          const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
-          if (!backupCleanup.ok) {
-            console.warn(`Delete backup cleanup failed for ${body.file}: unlink (${backupCleanup.unlinkError}) / neutralize (${backupCleanup.writeError})`);
-          }
-        } catch (e) { console.warn(`Delete backup cleanup threw for ${body.file}: ${e.message}`); }
-      }
+      if (isPrd) prdStore.deletePrd(body.file, { archived: archivedPrd });
+      else safeUnlink(planPath);
 
       // Clean up materialized work items from all projects + central
       let cleaned = 0;
-      const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-      for (const proj of PROJECTS) {
-        wiPaths.push(shared.projectWorkItemsPath(proj));
-      }
-      for (const wiPath of wiPaths) {
+      const workItemScopes = ['central', ...PROJECTS];
+      for (const scope of workItemScopes) {
         try {
-          mutateWorkItems(wiPath, items => {
+          mutateWorkItems(scope, items => {
             const filtered = items.filter(w => w.sourcePlan !== body.file);
             if (filtered.length < items.length) {
               cleaned += items.length - filtered.length;
@@ -8465,8 +8277,7 @@ const server = http.createServer(async (req, res) => {
       // If deleting a PRD .json, reset the plan-to-prd work item so the source .md reverts to draft
       if (prdSourcePlan) {
         try {
-          const centralPath = path.join(MINIONS_DIR, 'work-items.json');
-          mutateWorkItems(centralPath, items => {
+          mutateWorkItems('central', items => {
             for (const w of items) {
               if (w.type === WORK_TYPE.PLAN_TO_PRD && DONE_STATUSES.has(w.status) && w.planFile === prdSourcePlan) {
                 w.status = WI_STATUS.CANCELLED;
@@ -8488,23 +8299,18 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
       const isPrd = body.file.endsWith('.json');
-      shared.sanitizePath(body.file, isPrd ? PRD_DIR : PLANS_DIR);
-      const planPath = resolvePlanPath(body.file);
-      if (!statePathExists(planPath)) return jsonReply(res, 404, { error: 'plan not found' });
-
-      // Phase 10 step 4.2b: a PRD is archived IN PLACE (flag flip via
-      // _archivePrdPostProcess — the json stays in prd/, no move, so the
-      // live↔archive basename-collision class / footgun #7 is gone). Only the
-      // .md plan still physically moves to plans/archive/.
-      let archivePath;
+      if (!isPrd) shared.sanitizePath(body.file, PLANS_DIR);
+      let planPath = null;
       if (isPrd) {
-        archivePath = planPath; // in-place — do not move the PRD json
+        if (!prdStore.readPrd(body.file)) return jsonReply(res, 404, { error: 'plan not found' });
       } else {
+        planPath = resolvePlanPath(body.file);
+        if (!statePathExists(planPath)) return jsonReply(res, 404, { error: 'plan not found' });
         const archiveDir = path.join(PLANS_DIR, 'archive');
         // DATA-LOSS GUARD: moveFileNoClobber dedupes the destination so a same-
         // basename collision can't silently destroy a previously-archived plan +
         // its completed work-item history. Bumps to -2/-3 instead of overwriting.
-        archivePath = shared.moveFileNoClobber(planPath, archiveDir, body.file);
+        shared.moveFileNoClobber(planPath, archiveDir, body.file);
       }
 
       let archivedSource = null;
@@ -8515,8 +8321,6 @@ const server = http.createServer(async (req, res) => {
       if (isPrd) {
         const result = _archivePrdPostProcess({
           planFile: body.file,
-          archivePath,
-          planPath,
           plansDir: PLANS_DIR,
         });
         archivedSource = result.archivedSource;
@@ -8527,38 +8331,17 @@ const server = http.createServer(async (req, res) => {
         // archive any PRD whose `source_plan` points back at it. Without this,
         // the dashboard still renders the PRD as a status-completed plan card
         // forever (real incident: killswitches-and-granular-controls.md →
-        // minions-opg-2026-06-10-2.json). The per-PRD status-flip / sidecar /
-        // source-plan-move steps are delegated to _archivePrdPostProcess so
-        // both branches share the per-concern try/catch granularity Dallas
-        // shipped for the PRD branch in W-mqa13ulk0002def5 (PR #3222) — the
-        // helper's source-plan move is a safe no-op here because the outer
-        // handler already renamed body.file into plans/archive/.
-        const prdFiles = prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
-        for (const prdFile of prdFiles) {
-          const prdLivePath = path.join(PRD_DIR, prdFile);
-          let prd = null;
-          try {
-            prd = safeJsonObj(prdLivePath);
-          } catch (e) {
-            const warning = `Archive could not read PRD ${prdFile}: ${e.message}`;
-            archiveWarnings.push(warning);
-            console.warn(warning);
-            continue;
-          }
+        // minions-opg-2026-06-10-2.json).
+        const prdRows = prdStore.listPrdRows().filter(row => !row.archived);
+        for (const { filename: prdFile, plan: prd } of prdRows) {
           // Canonical match (prefix/dir-tolerant): a raw `prd.source_plan !==
           // body.file` skipped PRDs whose source_plan carried the legacy
           // `plans/` prefix, archiving the plan but NOT its PRD — the plan↔PRD
           // status desync behind the "old PRDs came back" resurrection.
           if (!prd || !shared.prdMatchesSourcePlan(prd.source_plan, body.file)) continue;
 
-          // Phase 10 step 4.2b: flag the PRD archived IN PLACE (no move). The
-          // outer handler already moved the .md to plans/archive/, so the
-          // helper's (c) source-plan move is a no-op; (a) flips the flag (dual-
-          // writing SQL) and (b) skips backup-neutralize since the file stayed.
           const cascadeResult = _archivePrdPostProcess({
             planFile: prdFile,
-            archivePath: prdLivePath,
-            planPath: prdLivePath,
             plansDir: PLANS_DIR,
           });
           archiveWarnings.push(...cascadeResult.archiveWarnings);
@@ -8570,10 +8353,10 @@ const server = http.createServer(async (req, res) => {
       // Cancel pending work items linked to this plan so the engine stops
       // dispatching for an archived plan. Done items are preserved as history.
       let cancelledItems = 0;
-      const wiPaths = [path.join(MINIONS_DIR, 'work-items.json'), ...PROJECTS.map(p => shared.projectWorkItemsPath(p))];
-      for (const wiPath of wiPaths) {
+      const workItemScopes = ['central', ...PROJECTS];
+      for (const scope of workItemScopes) {
         try {
-          mutateWorkItems(wiPath, items => {
+          mutateWorkItems(scope, items => {
             for (const w of items) {
               if (w.sourcePlan !== body.file) continue;
               if (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.QUEUED) {
@@ -8605,66 +8388,43 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
-      try { shared.sanitizePath(body.file, body.file.endsWith('.json') ? PRD_DIR : PLANS_DIR); }
+      try {
+        if (!body.file.endsWith('.json')) shared.sanitizePath(body.file, PLANS_DIR);
+      }
       catch { return jsonReply(res, 400, { error: 'invalid filename' }); }
       const isJson = body.file.endsWith('.json');
-      const targetDir = isJson ? PRD_DIR : PLANS_DIR;
-      const archivePath = path.join(targetDir, 'archive', body.file);
-      const livePath = path.join(targetDir, body.file);
-      // Phase 10 step 4.2b: a PRD can be archived two ways now — legacy
-      // (physically in <dir>/archive/) or in-place (in <dir>/ with the archived
-      // flag set). Restore from whichever it is.
-      let liveDest;
-      // Existence probes only — NEVER used as the write payload. The actual
-      // restore below (prdStore.restorePrdFromArchive) re-reads the archived
-      // row fresh inside its own transaction immediately before writing, so a
-      // concurrent engine write to that row between this probe and the write
-      // can't be clobbered by a stale in-memory snapshot (W-mrenu075000a94c9).
-      const archivedPrdExists = isJson ? prdStore.readPrd(archivePath) != null : false;
-      const activePrdData = isJson ? prdStore.readPrd(livePath) : null;
-      if (isJson && archivedPrdExists) {
-        const restored = prdStore.restorePrdFromArchive(body.file);
-        if (!restored) return jsonReply(res, 404, { error: 'File not found in archive' });
-        liveDest = livePath;
-      } else if (fs.existsSync(archivePath)) {
-        // DATA-LOSS GUARD: restoring must not clobber a LIVE plan/PRD of the same
-        // basename (renameSync overwrites). moveFileNoClobber bumps the restored
-        // name instead so the existing live file survives.
-        liveDest = shared.moveFileNoClobber(archivePath, targetDir, body.file);
-      } else if (isJson && activePrdData && shared.isPrdArchived(activePrdData)) {
-        liveDest = livePath; // in-place flag-archived — already in prd/, just clear the flag below
-      } else {
-        return jsonReply(res, 404, { error: 'File not found in archive' });
-      }
-      // Clear the archived flag/status so the unarchived PRD renders LIVE again.
-      // Archived-ness is the FLAG now (4.2a), so moving the file back is no longer
-      // enough — a legacy PRD carries status='archived' and would still render
-      // archived without this. Dual-writes the cleared state into SQL.
-      if (isJson) {
-        try {
-          mutateJsonFileLocked(liveDest, (d) => {
-            if (!d || typeof d !== 'object' || Array.isArray(d)) return d;
-            if (d.status === 'archived') d.status = 'active';
-            delete d.archived;
-            delete d.archivedAt;
-            return d;
-          }, { skipWriteIfUnchanged: true });
-        } catch (e) { console.warn(`Unarchive flag-clear failed for ${body.file}: ${e.message}`); }
-      }
-
-      // Also unarchive linked source plan
+      let restoredAs = body.file;
       let unarchivedSource = null;
       if (isJson) {
+        const archivedRow = prdStore.readPrd(body.file, { archived: true });
+        let prd = archivedRow
+          ? prdStore.restorePrdFromArchive(body.file)
+          : prdStore.readPrd(body.file);
+        if (!prd || (!archivedRow && !shared.isPrdArchived(prd))) {
+          return jsonReply(res, 404, { error: 'File not found in archive' });
+        }
+        prdStore.mutatePrd(body.file, (data) => {
+          if (data.status === 'archived') data.status = 'active';
+          delete data.archived;
+          delete data.archivedAt;
+          return data;
+        });
+        prd = prdStore.readPrd(body.file);
         try {
-          const prd = safeJson(liveDest);
           if (prd?.source_plan) {
-            const mdArchivePath = path.join(PLANS_DIR, 'archive', prd.source_plan);
+            const sourcePlan = shared.sourcePlanKey(prd.source_plan);
+            const mdArchivePath = path.join(PLANS_DIR, 'archive', sourcePlan);
             if (fs.existsSync(mdArchivePath)) {
-              const liveMdDest = shared.moveFileNoClobber(mdArchivePath, PLANS_DIR, prd.source_plan);
+              const liveMdDest = shared.moveFileNoClobber(mdArchivePath, PLANS_DIR, sourcePlan);
               unarchivedSource = path.basename(liveMdDest);
             }
           }
         } catch { /* optional */ }
+      } else {
+        const archivePath = path.join(PLANS_DIR, 'archive', body.file);
+        if (!fs.existsSync(archivePath)) return jsonReply(res, 404, { error: 'File not found in archive' });
+        const liveDest = shared.moveFileNoClobber(archivePath, PLANS_DIR, body.file);
+        restoredAs = path.basename(liveDest);
       }
 
       invalidateStatusCache();
@@ -8672,7 +8432,6 @@ const server = http.createServer(async (req, res) => {
       // `restoredAs` reflects the actual restored basename: moveFileNoClobber
       // bumps to <name>-2 when a live file of the same name already exists, so
       // the client isn't misled into expecting body.file when it differs.
-      const restoredAs = path.basename(liveDest);
       const payload = { ok: true, unarchivedSource };
       if (restoredAs !== body.file) payload.restoredAs = restoredAs;
       return jsonReply(res, 200, payload);
@@ -8684,20 +8443,18 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       if (!body.file || !body.feedback) return jsonReply(res, 400, { error: 'file and feedback required' });
       if (!body.file.endsWith('.json')) return jsonReply(res, 400, { error: 'expected a PRD JSON filename (got `' + body.file + '`). Pass prd/<plan>.json, not the source plans/<plan>.md.' });
-      const planPath = resolvePlanPath(body.file);
-      const plan = mutateJsonFileLocked(planPath, (data) => {
+      const plan = prdStore.mutatePrd(body.file, (data) => {
         if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
         data.status = 'revision-requested';
         data.revision_feedback = body.feedback;
         data.revisionRequestedAt = new Date().toISOString();
         data.revisionRequestedBy = body.requestedBy || os.userInfo().username;
         return data;
-      }, { defaultValue: {} });
+      });
 
       // Create a work item to revise the plan
-      const wiPath = path.join(MINIONS_DIR, 'work-items.json');
       const id = 'W-' + shared.uid();
-      mutateWorkItems(wiPath, items => {
+      mutateWorkItems('central', items => {
         items.push({
           id, title: 'Revise plan: ' + (plan.plan_summary || body.file),
           type: WORK_TYPE.PLAN_TO_PRD, priority: 'high',
@@ -8718,11 +8475,10 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       if (!body.file) return jsonReply(res, 400, { error: 'file required' });
-      const planPath = resolvePlanPath(body.file);
-      const planContent = safeRead(planPath);
-      if (!planContent) return jsonReply(res, 404, { error: 'plan not found' });
-
-      const plan = JSON.parse(planContent);
+      if (!body.file.endsWith('.json')) return jsonReply(res, 400, { error: 'expected a PRD JSON filename' });
+      const plan = prdStore.readPrd(body.file);
+      if (!plan) return jsonReply(res, 404, { error: 'plan not found' });
+      const planReference = `SQL PRD ${body.file}`;
       const projectName = plan.project || 'Unknown';
 
       // Build the session launch script
@@ -8730,10 +8486,10 @@ const server = http.createServer(async (req, res) => {
       let sysPrompt;
       try {
         sysPrompt = fs.readFileSync(path.join(MINIONS_DIR, 'prompts', 'plan-advisor-system.md'), 'utf8')
-          .replace(/\{\{plan_path\}\}/g, planPath)
+          .replace(/\{\{plan_path\}\}/g, planReference)
           .replace(/\{\{project_name\}\}/g, projectName);
       } catch {
-        sysPrompt = `You are a Plan Advisor. The plan is at ${planPath} for project ${projectName}. Help the user review and approve it.`;
+        sysPrompt = `You are a Plan Advisor. The plan is ${planReference} for project ${projectName}. Help the user review and approve it.`;
       }
 
       const initialPrompt = `Here's the plan awaiting your review:
@@ -9585,7 +9341,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       _clearCcLiveStream(tabId);
     }
     // P-c2sess-1d8e: lock single-session reset against concurrent updateSession writes.
-    mutateJsonFileLocked(CC_SESSION_PATH, () => ccSession, { defaultValue: {} });
+    persistCcSession();
     return jsonReply(res, 200, { ok: true });
   }
 
@@ -9619,12 +9375,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   async function handleCCSessionDelete(req, res, match) {
     const id = match?.[1];
     if (!id) return jsonReply(res, 400, { error: 'id required' });
-    // P-c2sess-1d8e: one locked RMW so a concurrent upsert from the streaming
-    // handler cannot resurrect the deleted tab between read and write.
-    mutateJsonFileLocked(CC_SESSIONS_PATH, (raw) => {
+    smallStateStore.applyCcSessionsMutation((raw) => {
       const sessions = _filterCcTabSessions(raw);
       return sessions.filter(s => s.id !== id);
-    }, { defaultValue: [] });
+    });
     // Sub-task C of W-mp2w003600196c51: tear down the persistent ACP worker
     // for this tab so we don't leak a Copilot process after the user closes
     // the tab. closeTab is a no-op when the pool has no entry for the tabId,
@@ -9814,7 +9568,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       // W-mrb1a3950003d9ea — flat, stable label (no per-watch-id interpolation).
       // Every other _engine category (kb-sweep, consolidation, command-center, …)
       // uses one flat label; a dynamic watchId suffix here used to mint a brand-new
-      // permanent metrics.json._engine key per watch firing (20+ confirmed live).
+      // permanent metrics category per watch firing (20+ confirmed live).
       const label = 'watch-cc-triage';
 
       const model = CONFIG.engine?.ccModel || shared.ENGINE_DEFAULTS.ccModel;
@@ -10692,10 +10446,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const _persistTabId = body.tabId;
         if (_persistTabId && responseSessionId) {
           try {
-            // P-c2sess-1d8e: one locked RMW so concurrent multi-tab streams can't
-            // race on read+modify+write — both upsert paths share the lock.
             const preview = (body.message || '').slice(0, 80);
-            mutateJsonFileLocked(CC_SESSIONS_PATH, (raw) => {
+            smallStateStore.applyCcSessionsMutation((raw) => {
               const sessions = _filterCcTabSessions(raw);
               const existing = sessions.find(s => s.id === _persistTabId);
               if (existing) {
@@ -10709,7 +10461,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
                 sessions.push({ id: _persistTabId, title: (body.message || 'New chat').slice(0, 40), sessionId: responseSessionId, createdAt: new Date(now).toISOString(), lastActiveAt: new Date(now).toISOString(), turnCount: 1, preview, _promptHash: _ccPromptHash, runtime: currentRuntime });
               }
               return sessions;
-            }, { defaultValue: [] });
+            });
           } catch { /* non-critical */ }
         }
 
@@ -10899,9 +10651,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         participants: Array.isArray(schedForRun.participants) ? schedForRun.participants : [],
       });
     } else {
-      const centralPath = path.join(MINIONS_DIR, 'work-items.json');
       let duplicate = null;
-      mutateJsonFileLocked(centralPath, (items) => {
+      mutateWorkItems('central', (items) => {
         if (!Array.isArray(items)) items = [];
         duplicate = items.find(i =>
           i._scheduleId === item._scheduleId &&
@@ -10911,7 +10662,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         );
         if (!duplicate) items.push(item);
         return items;
-      }, { defaultValue: [] });
+      });
       if (duplicate) {
         return jsonReply(res, 409, {
           error: 'Schedule already has an active work item',
@@ -11091,19 +10842,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           name: p.name,
           localPath: p.localPath || null,
           mainBranch: p.mainBranch || null,
-          // P-a3f9b207 — surface checkoutMode so the Settings UI can pre-fill
-          // the per-project dropdown. resolveCheckoutMode honors the legacy
-          // worktreeMode field; 'worktree' (default) or 'live'.
-          checkoutMode: shared.resolveCheckoutMode(p),
-          // W-mr9mx93d000x1dda — surface the hybrid liveValidation config
-          // (type(s) + autoDispatch) so the Settings → Projects checkout-mode
-          // control can pre-fill its Hybrid sub-panel authoritatively (mirrors
-          // the /api/status project mapping the Projects-bar picker reads).
-          // Only meaningful under checkoutMode:'live'; null/false otherwise.
-          liveValidationType: (shared.resolveCheckoutMode(p) === 'live' && p.liveValidation && p.liveValidation.type)
-            ? p.liveValidation.type
-            : null,
-          liveValidationAutoDispatch: !!(shared.resolveCheckoutMode(p) === 'live' && p.liveValidation && p.liveValidation.autoDispatch === true),
+          ..._projectCheckoutConfigView(p),
           // W-mqtvnnj1000357fa — surface the RAW per-project auto-stash override
           // (true / false / undefined) so the Settings UI can pre-select the
           // tri-state dropdown. Undefined means "use fleet default"
@@ -12117,7 +11856,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
   // ── Managed processes API (P-4b8d2e57, plan W-mp7k1r760003b5dd item 4) ──
   // List + by-name + kill + restart for the engine-owned managed-spawn
-  // services (engine/managed-processes.json). Mirrors the keep-processes
+  // services (SQL managed-process state). Mirrors the keep-processes
   // pattern above but lives a layer deeper because the state is engine-side
   // (not per-agent sidecars).
 
@@ -12416,7 +12155,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const projectName = runbook.project || target.owner_project || '';
       const resolveTarget = resolveWorkItemsCreateTarget(projectName);
       if (resolveTarget.error) return jsonReply(res, 400, { error: resolveTarget.error }, req);
-      const wiPath = resolveTarget.wiPath;
+      const wiScope = resolveTarget.scope;
       const targetProject = resolveTarget.project;
 
       // Create run record BEFORE the WI so we can stamp the WI with qaRunId.
@@ -12452,12 +12191,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       if (targetProject) wi.project = targetProject.name;
       if (body.agent && typeof body.agent === 'string' && body.agent.trim()) wi.agent = body.agent.trim();
 
-      // Atomic WI creation: mutateWorkItems holds the file lock for the entire
-      // append. createRun above is its own lock — order is intentional so a
+      // createRun and the work-item append are separate transactions; order is
+      // intentional so a
       // crash between the two leaves the run as `pending` (recoverable) rather
       // than orphaning a WI with no run record.
       let added = false;
-      mutateWorkItems(wiPath, (items) => {
+      mutateWorkItems(wiScope, (items) => {
         if (!Array.isArray(items)) items = [];
         if (!items.some(i => i && i.id === wiId)) {
           items.push(wi);
@@ -12633,7 +12372,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   }
 
   // W-mpxp90xs000i5732 — DELETE /api/qa/runs/<id>. Hard-delete: removes the
-  // run from engine/qa-runs.json AND best-effort wipes the on-disk artifact
+  // run from SQL QA state and best-effort wipes the on-disk artifact
   // directory under engine/qa-artifacts/<runId>/. Terminal-only — refuses
   // pending/running runs with 409. Caller must cancel/complete the run via
   // the lifecycle helpers before deletion. CSRF/Origin gate is applied by
@@ -12721,7 +12460,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   // Thin HTTP wrappers over engine/qa-sessions.js + engine/qa-runners.js. The
   // lifecycle (state machine, work-item builders, dispatch chain) lives in
   // those modules; these handlers translate HTTP into the right call,
-  // resolve project/wiPath the same way handleQaRunbookRun does, and shape
+  // resolve project/scope the same way handleQaRunbookRun does, and shape
   // qa-sessions thrown errors into 400/404/409 instead of 500.
   //
   // Endpoint summary:
@@ -12752,22 +12491,17 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return 500;
   }
 
-  // Resolve the (project, wiPath) tuple for a session create/approve/edit
-  // request. session.spec.project (or the create-time project field) decides
-  // which work-items.json receives the new WI. central → root-level
-  // work-items.json. Returns { error } on resolution failure so the handler
-  // can reply 400.
+  // Resolve the project and SQL scope for QA work items.
   function _qaSessionsResolveTarget(projectName) {
     const target = resolveWorkItemsCreateTarget(projectName || '');
     if (target.error) return { error: target.error };
-    return { wiPath: target.wiPath, project: target.project ? target.project.name : null };
+    return { scope: target.scope, project: target.project ? target.project.name : null };
   }
 
   // W-mpq6xqzj000606d0 — Multi-project resolver. Walks each requested project
   // through resolveWorkItemsCreateTarget, returning either the full list of
-  // {wiPath, project} entries (with the first treated as primary) or
-  // { error } on the first failure. Accepts the canonical `projects: string[]`
-  // and falls back to the legacy single `project` string.
+  // {scope, project} entries (with the first treated as primary) or
+  // { error } on the first failure.
   function _qaSessionsResolveTargets(body) {
     const list = Array.isArray(body && body.projects) && body.projects.length > 0
       ? body.projects.slice()
@@ -12815,7 +12549,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       let setupWiId = null;
       try {
         setupWiId = qaSessions.queueSetup(session.id, {
-          resolvedTargets: resolution.targets.map(t => ({ project: t.project, wiPath: t.wiPath })),
+          resolvedTargets: resolution.targets.map(t => ({ project: t.project, scope: t.scope })),
         });
       } catch (e) {
         // queueSetup throws when pending→spawning is rejected (createSession
@@ -12923,7 +12657,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       let setupWiId = null;
       try {
         setupWiId = qaSessions.queueSetup(session.id, {
-          resolvedTargets: resolution.targets.map(t => ({ project: t.project, wiPath: t.wiPath })),
+          resolvedTargets: resolution.targets.map(t => ({ project: t.project, scope: t.scope })),
         });
       } catch (e) {
         return jsonReply(res, _qaSessionsErrorToStatus(e), {
@@ -13067,7 +12801,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       let executeWiId;
       try {
         executeWiId = qaSessions.approveDraft(session.id, {
-          wiPath: resolved.wiPath,
+          scope: resolved.scope,
           qaRunId: run.id,
           project: resolved.project,
         });
@@ -13106,7 +12840,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       let draftWiId;
       try {
         draftWiId = qaSessions.editDraft(session.id, {
-          wiPath: resolved.wiPath,
+          scope: resolved.scope,
           feedback,
           project: resolved.project,
         });
@@ -13260,6 +12994,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
     // Status & health
     { method: 'GET', path: '/api/status', desc: 'Full dashboard status snapshot (agents, PRDs, work items, dispatch, etc.)', handler: handleStatus },
+    { method: 'GET', path: '/api/constellation/v1/snapshot', desc: 'Versioned metadata-only full snapshot for the local Constellation mirror', handler: (req, res) => {
+      return serveFreshJson(req, res, {
+        tag: `constellation-v1-${_dashboardVersion.codeVersion || 'unknown'}-${_dashboardVersion.codeCommit || 'unknown'}`,
+        inputs: [CONFIG_PATH, queries.CONTROL_PATH, INBOX_DIR, AGENTS_DIR],
+        builder: _buildConstellationBridgeSnapshot,
+      });
+    }},
     // Raw state-file passthrough (no /api/ prefix — this serves files, not API
     // responses). Allowlisted top-level dirs only; mtime+size ETag → 304.
     { method: 'GET', path: /^\/state\/.+/, desc: 'Serve a raw state file (or directory listing) from MINIONS_DIR with mtime/size ETag', handler: handleStateRead },
@@ -13272,34 +13013,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         tag: 'agents',
         inputs: [
           CONFIG_PATH,
-          path.join(ENGINE_DIR, 'dispatch.json'),
           INBOX_DIR,
           AGENTS_DIR,
         ],
         builder: () => getAgents(),
       });
     }},
-    { method: 'GET', path: '/api/work-items', desc: 'Fully-enriched work items (per-project files joined + dispatch/PR cross-reference) — fresh on every request; description hard-capped + acceptanceCriteria/references replaced with *Count integers (W-mq5xg5e9000nec0e); detail modal lazy-loads the full record via GET /api/work-items/<id>', handler: (req, res) => {
-      const config = queries.getConfig();
-      const projects = config.projects || [];
-      const inputs = [
-        CONFIG_PATH,
-        path.join(ENGINE_DIR, 'dispatch.json'),
-        // Central work-items.json at MINIONS_DIR root — backs the 'central'
-        // scope (schedule/pipeline/CC-created rootless WIs, per
-        // work-items-store.js#_filePathForScope). Without this, a new
-        // central-scope WI never busts the ETag until dispatch.json changes.
-        shared.centralWorkItemsPath(MINIONS_DIR),
-      ];
-      for (const p of projects) {
-        if (p && p.name) {
-          inputs.push(path.join(MINIONS_DIR, 'projects', p.name, 'work-items.json'));
-          inputs.push(path.join(MINIONS_DIR, 'projects', p.name, 'pull-requests.json'));
-        }
-      }
+    { method: 'GET', path: '/api/work-items', desc: 'Fully-enriched SQL-backed work items joined with dispatch/PR state — fresh on every request; description hard-capped + acceptanceCriteria/references replaced with *Count integers (W-mq5xg5e9000nec0e); detail modal lazy-loads the full record via GET /api/work-items/<id>', handler: (req, res) => {
       return serveFreshJson(req, res, {
         tag: 'work-items',
-        inputs,
+        inputs: [CONFIG_PATH],
         // W-mq5xg5e9000nec0e — Slim every item before stringify so the polled
         // refresh-loop payload stays < ~300 KB even when description fields
         // include 100+ KB transcripts. slimWorkItemForList shallow-copies so
@@ -13307,22 +13030,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         builder: () => getWorkItems().map(slimWorkItemForList),
       });
     }},
-    { method: 'GET', path: '/api/pull-requests', desc: 'Fully-enriched pull requests (per-project files joined + url backfill + _project stamp)', handler: (req, res) => {
-      const config = queries.getConfig();
-      const projects = config.projects || [];
-      const inputs = [
-        CONFIG_PATH,
-        // Central pull-requests.json at MINIONS_DIR root — backs the
-        // 'central' scope per pull-requests-store.js#_filePathForScope.
-        // Mirrors the same class of staleness fix as /api/work-items.
-        shared.centralPullRequestsPath(MINIONS_DIR),
-      ];
-      for (const p of projects) {
-        if (p && p.name) inputs.push(path.join(MINIONS_DIR, 'projects', p.name, 'pull-requests.json'));
-      }
+    { method: 'GET', path: '/api/pull-requests', desc: 'Fully-enriched SQL-backed pull requests with URL backfill and project stamps', handler: (req, res) => {
       return serveFreshJson(req, res, {
         tag: 'pull-requests',
-        inputs,
+        inputs: [CONFIG_PATH],
         builder: () => queries.getPullRequests(),
       });
     }},
@@ -13334,54 +13045,22 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'GET', path: '/api/dispatch', desc: 'Live dispatch queue with completion-report summaries (pending/active/completed slices)', handler: (req, res) => {
       return serveFreshJson(req, res, {
         tag: 'dispatch',
-        inputs: [
-          path.join(ENGINE_DIR, 'dispatch.json'),
-          path.join(ENGINE_DIR, 'metrics.json'),
-        ],
+        inputs: [],
         builder: () => getDispatchQueue(),
       });
     }},
     { method: 'GET', path: '/api/metrics', desc: 'Per-agent metrics with PR/runtime enrichment (joined against pull-requests + dispatch.completed)', handler: (req, res) => {
-      const config = queries.getConfig();
-      const projects = config.projects || [];
-      const inputs = [
-        path.join(ENGINE_DIR, 'metrics.json'),
-        path.join(ENGINE_DIR, 'dispatch.json'),
-        // getMetrics() enriches from getPullRequests(), which includes the
-        // central pull-requests.json scope — include it here too so a new
-        // central-scope PR busts the ETag (same class of bug as /api/work-items).
-        shared.centralPullRequestsPath(MINIONS_DIR),
-      ];
-      for (const p of projects) {
-        if (p && p.name) inputs.push(path.join(MINIONS_DIR, 'projects', p.name, 'pull-requests.json'));
-      }
       return serveFreshJson(req, res, {
         tag: 'metrics',
-        inputs,
+        inputs: [CONFIG_PATH],
         builder: () => getMetrics(),
       });
     }},
-    { method: 'GET', path: '/api/prd', desc: 'PRD status + progress derived from prd/*.json × per-project work-items × pull-requests', handler: (req, res) => {
-      const config = queries.getConfig();
-      const projects = config.projects || [];
+    { method: 'GET', path: '/api/prd', desc: 'PRD status + progress derived from SQL-backed PRDs, work items, and pull requests', handler: (req, res) => {
       const inputs = [
         CONFIG_PATH,
-        PRD_DIR,
-        path.join(PRD_DIR, 'archive'),
-        // Plans dir — getPrdInfo statSyncs plans/<plan.source_plan> to
-        // compute the `planStale` flag; edits to plans/*.md need to bust
-        // the ETag so the Regenerate prompt surfaces. (Review finding #7.)
         path.join(MINIONS_DIR, 'plans'),
-        // Central work-items.json at MINIONS_DIR root — getPrdInfo
-        // cross-references plan items lacking a project scope. (Review #7.)
-        path.join(MINIONS_DIR, 'work-items.json'),
       ];
-      for (const p of projects) {
-        if (p && p.name) {
-          inputs.push(path.join(MINIONS_DIR, 'projects', p.name, 'work-items.json'));
-          inputs.push(path.join(MINIONS_DIR, 'projects', p.name, 'pull-requests.json'));
-        }
-      }
       return serveFreshJson(req, res, {
         tag: 'prd',
         inputs,
@@ -13391,7 +13070,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'GET', path: '/api/archived-prds', desc: 'List of archived PRD files with status + completedAt', handler: (req, res) => {
       return serveFreshJson(req, res, {
         tag: 'archived-prds',
-        inputs: [path.join(PRD_DIR, 'archive')],
+        inputs: [],
         builder: () => [],
       });
     }},
@@ -13418,12 +13097,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         builder: () => {
           // Read config.json directly via queries.getConfig() rather than
           // calling reloadConfig() — the latter cascades into
-          // ensureConfiguredProjectStateFiles() which acquires
-          // mutateJsonFileLocked on every project's work-items.json AND
-          // pull-requests.json, putting the schedules sidebar poll on the
-          // critical path of every engine PR/WI writer. The builder only
-          // needs config.schedules; getConfig is a pure disk read.
-          // (Round-2 review finding #3.)
+          // ensureConfiguredProjectStateFiles(); the builder only needs
+          // config.schedules, so getConfig avoids unrelated setup work.
           const cfg = queries.getConfig() || {};
           const scheds = cfg.schedules || [];
           const runs = require('./engine/small-state-store').readScheduleRuns();
@@ -13570,11 +13245,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const { id, source, rating, comment } = body;
       if (!id || !rating) return jsonReply(res, 400, { error: 'id and rating required' });
       const projects = shared.getProjects(CONFIG);
-      const paths = [path.join(MINIONS_DIR, 'work-items.json')];
-      for (const p of projects) paths.push(shared.projectWorkItemsPath(p));
+      const workItemScopes = ['central', ...projects];
       let found = null;
-      for (const wiPath of paths) {
-        mutateWorkItems(wiPath, items => {
+      for (const scope of workItemScopes) {
+        mutateWorkItems(scope, items => {
           const item = items.find(i => i.id === id);
           if (item && !found) {
             item._humanFeedback = { rating, comment: comment || '', at: new Date().toISOString() };
@@ -13714,7 +13388,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       } catch (e) {
         return jsonReply(res, e.statusCode || 400, { error: e.message }, req);
       }
-      const { id: prId, prPath, prNum, created, linked, targetProject, projectResolution, skipped, resurrected } = linkResult;
+      const { id: prId, scope, prNum, created, linked, targetProject, projectResolution, skipped, resurrected } = linkResult;
       invalidateStatusCache();
       // W-mrdutzdr000t22f4 — upsertPullRequestRecord can leave the record
       // untouched (`skipped: true`) for reasons other than a resurrect, e.g.
@@ -13763,7 +13437,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             } catch { /* ADO token may not be available */ }
           }
           if (!prData) return;
-          mutateJsonFileLocked(prPath, (prs) => {
+          shared.mutatePullRequests(scope, (prs) => {
             const pr = prs.find(p => p.id === prId);
             if (!pr) return prs;
             // Remote title always wins — any user-supplied title is a placeholder (closes #1283)
@@ -13978,14 +13652,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const { id, project: requestedProjectName } = body;
       if (!id) return jsonReply(res, 400, { error: 'id required' });
       reloadConfig();
-      // Search all project PR files and central file
+      // Search all project and central PR scopes.
       const projects = shared.getProjects(CONFIG);
       const projectByName = new Map(projects.map(project => [project.name, project]));
       const store = require('./engine/pull-requests-store');
       const storedPrs = store.readAllPullRequests() || [];
       const prScopes = new Map([
-        ...projects.map(project => [project.name, { prPath: shared.projectPrPath(project), project }]),
-        ['central', { prPath: path.join(MINIONS_DIR, 'pull-requests.json'), project: null }],
+        ...projects.map(project => [project.name, { source: project, project }]),
+        ['central', { source: 'central', project: null }],
       ]);
       const canonicalRequest = shared.parseCanonicalPrId(id);
       const requestedIdentities = new Set();
@@ -14016,7 +13690,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const ownerProject = scope !== 'central' ? projectByName.get(scope) || null : null;
         if (!requestedIdentities.has(shared.getPrIdentityKey(pr, ownerProject))) continue;
         if (!prScopes.has(scope)) {
-          prScopes.set(scope, { prPath: store._filePathForScope(scope), project: ownerProject });
+          prScopes.set(scope, { source: ownerProject || scope, project: ownerProject });
         }
       }
       let found = false;
@@ -14027,11 +13701,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       // the other scope's copy fully untouched — queries.js#getPullRequests
       // then de-dupes by picking that untouched duplicate as the "winner"
       // and silently resurrects the "deleted" PR on the next read.
-      for (const { prPath, project } of prScopes.values()) {
+      for (const { source, project } of prScopes.values()) {
         // Issue #384: use a tombstone (userDeleted:true) instead of splice so
         // the next poller cycle cannot re-add the PR. The entry stays in the
-        // file but is filtered from API responses and skipped by pollers.
-        shared.mutatePullRequests(prPath, (prs) => {
+        // state but is filtered from API responses and skipped by pollers.
+        shared.mutatePullRequests(source, (prs) => {
           if (!Array.isArray(prs)) return prs;
           const matches = prs.filter(pr =>
             requestedIdentities.has(shared.getPrIdentityKey(pr, project))
@@ -14056,22 +13730,19 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       if (!prId) return jsonReply(res, 400, { error: 'prId required' });
       if (!cause) return jsonReply(res, 400, { error: 'cause required' });
       // Validate cause is one of the known PR_FIX_CAUSE values to reject
-      // typos before scanning state files.
+      // typos before scanning state.
       const knownCauses = new Set(Object.values(shared.PR_FIX_CAUSE));
       if (!knownCauses.has(cause)) {
         return jsonReply(res, 400, { error: `unknown cause: ${cause}` });
       }
       reloadConfig();
       const lifecycle = require('./engine/lifecycle');
-      const prPaths = [
-        ...shared.getProjects(CONFIG).map(p => shared.projectPrPath(p)),
-        shared.centralPullRequestsPath(MINIONS_DIR),
-      ];
+      const prSources = [...shared.getProjects(CONFIG), 'central'];
       let prFound = false;
       let causeFound = false;
-      for (const prPath of prPaths) {
+      for (const source of prSources) {
         if (causeFound) break;
-        shared.mutatePullRequests(prPath, (prs) => {
+        shared.mutatePullRequests(source, (prs) => {
           if (!Array.isArray(prs)) return prs;
           const target = prs.find(p => p && p.id === prId);
           if (!target) return prs;
@@ -14094,7 +13765,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // separately from `_noOpFixes` and so isn't reachable via the endpoint
     // above. Once a fresh CI build is queued against a rebased/retried head,
     // this lets an operator clear the stale pause without hand-editing
-    // pull-requests.json.
+    // tracked PR state.
     { method: 'POST', path: '/api/pull-requests/clear-build-fix-ineffective', desc: 'Resume a paused build-fix-ineffective ("infra issue suspected") pause (issue #671) — clears _buildFixIneffective so BUILD_FAILURE auto-fix dispatch can resume', params: 'prId (canonical host:slug#number), headSha? (optional — if provided, must match the paused record\'s headSha or the clear is rejected as stale)', handler: async (req, res) => {
       const body = await readBody(req);
       const prId = typeof body?.prId === 'string' ? body.prId.trim() : '';
@@ -14102,16 +13773,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       if (!prId) return jsonReply(res, 400, { error: 'prId required' });
       reloadConfig();
       const lifecycle = require('./engine/lifecycle');
-      const prPaths = [
-        ...shared.getProjects(CONFIG).map(p => shared.projectPrPath(p)),
-        shared.centralPullRequestsPath(MINIONS_DIR),
-      ];
+      const prSources = [...shared.getProjects(CONFIG), 'central'];
       let prFound = false;
       let recordCleared = false;
       let staleHead = false;
-      for (const prPath of prPaths) {
+      for (const source of prSources) {
         if (recordCleared || staleHead) break;
-        shared.mutatePullRequests(prPath, (prs) => {
+        shared.mutatePullRequests(source, (prs) => {
           if (!Array.isArray(prs)) return prs;
           const target = prs.find(p => p && p.id === prId);
           if (!target) return prs;
@@ -14150,15 +13818,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       if (!prId) return jsonReply(res, 400, { error: 'prId required' });
       reloadConfig();
       const lifecycle = require('./engine/lifecycle');
-      const prPaths = [
-        ...shared.getProjects(CONFIG).map(p => shared.projectPrPath(p)),
-        shared.centralPullRequestsPath(MINIONS_DIR),
-      ];
+      const prSources = [...shared.getProjects(CONFIG), 'central'];
       let prFound = false;
       let recordCleared = false;
-      for (const prPath of prPaths) {
+      for (const source of prSources) {
         if (recordCleared) break;
-        shared.mutatePullRequests(prPath, (prs) => {
+        shared.mutatePullRequests(source, (prs) => {
           if (!Array.isArray(prs)) return prs;
           const target = prs.find(p => p && p.id === prId);
           if (!target) return prs;
@@ -14593,10 +14258,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       completeRun(body.id, run.runId, 'failed');
       // Cancel pending/active work items and dispatches spawned by this run
       let cancelled = 0;
-      const wiPaths = [path.join(MINIONS_DIR, 'work-items.json'), ...PROJECTS.map(p => shared.projectWorkItemsPath(p))];
-      for (const wiPath of wiPaths) {
+      const workItemScopes = ['central', ...PROJECTS];
+      for (const scope of workItemScopes) {
         try {
-          mutateWorkItems(wiPath, items => {
+          mutateWorkItems(scope, items => {
             for (const w of items) {
               if (w._pipelineRun === run.runId && w.status !== shared.WI_STATUS.DONE && w.status !== shared.WI_STATUS.CANCELLED) {
                 w.status = shared.WI_STATUS.CANCELLED;
@@ -14971,6 +14636,7 @@ module.exports = {
   _findDuplicateWorkItemCreate: findDuplicateWorkItemCreate,
   _createWorkItemWithDedup: createWorkItemWithDedup,
   _resolveWorkItemsCreateTarget: resolveWorkItemsCreateTarget,
+  _matchesResolvedWorkItemDispatch: matchesResolvedWorkItemDispatch, // exported for testing
   _validatePrFollowupShape: validatePrFollowupShape,
   _findExistingFollowupForComment: findExistingFollowupForComment,
   _extractMinionsAgentHeader: extractMinionsAgentHeader,
@@ -14984,6 +14650,7 @@ module.exports = {
   buildCCStateRefresh,
   _resetRefreshCache,
   _routesAsMeta,
+  _buildConstellationBridgeSnapshot,
   _server: server,
   _buildTranscriptCarryover,
   _transcriptHasCarryoverContext,