@yemi33/minions 0.1.2378 → 0.1.2380

package/engine.js

@@ -57,7 +57,7 @@ const IDENTITY_DIR = path.join(MINIONS_DIR, 'identity');
 
 // Re-export from queries for internal use (avoid changing every call site)
 const { CONFIG_PATH, NOTES_PATH, AGENTS_DIR, ENGINE_DIR, CONTROL_PATH,
-  DISPATCH_PATH, LOG_PATH, INBOX_DIR, KNOWLEDGE_DIR, PLANS_DIR, PRD_DIR } = queries;
+  INBOX_DIR, KNOWLEDGE_DIR, PLANS_DIR, PRD_DIR } = queries;
 
 // ─── Multi-Project Support ──────────────────────────────────────────────────
 // Config can have either:
@@ -102,7 +102,7 @@ function validateConfig(config) {
   }
 }
 
-const { getProjects, projectRoot, projectStateDir, projectWorkItemsPath, projectPrPath, getAdoOrgBase, sanitizeBranch, parseSkillFrontmatter, safeReadDir,
+const { getProjects, projectRoot, projectStateDir, getAdoOrgBase, sanitizeBranch, parseSkillFrontmatter, safeReadDir,
   logTs, dateStamp, log } = shared;
 
 // ─── Utilities ──────────────────────────────────────────────────────────────
@@ -110,12 +110,13 @@ const { getProjects, projectRoot, projectStateDir, projectWorkItemsPath, project
 const safeJson = shared.safeJson;
 const safeJsonArr = shared.safeJsonArr;
 const safeJsonObj = shared.safeJsonObj;
-const safeJsonNoRestore = shared.safeJsonNoRestore;
 const safeRead = shared.safeRead;
 const safeWrite = shared.safeWrite;
 const safeUnlink = shared.safeUnlink;
 const mutateJsonFileLocked = shared.mutateJsonFileLocked;
 const mutateControl = shared.mutateControl;
+const readWorkItems = shared.readWorkItems;
+const readPullRequests = shared.readPullRequests;
 const mutateWorkItems = shared.mutateWorkItems;
 const mutatePullRequests = shared.mutatePullRequests;
 const withFileLock = shared.withFileLock;
@@ -175,7 +176,7 @@ const ghToken = require('./engine/gh-token');
 const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, reconcilePrdStatuses, handlePostMerge, checkPlanCompletion,
   syncPrsFromOutput, updatePrAfterReview, updatePrAfterFix, checkForLearnings, extractSkillsFromOutput,
   updateAgentHistory, updateMetrics, createReviewFeedbackForAuthor, parseAgentOutput, syncPrdFromPrs, persistVerifyPrsToPrd,
-  isItemCompleted, classifyFailure: classifyFailureFallback, diagnoseEmptyOutput, processPendingRebases, resolveWorkItemPath,
+  isItemCompleted, classifyFailure: classifyFailureFallback, diagnoseEmptyOutput, processPendingRebases, resolveWorkItemScope,
   mergeArtifactNotes, promoteCompletionArtifacts, pruneScopeMismatchDuplicatePrs, collapseAllDuplicatePrRecords,
   recordWorktreeHeldPause, clearWorktreeHeldPause } = require('./engine/lifecycle');
 
@@ -701,8 +702,7 @@ function resolveDependencyBranches(depIds, sourcePlan, project, config) {
 
   // Find PR branches for each dependency work item
   for (const p of projects) {
-    const prPath = shared.projectPrPath(p);
-    const prs = safeJsonArr(prPath);
+    const prs = readPullRequests(p);
     for (const pr of prs) {
       if (!pr.branch || pr.status !== PR_STATUS.ACTIVE) continue;
       const linked = (pr.prdItems || []).some(id =>
@@ -2159,7 +2159,7 @@ function _tryAutoResolveLiveCheckoutWorktreeConflict({ conflictPath, gitRoot, en
 async function spawnAgent(dispatchItem, config) {
   const { id, agent: agentId, type, meta } = dispatchItem;
   // Resolve prompt — prefers sidecar file when dispatchItem._promptFile is set
-  // (large prompts are written to engine/contexts/<id>.md to keep dispatch.json
+  // (large prompts are written to engine/contexts/<id>.md to keep dispatch rows
   // small — see shared.sidecarDispatchPrompt / #1167).
   let taskPrompt = shared.resolveDispatchPrompt(dispatchItem);
   const claudeConfig = config.claude || {};
@@ -2415,12 +2415,8 @@ async function spawnAgent(dispatchItem, config) {
   // dir via shared.dispatchPidCandidates / findDispatchPidFile. Best-effort —
   // backward-compat fallbacks still scan dispatch-<safeId>-* dirs by id.
   //
-  // W-mq9b7lor (H1): must route through mutateDispatch (SQL writer) — a direct
-  // mutateJsonFileLocked on engine/dispatch.json is dropped on the next
-  // mutateDispatch call because engine/dispatch.js#mutateDispatch regenerates
-  // dispatch.json from SQL after every successful mutation (see
-  // engine/dispatch.js:98-101). Without the SQL write, the tmpDir pointer is
-  // lost and orphan-reap/kill/cleanup paths can't find the prompt directory.
+  // W-mq9b7lor (H1): persist through mutateDispatch so the tmpDir pointer
+  // survives and orphan-reap/kill/cleanup paths can find the prompt directory.
   try {
     dispatchItem.tmpDir = dispatchTmpDir;
     mutateDispatch((dispatch) => {
@@ -2519,7 +2515,7 @@ async function spawnAgent(dispatchItem, config) {
     if ((meta?.source === 'pr' || meta?.source === 'pr-human-feedback') && meta?.pr) {
       try {
         const pauseProject = meta.project || project;
-        mutatePullRequests(projectPrPath(pauseProject), (prs) => {
+        mutatePullRequests(pauseProject, (prs) => {
           if (!Array.isArray(prs)) return prs;
           const target = shared.findPrRecord(prs, meta.pr, pauseProject);
           if (!target) return prs;
@@ -2581,7 +2577,7 @@ async function spawnAgent(dispatchItem, config) {
   // validation WI auto-created by the post-completion hook that carries a PR
   // reference but no explicit branch), resolve the target branch from the work
   // item's PR reference so prepareLiveCheckout can check out the correct PR
-  // source branch. resolveWorkItemPrRecord loads pull-requests.json + finds the
+  // source branch. resolveWorkItemPrRecord loads tracked PR state and finds the
   // PR record; resolvePrBranch extracts the source branch from it. Both helpers
   // are hoisted function declarations so the order-of-definition is safe.
   if (liveMode && !branchName && !READ_ONLY_ROOT_TASK_TYPES.has(type)) {
@@ -2682,9 +2678,9 @@ async function spawnAgent(dispatchItem, config) {
       wiId: _wiIdForAlert,
       log: (msg, lvl) => log(lvl || 'info', msg),
       clearDirtyStamp: () => {
-        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (_wiPath && dispatchItem.meta?.item?.id) {
-          mutateJsonFileLocked(_wiPath, (data) => {
+        const _wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (_wiScope && dispatchItem.meta?.item?.id) {
+          mutateWorkItems(_wiScope, (data) => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
             if (wi && wi._pendingReason === 'live_checkout_dirty') delete wi._pendingReason;
@@ -2821,9 +2817,9 @@ async function spawnAgent(dispatchItem, config) {
       try { writeInboxAlert(`live-checkout-dirty-${_wiIdForAlert}`, _alertBody); }
       catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
       try {
-        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (_wiPath && dispatchItem.meta?.item?.id) {
-          mutateJsonFileLocked(_wiPath, (data) => {
+        const _wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (_wiScope && dispatchItem.meta?.item?.id) {
+          mutateWorkItems(_wiScope, (data) => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
             if (wi) {
@@ -2892,9 +2888,9 @@ async function spawnAgent(dispatchItem, config) {
       catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
       const _pendingReason = _isMidOp ? 'live_checkout_mid_operation' : 'live_checkout_detached_head';
       try {
-        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (_wiPath && dispatchItem.meta?.item?.id) {
-          mutateJsonFileLocked(_wiPath, (data) => {
+        const _wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (_wiScope && dispatchItem.meta?.item?.id) {
+          mutateWorkItems(_wiScope, (data) => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
             if (wi) wi._pendingReason = _pendingReason;
@@ -2966,9 +2962,9 @@ async function spawnAgent(dispatchItem, config) {
       try { writeInboxAlert(`live-checkout-blocked-${_wiIdForAlert}`, _alertBody); }
       catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
       try {
-        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (_wiPath && dispatchItem.meta?.item?.id) {
-          mutateJsonFileLocked(_wiPath, (data) => {
+        const _wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (_wiScope && dispatchItem.meta?.item?.id) {
+          mutateWorkItems(_wiScope, (data) => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
             if (wi) wi._pendingReason = 'live_checkout_wrong_base';
@@ -3025,9 +3021,9 @@ async function spawnAgent(dispatchItem, config) {
       try { writeInboxAlert(`live-checkout-blocked-${_wiIdForAlert}`, _alertBody); }
       catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
       try {
-        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (_wiPath && dispatchItem.meta?.item?.id) {
-          mutateJsonFileLocked(_wiPath, (data) => {
+        const _wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (_wiScope && dispatchItem.meta?.item?.id) {
+          mutateWorkItems(_wiScope, (data) => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
             if (wi) wi._pendingReason = 'live_checkout_blob_fetch';
@@ -3129,9 +3125,9 @@ async function spawnAgent(dispatchItem, config) {
       try { writeInboxAlert(`live-checkout-worktree-conflict-${_wiIdForAlert}`, _alertBody); }
       catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
       try {
-        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (_wiPath && dispatchItem.meta?.item?.id) {
-          mutateJsonFileLocked(_wiPath, (data) => {
+        const _wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (_wiScope && dispatchItem.meta?.item?.id) {
+          mutateWorkItems(_wiScope, (data) => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
             if (wi) wi._pendingReason = 'live_checkout_worktree_conflict';
@@ -3215,9 +3211,9 @@ async function spawnAgent(dispatchItem, config) {
       try { writeInboxAlert(`live-checkout-stale-base-${_wiIdForAlert}`, _alertBody); }
       catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
       try {
-        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (_wiPath && dispatchItem.meta?.item?.id) {
-          mutateJsonFileLocked(_wiPath, (data) => {
+        const _wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (_wiScope && dispatchItem.meta?.item?.id) {
+          mutateWorkItems(_wiScope, (data) => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
             if (wi) wi._pendingReason = 'live_checkout_stale_base';
@@ -3244,9 +3240,9 @@ async function spawnAgent(dispatchItem, config) {
     // second-strike on its next dirty encounter. Only write when the stamp is set.
     if (dispatchItem.meta?.item?._liveCheckoutDirtyAttempts) {
       try {
-        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (_wiPath && dispatchItem.meta?.item?.id) {
-          mutateJsonFileLocked(_wiPath, (data) => {
+        const _wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (_wiScope && dispatchItem.meta?.item?.id) {
+          mutateWorkItems(_wiScope, (data) => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
             if (wi) delete wi._liveCheckoutDirtyAttempts;
@@ -3905,7 +3901,7 @@ async function spawnAgent(dispatchItem, config) {
           // Fetch all dependency branches in parallel (git fetches are independent)
           const fetchable = depBranches.filter(d => !_failedRefCache.has(d.branch));
           const unfetchable = depBranches.filter(d => _failedRefCache.has(d.branch));
-          const allPrsForDeps = unfetchable.length > 0 ? shared.getProjects(config).reduce((acc, p) => acc.concat(safeJsonArr(shared.projectPrPath(p))), []) : [];
+          const allPrsForDeps = unfetchable.length > 0 ? shared.getProjects(config).reduce((acc, p) => acc.concat(readPullRequests(p)), []) : [];
           for (const { branch: depBranch, prId } of unfetchable) {
             const pr = allPrsForDeps.find(p => p.id === prId);
             if (pr && (pr.status === PR_STATUS.MERGED || pr.status === PR_STATUS.CLOSED)) {
@@ -3938,7 +3934,7 @@ async function spawnAgent(dispatchItem, config) {
             })
           );
           const hasFetchFailures = fetchResults.some(r => r.status === 'rejected');
-          const allPrsForFetch = hasFetchFailures ? shared.getProjects(config).reduce((acc, p) => acc.concat(safeJsonArr(shared.projectPrPath(p))), []) : [];
+          const allPrsForFetch = hasFetchFailures ? shared.getProjects(config).reduce((acc, p) => acc.concat(readPullRequests(p)), []) : [];
           // Track branches recovered by local-only push so they can be merged
           const recoveredBranches = new Set();
           for (let i = 0; i < fetchResults.length; i++) {
@@ -4291,9 +4287,7 @@ async function spawnAgent(dispatchItem, config) {
             // so commits land on the dep's existing PR branch (W-mpcwojgr000a0244).
             if (depConflictBranch && meta?.item?.id && project) {
               try {
-                const wiPath = project.name
-                  ? projectWorkItemsPath(project)
-                  : path.join(MINIONS_DIR, 'work-items.json');
+                const wiScope = project.name ? project : 'central';
                 const newItem = buildDepConflictFixItem({
                   depConflictBranch,
                   depConflictFiles,
@@ -4303,7 +4297,7 @@ async function spawnAgent(dispatchItem, config) {
                   blockedItem: meta.item,
                   projectName: project.name || null,
                 });
-                mutateWorkItems(wiPath, items => {
+                mutateWorkItems(wiScope, items => {
                   // Don't create duplicate conflict-fix items
                   const existing = items.find(i => i.id === newItem.id && i.status !== WI_STATUS.DONE && i.status !== WI_STATUS.FAILED && i.status !== WI_STATUS.CANCELLED);
                   if (existing) return;
@@ -4538,7 +4532,7 @@ async function spawnAgent(dispatchItem, config) {
   log('info', `Spawning agent: ${agentId} (${id}) in ${cwd}`);
   log('info', `Task type: ${type} | Branch: ${branchName || 'none'}`);
 
-  // Agent status is derived from dispatch.json — no setAgentStatus needed for working state.
+  // Agent status is derived from dispatch state.
 
   // Spawn the claude process
   const childEnv = shared.cleanChildEnv();
@@ -4693,13 +4687,24 @@ async function spawnAgent(dispatchItem, config) {
       });
     } else {
       // P-1d8f0b93 — pooled copilot dispatch. No separate spawn-agent.js
-      // child process exists, so build the SAME combined prompt text that
-      // process would have received via runtime.buildPrompt(...) directly
-      // here, and hand it to a PooledAgentProcess facade instead of
-      // cold-spawning. Everything downstream (stdout/stderr handlers,
+      // child process exists, so hand the task and trusted system context to
+      // the PooledAgentProcess separately instead of cold-spawning. Everything
+      // downstream (stdout/stderr handlers,
       // onAgentClose, live-output.log, PID-file writing below) treats `proc`
       // identically to a real child_process either way.
-      const pooledPromptText = runtime.buildPrompt(fullTaskPrompt, systemPrompt, { sessionId: cachedSessionId });
+      const pooledSessionKeys = [
+        'MINIONS_COMPLETION_REPORT',
+        'MINIONS_COMPLETION_NONCE',
+        'MINIONS_LIVE_OUTPUT_PATH',
+        'MINIONS_STEERING_ACK_DIR',
+        'MINIONS_AGENT_CWD',
+      ];
+      const pooledProcessEnv = { ...childEnv };
+      const pooledSessionContext = {};
+      for (const key of pooledSessionKeys) {
+        if (pooledProcessEnv[key] !== undefined) pooledSessionContext[key] = pooledProcessEnv[key];
+        delete pooledProcessEnv[key];
+      }
       proc = new PooledAgentProcess({
         pool: agentWorkerPool,
         dispatchId: id,
@@ -4710,7 +4715,10 @@ async function spawnAgent(dispatchItem, config) {
         // flat top-level config array, not per-agent-resolved.
         mcpServers: (engineConfig && engineConfig.mcpServers) || [],
         hermeticDirs: addDirs,
-        promptText: pooledPromptText,
+        processEnv: pooledProcessEnv,
+        sessionContext: pooledSessionContext,
+        systemPromptText: systemPrompt,
+        promptText: fullTaskPrompt,
       });
       // The child_process PID file is normally written asynchronously by
       // spawn-agent.js itself (engine/spawn-agent.js:606) once it starts.
@@ -5398,7 +5406,7 @@ async function spawnAgent(dispatchItem, config) {
     // agent described in its sidecar. This gate (a) rejects malformed
     // sidecars as a hard non-retryable failure with a dedicated failure
     // class + inbox alert, and (b) on success spawns each spec detached and
-    // batch-records them in engine/managed-processes.json. Healthcheck loops
+    // batch-records them in SQL managed-process state. Healthcheck loops
     // + dispatch ERROR-on-healthcheck-failure land in the follow-up item;
     // for now a spec that spawns successfully is recorded with
     // healthy:false, alive:true and the engine sweep / item-3 healthcheck
@@ -5897,9 +5905,9 @@ async function spawnAgent(dispatchItem, config) {
     //     engine/managed-logs/.
     if (managedSpawnHealthcheckFailure && managedSpawnHealthcheckFailure.annotation && dispatchItem.meta?.item?.id) {
       try {
-        const wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (wiPath) {
-          mutateWorkItems(wiPath, items => {
+        const wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (wiScope) {
+          mutateWorkItems(wiScope, items => {
             const wi = items.find(i => i.id === dispatchItem.meta.item.id);
             if (!wi) return items;
             wi._managedSpawnPartial = managedSpawnHealthcheckFailure.annotation;
@@ -5916,9 +5924,9 @@ async function spawnAgent(dispatchItem, config) {
     // rather than a queue gate.
     if (keepProcessesAcceptanceFailure && dispatchItem.meta?.item?.id) {
       try {
-        const wiPath = resolveWorkItemPath(dispatchItem.meta);
-        if (wiPath) {
-          mutateJsonFileLocked(wiPath, data => {
+        const wiScope = resolveWorkItemScope(dispatchItem.meta);
+        if (wiScope) {
+          mutateWorkItems(wiScope, data => {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i.id === dispatchItem.meta.item.id);
             if (!wi) return data;
@@ -5935,7 +5943,7 @@ async function spawnAgent(dispatchItem, config) {
     // Cleanup temp files (whole per-dispatch dir, including PID/sysprompt
     // tmp/prompt — P-f6-tmp-toctou). removeDispatchTmpDir validates the path
     // resolves under engine/tmp/dispatch-* before rmSync, so a corrupted
-    // dispatch.json field can't redirect this to an arbitrary path.
+    // dispatch field cannot redirect this to an arbitrary path.
     try { shared.removeDispatchTmpDir(dispatchTmpDir); } catch { /* cleanup */ }
 
     log('info', `Agent ${agentId} completed. Output saved to ${archivePath}`);
@@ -6037,7 +6045,7 @@ async function spawnAgent(dispatchItem, config) {
     item.started_at = startedAt;
     // Persist the resolved runtime so post-completion hooks (lifecycle.js) can
     // route output parsing through the right adapter. Also surfaces the choice
-    // in dispatch.json for debugging multi-runtime fleets.
+    // in dispatch state for debugging multi-runtime fleets.
     item.runtimeName = runtimeName;
     // P-3f5b7d26 — persist pooled on the DISK record (activeProcesses/_pooled
     // is wiped on restart); cli.js's reattach path needs this since a pooled
@@ -6064,14 +6072,9 @@ async function spawnAgent(dispatchItem, config) {
   // Atomically stamp dispatched_to/dispatched_at on the originating work item (#402).
   if (meta?.item?.id) {
     try {
-      let wiPath = null;
-      if (meta.source === 'central-work-item' || meta.source === 'central-work-item-fanout') {
-        wiPath = path.join(MINIONS_DIR, 'work-items.json');
-      } else if (meta.source === 'work-item' && meta.project?.name) {
-        wiPath = projectWorkItemsPath({ name: meta.project.name, localPath: meta.project.localPath });
-      }
-      if (wiPath) {
-        mutateJsonFileLocked(wiPath, (items) => {
+      const wiScope = resolveWorkItemScope(meta);
+      if (wiScope) {
+        mutateWorkItems(wiScope, (items) => {
           if (!Array.isArray(items)) return items;
           const wi = items.find(i => i.id === meta.item.id);
           if (wi) {
@@ -6080,7 +6083,7 @@ async function spawnAgent(dispatchItem, config) {
             if (wi.status !== WI_STATUS.DISPATCHED) wi.status = WI_STATUS.DISPATCHED;
           }
           return items;
-        }, { defaultValue: [] });
+        });
       }
     } catch (e) { log('warn', `stamp dispatched_to on work item ${meta.item.id}: ${e.message}`); }
   }
@@ -6105,12 +6108,9 @@ function areDependenciesMet(item, config) {
   for (const depId of deps) {
     const depItem = allWorkItems.find(w => w.id === depId);
     if (!depItem) {
-      // Fallback: check PRD JSON — plan-to-prd agents may pre-set items to done.
-      // safeJsonNoRestore — if the PRD has been archived, treat the dep as
-      // unmet rather than resurrecting the active PRD from .backup
-      // (W-mouptdh1000h9f39).
+      // Fallback: check the PRD store — plan-to-prd agents may pre-set items to done.
       try {
-        const plan = safeJsonNoRestore(path.join(PRD_DIR, sourcePlan));
+        const plan = prdStore.readPrd(sourcePlan);
         const prdItem = (plan?.missing_features || []).find(f => f.id === depId);
         if (prdItem && PRD_MET_STATUSES.has(prdItem.status)) continue; // PRD says done — treat as met
       } catch (e) { log('warn', 'check PRD dep status: ' + e.message); }
@@ -6182,8 +6182,8 @@ function detectDependencyCycles(items) {
 }
 
 // Reconciles work items against known PRs.
-// Primary linkage comes from prdItems in pull-requests.json; fallback linkage
-// uses engine/pr-links.json so matching does not depend on branch/title parsing.
+// Primary linkage comes from tracked PR prdItems; fallback linkage
+// uses SQL PR links so matching does not depend on branch/title parsing.
 // onlyIds: if provided, only items whose ID is in this Set are eligible.
 function reconcileItemsWithPrs(items, allPrs, { onlyIds } = {}) {
   const prLinks = shared.getPrLinks();
@@ -6275,7 +6275,7 @@ function updateSnapshot(config) {
 
 // ─── Cooldowns (extracted to engine/cooldown.js) ─────────────────────────────
 
-const { COOLDOWN_PATH, dispatchCooldowns, loadCooldowns, saveCooldowns,
+const { dispatchCooldowns, loadCooldowns, saveCooldowns,
   isOnCooldown, setCooldown, setCooldownWithContext, drainCoalescedContexts,
   setCooldownFailure, clearCooldown, getPrReviewCooldownKey, clearLegacyPrReviewCooldown,
   isAlreadyDispatched, isBranchActive } = require('./engine/cooldown');
@@ -6283,12 +6283,11 @@ const { COOLDOWN_PATH, dispatchCooldowns, loadCooldowns, saveCooldowns,
 // Auto-clean pending/failed work items for a PRD so they re-materialize with updated plan data
 function autoCleanPrdWorkItems(prdFile, config) {
   const allProjects = getProjects(config);
-  const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-  for (const proj of allProjects) wiPaths.push(projectWorkItemsPath(proj));
+  const workItemScopes = ['central', ...allProjects];
   const deletedIds = [];
-  for (const wiPath of wiPaths) {
+  for (const scope of workItemScopes) {
     try {
-      mutateWorkItems(wiPath, items => {
+      mutateWorkItems(scope, items => {
         const filtered = items.filter(w => {
           if (w.sourcePlan === prdFile && (w.status === WI_STATUS.PENDING || w.status === WI_STATUS.FAILED)) {
             deletedIds.push(w.id); return false;
@@ -6331,51 +6330,6 @@ function safePrdProjectSlug(projectName) {
   return slug || 'project';
 }
 
-/**
- * Atomically reserve a unique PRD filename in `prdDir` (P-9b7e5d3c).
- *
- * Replaces the racy "fs.existsSync(...) then write" pattern: two parallel
- * materializations on the same plan slug previously both observed a 'free'
- * filename and silently overwrote each other. This helper uses
- * `fs.openSync(path, 'wx')` so the OS rejects duplicate creates atomically.
- *
- * Attempt schedule (100 attempts total):
- *   attempt = 0 → baseFileName              (e.g. "slug.json")
- *   attempt = 1 → "${stem}-1${ext}"          (e.g. "slug-1.json")
- *   attempt = 2 → "${stem}-2${ext}"
- *   ...
- *   attempt = 99 → "${stem}-99${ext}"
- *
- * Behavior:
- *   - On EEXIST: increment attempt and retry.
- *   - Any other openSync error propagates immediately.
- *   - After 100 EEXIST failures: throw
- *     'Could not reserve unique PRD filename after 100 attempts'.
- *   - On success: write `content` to the reserved file, close fd, return basename.
- */
-function reservePrdFilename(prdDir, baseFileName, content = '') {
-  const ext = path.extname(baseFileName);
-  const stem = ext ? baseFileName.slice(0, -ext.length) : baseFileName;
-  for (let attempt = 0; attempt < 100; attempt++) {
-    const candidateName = attempt === 0 ? baseFileName : `${stem}-${attempt}${ext}`;
-    const candidatePath = path.join(prdDir, candidateName);
-    let fd;
-    try {
-      fd = fs.openSync(candidatePath, 'wx');
-    } catch (err) {
-      if (err && err.code === 'EEXIST') continue;
-      throw err;
-    }
-    try {
-      if (content) fs.writeSync(fd, content);
-    } finally {
-      fs.closeSync(fd);
-    }
-    return candidateName;
-  }
-  throw new Error('Could not reserve unique PRD filename after 100 attempts');
-}
-
 // Fleet branches the engine/CC create. A worktree-mode operator checkout should
 // NEVER sit on one of these (or any branch); when it does, a flow ran raw
 // `git checkout`/`merge` in the live checkout instead of a worktree.
@@ -6444,16 +6398,15 @@ function restoreHijackedOperatorCheckouts(config) {
 }
 
 function materializePlansAsWorkItems(config) {
-  if (!fs.existsSync(PRD_DIR)) { try { fs.mkdirSync(PRD_DIR, { recursive: true }); } catch (e) { log('warn', 'create PRD directory: ' + e.message); } }
   const writePrdLocked = (fileName, data) => {
-    return mutateJsonFileLocked(path.join(PRD_DIR, fileName), () => data, { defaultValue: data });
+    return prdStore.writePrd(fileName, data);
   };
-  const mutatePrdLocked = (fileName, fallback, mutator, options = {}) => {
-    return mutateJsonFileLocked(path.join(PRD_DIR, fileName), (current) => {
+  const mutatePrdLocked = (fileName, fallback, mutator) => {
+    return prdStore.mutatePrd(fileName, (current) => {
       if (!current?.missing_features && fallback?.missing_features) current = fallback;
       if (!current || Array.isArray(current) || typeof current !== 'object') current = {};
       return mutator(current) || current;
-    }, { defaultValue: fallback || {}, ...options });
+    }, { defaultValue: fallback || {} });
   };
   const enforceDeclaredPlanProject = (fileName, currentPlan) => {
     if (!currentPlan?.source_plan) return { fileName, plan: currentPlan };
@@ -6512,7 +6465,7 @@ function materializePlansAsWorkItems(config) {
             const jsonName = mf.replace(/\.md$/, '.json');
             // Atomic open ('wx' + retry) so two parallel migrations on the
             // same slug don't both overwrite a single PRD (P-9b7e5d3c).
-            const reserved = reservePrdFilename(checkDir, jsonName, JSON.stringify(parsed, null, 2));
+            const reserved = prdStore.createPrdUnique(jsonName, parsed);
             try { fs.unlinkSync(path.join(checkDir, mf)); } catch { /* cleanup */ }
             log('info', `Plan enforcement: moved ${mf} → prd/${reserved} (PRDs must be .json in prd/)`);
           }
@@ -6529,7 +6482,7 @@ function materializePlansAsWorkItems(config) {
             if (parsed?.missing_features) {
               // Atomic open ('wx' + retry) so two parallel migrations on the
               // same slug don't both overwrite a single PRD (P-9b7e5d3c).
-              const reserved = reservePrdFilename(PRD_DIR, jf, JSON.stringify(parsed, null, 2));
+              const reserved = prdStore.createPrdUnique(jf, parsed);
               try { fs.unlinkSync(path.join(PLANS_DIR, jf)); } catch { /* cleanup */ }
               log('info', `Auto-migrated PRD ${jf} from plans/ to prd/${reserved}`);
             }
@@ -6549,10 +6502,7 @@ function materializePlansAsWorkItems(config) {
   const SEQUENTIAL_ID_RE = /^[A-Za-z]+-?\d+$/;
 
   for (let file of planFiles) {
-    // safeJsonNoRestore — if a PRD was archived between readdir and this
-    // read, do not auto-resurrect it from a stale .backup sidecar
-    // (W-mouptdh1000h9f39).
-    let plan = safeJsonNoRestore(path.join(PRD_DIR, file));
+    let plan = prdStore.readPrd(file);
     if (!plan?.missing_features) continue;
     // Resurrection-re-execution guard ("old PRDs came back"): never (re)materialize
     // a defunct PRD — archived, or completed with its source plan gone from plans/.
@@ -6699,7 +6649,7 @@ function materializePlansAsWorkItems(config) {
     const defaultProjectName = plan.project || file.replace(/-\d{4}-\d{2}-\d{2}\.json$/, '');
     const allProjects = getProjects(config);
     const defaultProject = shared.resolveProjectSource(defaultProjectName, allProjects, { allowCentral: false }).project;
-    // No project found — use central work-items.json (engine works without projects)
+    // No project found — use central state (engine works without projects).
     const useCentral = !defaultProject;
 
     const statusFilter = PRD_MATERIALIZABLE;
@@ -6723,7 +6673,7 @@ function materializePlansAsWorkItems(config) {
     );
 
     // Group items by target project (per-item project field overrides plan-level project)
-    // When no projects are configured, all items go to central work-items.json
+    // When no projects are configured, all items use the central scope.
     const itemsByProject = new Map(); // projectName -> { project, items: [] }
     for (const item of items) {
       if (item.project) {
@@ -6773,19 +6723,19 @@ function materializePlansAsWorkItems(config) {
       // A pause/reject/awaiting-approval signal may arrive between the outer-loop initial
       // read and this point (e.g. operator pauses via dashboard while the tick is running).
       // Re-reading here prevents phantom WI creation on a paused, rejected, or unapproved plan.
-      const freshPrd = prdStore.readPrd(path.join(PRD_DIR, file));
+      const freshPrd = prdStore.readPrd(file);
       const freshStatus = (freshPrd || {}).status || ((freshPrd || {}).requires_approval ? 'awaiting-approval' : null);
       if (freshStatus === PLAN_STATUS.PAUSED || freshStatus === PLAN_STATUS.REJECTED || freshStatus === 'awaiting-approval') {
         log('warn', `PRD ${file}: status changed to '${freshStatus}' mid-tick — skipping WI batch for ${projName} (P-f1a3b5c7)`);
         break;
       }
 
-      const wiPath = project ? projectWorkItemsPath(project) : path.join(MINIONS_DIR, 'work-items.json');
+      const wiScope = project || 'central';
       let created = 0;
       const newlyCreatedIds = new Set(); // tracks IDs created in this pass for reconciliation scoping
       const deferredReopens = []; // cross-project re-opens executed after this lock releases
 
-      mutateWorkItems(wiPath, existingItems => {
+      mutateWorkItems(wiScope, existingItems => {
         for (const item of projItems) {
           // Re-open: 'updated' or 'missing' re-opens a done work item (#906)
           // Use composite (sourcePlan, id) key so a WI from another PRD with the
@@ -6807,7 +6757,7 @@ function materializePlansAsWorkItems(config) {
           if (!alreadyExists) {
             for (const p of allProjects) {
               if (String(p.name || '').toLowerCase() === String(projName || '').toLowerCase()) continue;
-              const otherItems = safeJsonArr(projectWorkItemsPath(p));
+              const otherItems = readWorkItems(p);
               const otherWi = otherItems.find(w => w.id === item.id && w.sourcePlan === file);
               if (otherWi) {
                 if (DONE_STATUSES.has(otherWi.status) && shouldReopen) {
@@ -6853,7 +6803,7 @@ function materializePlansAsWorkItems(config) {
 
         if (created > 0) {
           // Reconciliation: exact prdItems match only, scoped to newly created items
-          const allPrsForReconcile = allProjects.flatMap(p => safeJsonArr(projectPrPath(p)));
+          const allPrsForReconcile = allProjects.flatMap(p => readPullRequests(p));
           const reconciled = reconcileItemsWithPrs(existingItems, allPrsForReconcile, { onlyIds: newlyCreatedIds });
           if (reconciled > 0) log('info', `Plan reconciliation: marked ${reconciled} item(s) as done → ${projName}`);
 
@@ -6887,8 +6837,7 @@ function materializePlansAsWorkItems(config) {
       for (const { itemId, projectName: rProjName, item: rItem } of deferredReopens) {
         const rProject = shared.resolveProjectSource(rProjName, allProjects, { allowCentral: false }).project;
         if (!rProject) continue;
-        const rPath = projectWorkItemsPath(rProject);
-        mutateWorkItems(rPath, items => {
+        mutateWorkItems(rProject, items => {
           const target = items.find(w => w.id === itemId);
           if (target && DONE_STATUSES.has(target.status)) {
             shared.reopenWorkItem(target);
@@ -6968,8 +6917,7 @@ function materializePlansAsWorkItems(config) {
 function clearPendingHumanFeedbackFlag(projectMeta, prId) {
   if (!prId) return;
   try {
-    const prsPath = projectPrPath(projectMeta);
-    mutatePullRequests(prsPath, prs => {
+    mutatePullRequests(projectMeta, prs => {
       const target = shared.findPrRecord(prs, prId, projectMeta);
       if (!target?.humanFeedback?.pendingFix) return;
       target.humanFeedback.pendingFix = false;
@@ -7044,7 +6992,7 @@ async function isWorktreeHeldPauseSuppressed(pr, project) {
   }
   if (!stillHeld) {
     try {
-      mutatePullRequests(projectPrPath(project), (prs) => {
+      mutatePullRequests(project, (prs) => {
         if (!Array.isArray(prs)) return prs;
         const target = shared.findPrRecord(prs, pr, project);
         if (!target) return prs;
@@ -7096,7 +7044,7 @@ function resolvePrBranch(pr) {
 function updatePrBranchResolutionState(project, pr, { branch = '', reason = '' } = {}) {
   let changed = false;
   try {
-    mutatePullRequests(projectPrPath(project), prs => {
+    mutatePullRequests(project, prs => {
       const target = shared.findPrRecord(prs, pr, project);
       if (!target) return;
       if (branch) {
@@ -7349,19 +7297,24 @@ function _resetAutoFixPausedLogState() {
 // persist — the warning is for the operator at engine startup/run time).
 const _warnedSilentDiscovery = new Set();
 
-function _warnSilentDiscoveryOnce(kind, project, dataPath, config) {
+function _warnSilentDiscoveryOnce(kind, project, config) {
   const key = `${kind}:${project?.name || project?.localPath || 'default'}`;
   if (_warnedSilentDiscovery.has(key)) return;
   let count = 0;
-  try { const arr = safeJson(dataPath); if (Array.isArray(arr)) count = arr.length; } catch {}
-  if (count <= 0) return; // empty file is fine — no warning worth surfacing
+  try {
+    const records = kind === 'pullRequests'
+      ? shared.readPullRequests(project)
+      : shared.readWorkItems(project);
+    if (Array.isArray(records)) count = records.length;
+  } catch {}
+  if (count <= 0) return;
   _warnedSilentDiscovery.add(key);
   const projName = project?.name || '(unnamed)';
   const hasBlock = !!(project?.workSources?.[kind] || config?.workSources?.[kind]);
   const hint = hasBlock
     ? `Toggle in Dashboard → Settings → Project, or set \`workSources.${kind}.enabled: true\` in config.json.`
     : `Run \`minions doctor\` to inspect, \`minions init\` if you cloned the repo without setup, or re-link the project: \`minions add ${project?.localPath || projName}\`.`;
-  log('warn', `Silent-discovery footgun: project "${projName}" has ${count} record(s) in ${path.basename(dataPath)} but workSources.${kind}.enabled is not true — engine will not pick them up. ${hint}`);
+  log('warn', `Silent-discovery footgun: project "${projName}" has ${count} ${kind} record(s) but workSources.${kind}.enabled is not true — engine will not pick them up. ${hint}`);
 }
 
 /**
@@ -7382,12 +7335,12 @@ function _logPrDispatchSkipOnce(pr, reason) {
 }
 
 /**
- * Scan pull-requests.json for PRs needing review or fixes
+ * Scan tracked PR state for records needing review or fixes.
  */
 async function discoverFromPrs(config, project) {
   const src = project?.workSources?.pullRequests || config.workSources?.pullRequests;
   if (!src?.enabled) {
-    _warnSilentDiscoveryOnce('pullRequests', project, projectPrPath(project), config);
+    _warnSilentDiscoveryOnce('pullRequests', project, config);
     return [];
   }
 
@@ -7535,7 +7488,7 @@ async function discoverFromPrs(config, project) {
           if (pr.reviewStatus !== REVIEW_STATUS.APPROVED) pr.reviewStatus = liveStatus;
           // Persist so next tick doesn't re-check
           try {
-            mutateJsonFileLocked(projectPrPath(project), data => {
+            mutatePullRequests(project, data => {
               if (!Array.isArray(data)) return data;
               const target = shared.findPrRecord(data, pr, project);
               if (target && target.reviewStatus !== REVIEW_STATUS.APPROVED) target.reviewStatus = liveStatus;
@@ -7751,7 +7704,7 @@ async function discoverFromPrs(config, project) {
           log('info', `Pre-dispatch vote check: ${pr.id} is ${liveStatus} (cached was waiting) — skipping re-review`);
           if (pr.reviewStatus !== REVIEW_STATUS.APPROVED) pr.reviewStatus = liveStatus;
           try {
-            mutateJsonFileLocked(projectPrPath(project), data => {
+            mutatePullRequests(project, data => {
               if (!Array.isArray(data)) return data;
               const target = shared.findPrRecord(data, pr, project);
               if (target && target.reviewStatus !== REVIEW_STATUS.APPROVED) target.reviewStatus = liveStatus;
@@ -7926,7 +7879,7 @@ async function discoverFromPrs(config, project) {
         const live = await checkBcFn(pr, project);
         if (live?.buildStatusStale) {
           try {
-            mutatePullRequests(projectPrPath(project), prs => {
+            mutatePullRequests(project, prs => {
               const target = shared.findPrRecord(prs, pr, project);
               if (!target) return;
               target._buildStatusStale = true;
@@ -7938,7 +7891,7 @@ async function discoverFromPrs(config, project) {
           log('info', `Pre-dispatch build check: ${pr.id} build is ${live.buildStatus} (cached was failing) — skipping build-fix`);
           // Persist the fresh status so subsequent ticks don't re-check on every pass
           try {
-            mutatePullRequests(projectPrPath(project), prs => {
+            mutatePullRequests(project, prs => {
               const target = shared.findPrRecord(prs, pr, project);
               if (!target) return;
               target.buildStatus = live.buildStatus;
@@ -8002,8 +7955,7 @@ async function discoverFromPrs(config, project) {
       if (pr.agent && !pr._buildFailNotified) {
         // Mark noted to prevent repeated processing; the fix dispatch and PR state carry the failure details.
         try {
-          const prPath = projectPrPath(project);
-          mutatePullRequests(prPath, prs => {
+          mutatePullRequests(project, prs => {
             const target = shared.findPrRecord(prs, pr, project);
             if (target) {
               target._buildFailNotified = true;
@@ -8068,7 +8020,7 @@ async function discoverFromPrs(config, project) {
           if (live && live.mergeConflict === false) {
             log('info', `Pre-dispatch conflict check: ${pr.id} reports clean merge (cached was conflict) — skipping conflict-fix`);
             try {
-              mutatePullRequests(projectPrPath(project), prs => {
+              mutatePullRequests(project, prs => {
                 const target = shared.findPrRecord(prs, pr, project);
                 if (!target) return;
                 delete target._mergeConflict;
@@ -8097,7 +8049,7 @@ async function discoverFromPrs(config, project) {
               newWork.push(item);
               // Record dispatch timestamp so re-dispatch is suppressed during ADO lag window
               try {
-                mutatePullRequests(projectPrPath(project), prs => {
+                mutatePullRequests(project, prs => {
                   const target = shared.findPrRecord(prs, pr, project);
                   if (target) target._conflictFixedAt = new Date().toISOString();
                 });
@@ -8197,7 +8149,7 @@ function _buildRunnerBriefVars(item, project) {
 }
 
 /**
- * Scan work-items.json for manually queued tasks
+ * Scan a project work-item scope for manually queued tasks.
  */
 function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, project, root, branchName, options = {}) {
   const worktreePath = options.worktreePath || path.resolve(root, config.engine?.worktreeRoot || '../worktrees', `${branchName}`);
@@ -8411,7 +8363,7 @@ function resolveWorkItemPrRecord(item, project) {
   if (!project) return null;
   const prRef = getWorkItemPrRef(item);
   if (!prRef) return null;
-  const prs = safeJsonArr(projectPrPath(project));
+  const prs = readPullRequests(project);
   shared.normalizePrRecords(prs, project);
   return shared.findPrRecord(prs, prRef, project);
 }
@@ -8478,7 +8430,7 @@ function refreshDeferredReviewPrompt(item, config) {
   // head SHA before rebuilding the prompt.
   let livePr = pr;
   try {
-    const prs = safeJsonArr(projectPrPath(project));
+    const prs = readPullRequests(project);
     const found = shared.findPrRecord(prs, pr, project);
     if (found) livePr = found;
   } catch (e) { log('warn', `refreshDeferredReviewPrompt: live PR lookup for ${pr.id} failed: ${e.message}`); }
@@ -8510,12 +8462,12 @@ function refreshDeferredReviewPrompt(item, config) {
 function discoverFromWorkItems(config, project) {
   const src = project?.workSources?.workItems || config.workSources?.workItems;
   if (!src?.enabled) {
-    _warnSilentDiscoveryOnce('workItems', project, projectWorkItemsPath(project), config);
+    _warnSilentDiscoveryOnce('workItems', project, config);
     return [];
   }
 
   const root = project?.localPath ? path.resolve(project.localPath) : path.resolve(MINIONS_DIR, '..');
-  const items = safeJsonArr(projectWorkItemsPath(project));
+  const items = readWorkItems(project);
   // W-mq9b7lor (H3): snapshot each item's serializable state BEFORE the
   // discover loop runs so we can compute per-item field deltas at the end
   // and apply them inside the mutateWorkItems lock — the prior
@@ -8625,7 +8577,7 @@ function discoverFromWorkItems(config, project) {
     }
 
     const key = `work-${project?.name || 'default'}-${item.id}`;
-    // Self-heal: collect keys for batched dispatch.json cleanup (after the loop)
+    // Self-heal: collect keys for batched dispatch cleanup.
     selfHealKeys.add(key);
     dispatchCooldowns.delete(key);
     // Cooldown bypass for resumed items
@@ -8931,7 +8883,7 @@ function discoverFromWorkItems(config, project) {
       }
     }
     if (patches.size > 0) {
-      mutateWorkItems(projectWorkItemsPath(project), (current) => {
+      mutateWorkItems(project, (current) => {
         for (const it of current) {
           const patch = patches.get(it.id);
           if (!patch) continue;
@@ -9197,10 +9149,9 @@ function materializeSpecsAsWorkItems(config, project) {
 
   if (recentSpecs.length === 0) return;
 
-  const wiPath = projectWorkItemsPath(project);
   let created = 0;
 
-  mutateWorkItems(wiPath, existingItems => {
+  mutateWorkItems(project, existingItems => {
     for (const pr of mergedPrs) {
       const prBranch = (pr.branch || '').toLowerCase();
       const matchedSpecs = recentSpecs.filter(doc => {
@@ -9287,12 +9238,11 @@ function extractSpecInfo(filePath, projectRoot_) {
 }
 
 /**
- * Scan central ~/.minions/work-items.json for project-agnostic tasks.
+ * Scan central SQL state for project-agnostic tasks.
  * Uses the shared work-item.md playbook with multi-project context injected.
  */
 function discoverCentralWorkItems(config) {
-  const centralPath = path.join(MINIONS_DIR, 'work-items.json');
-  const items = safeJsonArr(centralPath);
+  const items = readWorkItems('central');
   const projects = getProjects(config);
   const dispatchProjects = getCentralDispatchProjects(projects);
   const newWork = [];
@@ -9592,7 +9542,6 @@ function discoverCentralWorkItems(config) {
       // Inject plan-to-prd variables — read the plan file content for the playbook
       if (workType === WORK_TYPE.PLAN_TO_PRD && item.planFile) {
         if (!fs.existsSync(PLANS_DIR)) fs.mkdirSync(PLANS_DIR, { recursive: true });
-        if (!fs.existsSync(PRD_DIR)) fs.mkdirSync(PRD_DIR, { recursive: true });
         if (planFileContent !== null) {
           vars.plan_content = planFileContent;
         } else {
@@ -9634,7 +9583,7 @@ function discoverCentralWorkItems(config) {
         const prdRows = prdStore.listPrdRows();
         const prdFiles = prdRows.filter(row => !row.archived).map(row => row.filename);
         for (const pf of prdFiles) {
-          const prd = prdStore.readPrd(path.join(PRD_DIR, pf));
+          const prd = prdStore.readPrd(pf);
           if (planKey && prd && !shared.isPrdArchived(prd) && shared.prdMatchesSourcePlan(prd.source_plan, planKey)) {
             prdFilename = pf;
             vars.existing_prd_json = JSON.stringify(prd, null, 2);
@@ -9733,53 +9682,20 @@ function discoverCentralWorkItems(config) {
   }
 
   if (mutations.size > 0) {
-    // True atomic read-modify-write — applies mutations to fresh locked data
-    mutateJsonFileLocked(centralPath, (freshItems) => {
+    // Apply field patches to a fresh transactional snapshot.
+    mutateWorkItems('central', (freshItems) => {
       if (!Array.isArray(freshItems)) freshItems = [];
       for (const fi of freshItems) {
         const m = mutations.get(fi.id);
         if (m) Object.assign(fi, m);
       }
       return freshItems;
-    }, { defaultValue: [] });
+    });
   }
   return newWork;
 }
 
 
-/**
- * Sweep stale `.backup` sidecars in `prd/` whose archived counterpart already
- * lives in `prd/archive/<name>.json` and the active `prd/<name>.json` is
- * absent. Pre-neutralize-era archives left these sidecars behind; without this
- * sweep, any caller that touched `prd/<name>.json` with the restore-enabled
- * `safeJson` would resurrect the archived PRD as active (W-mouptdh1000h9f39).
- *
- * Idempotent and best-effort: readdir / existsSync / unlink failures are
- * swallowed so a single weird filesystem state never blocks the discovery
- * tick. Returns the number of sidecars purged (for tests / logging).
- */
-function sweepStaleArchivedPrdBackups(prdDir, prdArchiveDir) {
-  let purged = 0;
-  if (!fs.existsSync(prdArchiveDir)) return purged;
-  let archivedNames;
-  try { archivedNames = fs.readdirSync(prdArchiveDir).filter(f => f.endsWith('.json')); }
-  catch { return purged; }
-  for (const f of archivedNames) {
-    const activePath = path.join(prdDir, f);
-    const backupPath = activePath + '.backup';
-    // Active PRD wins — the dedicated ghost-PRD purge in discoverWork handles
-    // the case where both active.json and active.json.backup are present.
-    if (fs.existsSync(activePath)) continue;
-    if (!fs.existsSync(backupPath)) continue;
-    try {
-      fs.unlinkSync(backupPath);
-      purged++;
-      log('info', `Purged stale .backup sidecar for archived PRD: ${f}`);
-    } catch { /* best-effort */ }
-  }
-  return purged;
-}
-
 /**
  * Run all work discovery sources and queue new items
  * Priority: fix (0) > ask (1) > review (1) > implement (2) > work-items (3) > central (4)
@@ -9789,7 +9705,7 @@ async function discoverWork(config) {
   const projects = getProjects(config);
   let persistedFixes = 0, persistedReviews = 0, persistedOther = 0;
 
-  // Side-effect passes: materialize plans and design docs into work-items.json
+  // Side-effect passes: materialize plans and design docs into SQL work-item state.
   // These write to project work queues — picked up by discoverFromWorkItems below.
   // Gated by config.engine?.planMaterializationEnabled !== false (P-d6f0a2b5) —
   // operators can suppress the PRD reconcile + plan materialization pair
@@ -9813,10 +9729,10 @@ async function discoverWork(config) {
   // projects)` loop below leaves this whole async function permanently
   // unresolved, so anything only collected into a local array and persisted
   // at the very end (the pre-fix allFixes/allReviews/allWorkItems) never
-  // reaches dispatch.json — silently discarding valid work already
+  // reaches dispatch state — silently discarding valid work already
   // discovered for unrelated, healthy projects processed earlier in the same
   // loop. Persisting per batch means a healthy project's discoveries land in
-  // dispatch.json immediately, before the loop ever reaches a slow project.
+  // dispatch state immediately, before the loop reaches a slow project.
   async function persistBatch(items) {
     if (!items || items.length === 0) return;
     // Gate reviews and fixes: only when at max concurrency — idle agents should pick up reviews
@@ -9869,7 +9785,7 @@ async function discoverWork(config) {
         } catch (e) {
           // Fail-open contract preserved: any validator throw here means the
           // item is dropped from this discovery batch rather than wedging the
-          // whole chunk. The item stays `pending` in work-items.json and the
+          // whole chunk. The item stays pending in SQL and the
           // next tick re-discovers it.
           log('warn', `pre-dispatch-eval: addToDispatchWithValidation threw for ${item?.meta?.item?.id || item?.id || 'unknown'}: ${e?.message || e}`);
         }
@@ -9945,7 +9861,6 @@ async function discoverWork(config) {
       const scheduledWork = discoverScheduledWork(config);
       if (scheduledWork.length > 0) {
         const { createMeeting, getMeetings } = require('./engine/meeting');
-        const centralPath = path.join(MINIONS_DIR, 'work-items.json');
         // Separate meetings (no work-items write) from task items
         const taskItems = [];
         for (const item of scheduledWork) {
@@ -9959,8 +9874,7 @@ async function discoverWork(config) {
           }
         }
         if (taskItems.length > 0) {
-          // Atomic write — prevents race with dispatch status updates on central work-items.json
-          mutateJsonFileLocked(centralPath, (items) => {
+          mutateWorkItems('central', (items) => {
             if (!Array.isArray(items)) items = [];
             let added = 0;
             // Snapshot active dedup keys BEFORE the loop so multiple items in the
@@ -9996,7 +9910,7 @@ async function discoverWork(config) {
               log('info', `Scheduled task fired: ${item._scheduleId} → ${item.title}`);
             }
             return items;
-          }, { defaultValue: [] });
+          });
         }
       }
     } catch (e) { log('warn', 'discover scheduled work: ' + e.message); }
@@ -10022,51 +9936,19 @@ async function discoverWork(config) {
   if (tickCount % (ENGINE_DEFAULTS.planCompletionScanEvery || 60) === 0) {
     try {
       const lifecycle = require('./engine/lifecycle');
-      const prdDir = path.join(MINIONS_DIR, 'prd');
-      const prdArchiveDir = path.join(prdDir, 'archive');
-      if (fs.existsSync(prdDir)) {
-        // Pass 1 — Burn the landmine: stale .backup sidecars whose archived
-        // counterpart already lives in prd/archive/ but no active prd/<f>.json.
-        // Without this, any future safeJson(prd/<f>.json) (or stray legacy
-        // call) would auto-restore the .backup and resurrect the archived PRD
-        // (W-mouptdh1000h9f39). Idempotent and fast — readdir + existsSync.
-        sweepStaleArchivedPrdBackups(prdDir, prdArchiveDir);
-
-        // Pass 2 — completion sweep. (The ghost-PRD purge that used to live here
-        // was a REDUNDANT + UNSAFE duplicate of the plan-completion scan's
-        // version: it unlinked prd/<f> whenever prd/archive/<f> existed, with NO
-        // `_isGhostPrdRestore` identity check — the exact footgun #7 (#496)
-        // hazard of deleting a legitimately re-opened PRD that shares an archived
-        // basename. The plan-completion scan does the same purge safely (identity-
-        // checked + neutralize); here the isDefunctPrd guard below already skips
-        // archived/defunct PRDs, so this loop never re-runs completion on a ghost.)
-        for (const f of prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename)) {
-          if (completedPlanCache.has(f)) continue;
-          // safeJsonNoRestore — defense in depth: if the file vanished between
-          // readdir and read (e.g. concurrent archive), do not resurrect it
-          // from a stale .backup sidecar (W-mouptdh1000h9f39).
-          const plan = safeJsonNoRestore(path.join(prdDir, f));
-          if (!plan?.missing_features) continue;
-          // Resurrection guard (mirror of completion-scan-B / #523): never re-run
-          // completion (which re-creates the verify gate) for a defunct PRD —
-          // archived, or completed with its plan gone from plans/.
-          if (shared.isDefunctPrd(plan, PLANS_DIR)) { completedPlanCache.add(f); continue; }
-          // A completed PRD may still be missing its aggregate verify WI — e.g. it
-          // landed on disk pre-completed via the plan-to-prd / pipeline path, so no
-          // agent-completion event ever drove checkPlanCompletion (W-mqk5ld3p). The
-          // function is idempotent (re-checks for an existing verify WI under lock),
-          // so run it for completed plans too and cache only once it reports nothing
-          // left to do (truthy return).
-          if (plan.status === PLAN_STATUS.COMPLETED) {
-            const done = lifecycle.checkPlanCompletion({ item: { sourcePlan: f } }, config);
-            if (done) completedPlanCache.add(f);
-            continue;
-          }
-          if (plan.status !== PLAN_STATUS.APPROVED && plan.status !== PLAN_STATUS.ACTIVE) continue;
-          // Simulate the meta object checkPlanCompletion expects
-          const completed = lifecycle.checkPlanCompletion({ item: { sourcePlan: f } }, config);
-          if (completed) completedPlanCache.add(f);
+      for (const f of prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename)) {
+        if (completedPlanCache.has(f)) continue;
+        const plan = prdStore.readPrd(f);
+        if (!plan?.missing_features) continue;
+        if (shared.isDefunctPrd(plan, PLANS_DIR)) { completedPlanCache.add(f); continue; }
+        if (plan.status === PLAN_STATUS.COMPLETED) {
+          const done = lifecycle.checkPlanCompletion({ item: { sourcePlan: f } }, config);
+          if (done) completedPlanCache.add(f);
+          continue;
         }
+        if (plan.status !== PLAN_STATUS.APPROVED && plan.status !== PLAN_STATUS.ACTIVE) continue;
+        const completed = lifecycle.checkPlanCompletion({ item: { sourcePlan: f } }, config);
+        if (completed) completedPlanCache.add(f);
       }
     } catch (e) { log('warn', 'plan completion sweep: ' + e.message); }
   }
@@ -10190,26 +10072,6 @@ const completedPlanCache = new Set();
 // Dedupe the "Skipping defunct PRD" materializer log so a lingering defunct PRD
 // doesn't spam one line per discovery tick; cleared when the file stops being defunct.
 const _defunctPrdSkipLogged = new Set();
-// Filenames where a live PRD shares a basename with an archived PRD but diverges
-// (different source_plan / introduces new work). We refuse to auto-purge those
-// and warn once instead of every tick. (RC4 — footgun #7 collision protection.)
-const _ghostPurgeCollisionWarned = new Set();
-
-// True when a live PRD that shares a basename with an archived one is merely a
-// stale echo of the archive (a .backup ghost-restore), safe to purge. False when
-// it's a genuinely distinct re-opened PRD that must NOT be silently deleted.
-// Conservative: if either file is unreadable we fall back to the legacy
-// "purge the ghost" behavior so we don't regress resurrection cleanup.
-function _isGhostPrdRestore(live, archived) {
-  if (!live || !archived) return true;
-  const ls = live.source_plan || live.sourcePlan;
-  const as = archived.source_plan || archived.sourcePlan;
-  if (ls && as && ls !== as) return false; // different plan identity → real PRD
-  const archivedIds = new Set((archived.missing_features || []).map(f => f && f.id).filter(Boolean));
-  const hasNewWork = (live.missing_features || []).some(f => f && f.id && !archivedIds.has(f.id));
-  if (hasNewWork) return false; // introduces work the archive never had → real PRD
-  return true; // same identity, no new work → stale echo → ghost
-}
 let lastWatchCheckAt = 0;
 let lastPrStatusPollAt = 0;
 let lastPrCommentsPollAt = 0;
@@ -10437,7 +10299,7 @@ async function tickInner() {
   }
 
   // 2.53. managed-spawn TTL/dead-PID sweep + log rotation (P-8a4d6f29). Walks
-  // engine/managed-processes.json, kills TTL-expired specs, drops dead-PID
+  // SQL managed-process state, kills TTL-expired specs, drops dead-PID
   // rows, rotates managed-logs/<name>.log past ENGINE_DEFAULTS.managedSpawn
   // .logRotateBytes. Mirrors the keep-processes sweep cadence (sweepEvery=180)
   // so the engine never iterates per-spec on every tick. Healthcheck loops
@@ -10484,16 +10346,12 @@ async function tickInner() {
     safe('checkWatches', () => {
       const { checkWatches } = require('./engine/watches');
       const projects = getProjects(config);
-      const pullRequests = projects.flatMap(p => {
-        const prPath = path.join(MINIONS_DIR, 'projects', p.name, 'pull-requests.json');
-        return safeJsonArr(prPath);
-      });
-      const workItems = projects.flatMap(p => {
-        const wiPath = path.join(MINIONS_DIR, 'projects', p.name, 'work-items.json');
-        return safeJsonArr(wiPath);
-      });
+      const pullRequestStore = require('./engine/pull-requests-store');
+      const workItemStore = require('./engine/work-items-store');
+      const pullRequests = projects.flatMap(p => pullRequestStore.readPullRequestsForScope(p.name));
+      const workItems = projects.flatMap(p => workItemStore.readWorkItemsForScope(p.name));
       // Also include central work items
-      const centralWi = safeJsonArr(path.join(MINIONS_DIR, 'work-items.json'));
+      const centralWi = workItemStore.readWorkItemsForScope('central');
 
       // Gather state for the new generalized target types. Each block is
       // best-effort — if a module/file is missing the watch evaluator will
@@ -10501,23 +10359,11 @@ async function tickInner() {
       let meetings = [];
       try { meetings = require('./engine/meeting').getMeetings(); } catch { /* optional */ }
 
-      // Plans/PRDs — read PRD JSON files directly so plan-level watches see
-      // status transitions (approved/rejected/completed/etc.). Each entry
-      // carries its filename in _source for target lookup.
-      const plans = [];
-      try {
-        const prdDir = path.join(MINIONS_DIR, 'prd');
-        for (const dir of [prdDir, path.join(prdDir, 'archive')]) {
-          if (!fs.existsSync(dir)) continue;
-          for (const f of fs.readdirSync(dir).filter(x => x.endsWith('.json'))) {
-            const plan = safeJson(path.join(dir, f));
-            if (plan) plans.push({ ...plan, _source: f, _sourcePlan: plan.source_plan || '' });
-          }
-        }
-      } catch { /* optional */ }
+      const plans = require('./engine/prd-store').listPrdRows()
+        .map(({ filename, plan }) => ({ ...plan, _source: filename, _sourcePlan: plan.source_plan || '' }));
 
       let scheduleRuns = {};
-      try { scheduleRuns = safeJsonObj(path.join(MINIONS_DIR, 'engine', 'schedule-runs.json')); } catch { /* optional */ }
+      try { scheduleRuns = require('./engine/small-state-store').readScheduleRuns(); } catch { /* optional */ }
 
       let pipelineRuns = {};
       try { pipelineRuns = require('./engine/pipeline').getPipelineRuns(); } catch { /* optional */ }
@@ -10617,29 +10463,7 @@ async function tickInner() {
       const prdFiles = prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
       for (const file of prdFiles) {
         if (completedPlanCache.has(file)) continue;
-        if (fs.existsSync(path.join(PRD_DIR, 'archive', file))) {
-          // A live PRD basename also exists in the archive. Historically this was
-          // unconditionally treated as an orphaned .backup ghost-restore and purged
-          // — but a re-opened plan can legitimately create a NEW live PRD sharing
-          // an archived basename (footgun #7). Identity-check before deleting so we
-          // never silently destroy a real divergent PRD.
-          const liveP = safeJsonNoRestore(path.join(PRD_DIR, file));
-          const archP = safeJsonNoRestore(path.join(PRD_DIR, 'archive', file));
-          if (_isGhostPrdRestore(liveP, archP)) {
-            // Orphaned backup restore — plan is already archived. Purge the ghost copy.
-            try { fs.unlinkSync(path.join(PRD_DIR, file)); } catch { }
-            shared.neutralizeJsonBackupSidecar(path.join(PRD_DIR, file));
-            completedPlanCache.add(file);
-            continue;
-          }
-          // Divergent live PRD — do NOT delete. Warn once and fall through to the
-          // normal completion handling below so it's treated as a real PRD.
-          if (!_ghostPurgeCollisionWarned.has(file)) {
-            log('warn', `PRD ${file} shares a basename with an archived PRD but diverges (different source_plan or new work) — NOT purging; resolve the collision manually`);
-            _ghostPurgeCollisionWarned.add(file);
-          }
-        }
-        const plan = safeJson(path.join(PRD_DIR, file));
+        const plan = prdStore.readPrd(file);
         // Resurrection-re-execution guard: a defunct PRD (archived, or completed
         // with its source plan gone from plans/) must NOT have its verify gate
         // re-created. This scan deliberately re-runs completion for completed
@@ -10753,13 +10577,12 @@ async function tickInner() {
         // Check for failed items blocking pending items
         for (const project of projects) {
           try {
-            const wiPath = projectWorkItemsPath(project);
             // Collect keys to clear AFTER work-items lock is released (avoid nested locks)
             const dispatchKeysToClear = [];
             const cooldownKeysToClear = [];
 
             if (_isTickStale(myGeneration)) return;
-            mutateWorkItems(wiPath, items => {
+            mutateWorkItems(project, items => {
               let changed = false;
               const failedIds = new Set(items.filter(w => w.status === WI_STATUS.FAILED).map(w => w.id));
               const pendingWithBlockedDeps = items.filter(w =>
@@ -11022,7 +10845,7 @@ async function tickInner() {
         assignPendingDispatchAgent(item, altAgent, config);
         pendingAgents.add(altAgent);
         log('info', `Reassigning ${item.id} from unspawned temp ${prevAgent} to ${altAgent} — temp agent never spawned`);
-        // Persist reassignment to dispatch.json so it survives restarts/ticks
+        // Persist reassignment so it survives restarts/ticks.
         persistPendingDispatchAgent(item);
       }
     }
@@ -11258,12 +11081,10 @@ async function tickInner() {
       // Defensive: ensure the work item is re-queued if completeDispatch didn't fire
       if (item.meta?.item?.id) {
         try {
-          const wiPath = item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout'
-            ? path.join(ENGINE_DIR, '..', 'work-items.json')
-            : item.meta.project?.name ? projectWorkItemsPath({ name: item.meta.project.name, localPath: item.meta.project.localPath }) : null;
-          if (wiPath) {
+          const wiScope = resolveWorkItemScope(item.meta);
+          if (wiScope) {
             if (_isTickStale(myGeneration)) return;
-            mutateWorkItems(wiPath, items => {
+            mutateWorkItems(wiScope, items => {
               const wi = items.find(i => i.id === item.meta.item.id);
               if (wi && wi.status === WI_STATUS.DISPATCHED) {
                 // completeDispatch didn't update the work item — re-queue manually
@@ -11386,8 +11207,8 @@ async function tickInner() {
     // clobbered. Previously the mutator callback assigned dp.pending from the
     // pre-lock postDispatch snapshot, overwriting any freshly loaded queue
     // entries. Sentinel-undefined for _pendingReason / _agentBusySince
-    // mirrors the in-loop `delete` semantics — JSON serialization drops
-    // undefined-valued keys, so SQL → JSON mirror stays consistent.
+    // mirrors the in-loop `delete` semantics — the SQL store serializes
+    // records without undefined-valued keys.
     const patches = new Map();
     for (const item of (postDispatch.pending || [])) {
       patches.set(item.id, {
@@ -11503,7 +11324,7 @@ function emitMemoryBaseline(tickN) {
 module.exports = {
   // Paths
   MINIONS_DIR, ENGINE_DIR, AGENTS_DIR, PLAYBOOKS_DIR, PLANS_DIR, PRD_DIR,
-  CONTROL_PATH, DISPATCH_PATH, LOG_PATH, INBOX_DIR, KNOWLEDGE_DIR, ARCHIVE_DIR,
+  CONTROL_PATH, INBOX_DIR, KNOWLEDGE_DIR, ARCHIVE_DIR,
   IDENTITY_DIR, CONFIG_PATH, ROUTING_PATH, NOTES_PATH, SKILLS_DIR,
 
   // Utilities
@@ -11528,10 +11349,7 @@ module.exports = {
   discoverWork, discoverFromPrs, discoverFromWorkItems, discoverCentralWorkItems,
   materializePlansAsWorkItems,
   materializeSpecsAsWorkItems, // exported for testing (P-f7-git-log)
-  reservePrdFilename, // exported for testing (P-9b7e5d3c)
   restoreHijackedOperatorCheckouts, // exported for testing — operator-checkout self-heal
-  sweepStaleArchivedPrdBackups, // exported for testing
-  _isGhostPrdRestore, // exported for testing (RC4 — ghost-purge identity check)
 
   // Shared helpers (used by lifecycle.js and tests)
   reconcileItemsWithPrs, detectDependencyCycles,