@yemi33/minions 0.1.2378 → 0.1.2380

package/engine/cli.js

@@ -6,10 +6,11 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeRead, safeJson, safeJsonArr, safeWrite, mutateControl, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, REVIEW_STATUS, DISPATCH_RESULT } = shared;
+const { safeRead, safeJson, safeJsonArr, safeWrite, readWorkItems, readPullRequests, mutateControl, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, REVIEW_STATUS, DISPATCH_RESULT, FAILURE_CLASS } = shared;
 const queries = require('./queries');
+const agentWorkerPool = require('./agent-worker-pool');
 const { getConfig, getControl, getDispatch, getAgentStatus,
-  MINIONS_DIR, ENGINE_DIR, AGENTS_DIR, PLANS_DIR, PRD_DIR, CONTROL_PATH, DISPATCH_PATH } = queries;
+  MINIONS_DIR, ENGINE_DIR, AGENTS_DIR, PLANS_DIR, PRD_DIR, CONTROL_PATH } = queries;
 
 // Lazy require — only for engine-specific functions (log, ts, tick, addToDispatch, etc.)
 let _engine = null;
@@ -242,7 +243,7 @@ const CLI_COMMAND_DOCS = Object.freeze({
   discover: { args: '',                      summary: 'Dry-run work discovery' },
   dispatch: { args: '',                      summary: 'Force a dispatch cycle' },
   spawn:    { args: '<agent> <prompt>',      summary: 'Manually spawn an agent with prompt' },
-  work:     { args: '<title> [opts]',        summary: 'Add to work-items.json queue' },
+  work:     { args: '<title> [opts]',        summary: 'Add to the work-item queue' },
   plan:     { args: '<file|text> [project]', summary: 'Generate PRD from a plan (file or text)' },
   kill:       { args: '',                      summary: 'Kill all active agents, reset to pending' },
   complete:   { args: '<dispatch-id>',         summary: 'Mark a dispatch as done' },
@@ -540,7 +541,7 @@ const commands = {
     // auto-archived back then left the WI pill pointing at the gone
     // notes/inbox/<name> path; this repoints them to the archived/KB location.
     // Idempotent (only touches provably-broken + resolvable links) and routed
-    // through mutateWorkItems so SQL + JSON mirror stay consistent — a no-op
+    // through mutateWorkItems so the repair is transactional — a no-op
     // once healed, so it's safe to run on every boot.
     try {
       const res = require('./note-link-backfill').runNoteLinkBackfill({ config });
@@ -596,7 +597,7 @@ const commands = {
         console.log(`  WARNING: ${p.name} path not found: ${p.localPath}`);
       } else {
         try {
-          shared.ensureProjectStateFiles(p);
+          shared.initializeProjectState(p);
         } catch (err) {
           e.log('warn', `Project state setup failed for "${p.name}": ${err.message}`);
         }
@@ -683,8 +684,7 @@ const commands = {
           // Sync work item status to dispatched — atomic write to avoid lifecycle lazy init issues
           if (item.meta?.item?.id && item.meta?.project?.localPath) {
             try {
-              const wiPath = path.join(MINIONS_DIR, "projects", item.meta.project.name, "work-items.json");
-              mutateWorkItems(wiPath, items => {
+              mutateWorkItems(item.meta.project.name, items => {
                 const wi = items.find(w => w.id === item.meta.item.id);
                 if (wi && wi.status !== WI_STATUS.DISPATCHED) {
                   wi.status = WI_STATUS.DISPATCHED;
@@ -756,13 +756,12 @@ const commands = {
             isSuccess = true;
           }
 
-          // Fallback: check pull-requests.json for a matching PR by work item ID
+          // Fallback: check tracked PR state for a matching work item ID.
           if (!isSuccess && item.meta?.item?.id) {
             try {
               const projName = item.meta.project?.name;
               if (projName) {
-                const prPath = path.join(MINIONS_DIR, 'projects', projName, 'pull-requests.json');
-                const prs = safeJsonArr(prPath);
+                const prs = readPullRequests(projName);
                 const matchingPr = prs.find(pr =>
                   (pr.prdItems || []).includes(item.meta.item.id) &&
                   pr.status !== 'abandoned' && pr.status !== 'closed'
@@ -788,8 +787,7 @@ const commands = {
               try {
                 const projName = item.meta.project?.name;
                 if (projName) {
-                  const wiPath = path.join(MINIONS_DIR, 'projects', projName, 'work-items.json');
-                  mutateWorkItems(wiPath, items => {
+                  mutateWorkItems(projName, items => {
                     const wi = items.find(w => w.id === item.meta.item.id);
                     if (wi) {
                       wi.status = status;
@@ -855,13 +853,10 @@ const commands = {
       let fixes = 0;
 
       const activeIds = new Set((dispatch.active || []).map(d => d.meta?.item?.id).filter(Boolean));
-      const allWiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
-      for (const p of projects) {
-        allWiPaths.push(path.join(MINIONS_DIR, "projects", p.name, "work-items.json"));
-      }
-      for (const wiPath of allWiPaths) {
+      const workItemScopes = ['central', ...projects];
+      for (const scope of workItemScopes) {
         try {
-          mutateWorkItems(wiPath, items => {
+          mutateWorkItems(scope, items => {
             for (const item of items) {
               if (item.status === WI_STATUS.DISPATCHED && !activeIds.has(item.id)) {
                 item.status = WI_STATUS.PENDING;
@@ -887,7 +882,7 @@ const commands = {
     // fix prevents future false-flips, this pass un-flips PRs that were
     // already wrongly marked `abandoned` before the hardening shipped (e.g.
     // the 16 PRs hit by the 2026-05-14 gh-auth-flip incident). Version-gated
-    // via engine/state.json so it runs once per ENGINE_DEFAULTS.abandonedReconciliationVersion
+    // in SQL so it runs once per ENGINE_DEFAULTS.abandonedReconciliationVersion
     // bump and is otherwise a no-op. Fire-and-forget — boot must not block on
     // network calls; the pass operates on `abandoned` PRs while pollPrStatus
     // operates on `active`/`linked`, so there is no per-record race.
@@ -925,7 +920,7 @@ const commands = {
     })();
 
     // P-8a4d6f29 — Boot reconcile for managed-spawn: drop dead-PID rows from
-    // engine/managed-processes.json, kill TTL-expired specs, re-probe
+    // managed-process state, kill TTL-expired specs, re-probe
     // survivors once. Wrapped in Promise.race against
     // ENGINE_DEFAULTS.managedSpawn.bootReconcileMaxMs (2s default) so a
     // malformed or oversized state file cannot block engine boot. Async +
@@ -1101,6 +1096,9 @@ const commands = {
         });
         e.tick();
       }
+      if (ctrl._shutdownRequestedAt) {
+        gracefulShutdown('shutdown request');
+      }
     }, 1000);
 
     console.log(`Tick interval: ${interval / 1000}s | Max concurrent: ${config.engine?.maxConcurrent || 5}`);
@@ -1140,7 +1138,8 @@ const commands = {
       catch (err) { console.error(`[shutdown] flushLogs failed: ${err.message}`); }
     }
 
-    // Graceful shutdown — wait for active agents before exiting
+    // Graceful shutdown drains non-reattachable pooled leases. Detached cold
+    // agents intentionally survive for normal restart reattachment.
     let shuttingDown = false;
     function gracefulShutdown(signal) {
       if (shuttingDown) return;
@@ -1157,43 +1156,77 @@ const commands = {
       }
       e.log('info', `Graceful shutdown initiated (${signal})`);
 
-      if (e.activeProcesses.size === 0) {
+      agentWorkerPool.beginDrain();
+
+      function getPooledDispatchIds() {
+        return [...e.activeProcesses.entries()]
+          .filter(([, procInfo]) => procInfo?._pooled)
+          .map(([id]) => id);
+      }
+
+      const drainingPooledIds = new Set([
+        ...getPooledDispatchIds(),
+        ...(getDispatch().active || []).filter(item => item.pooled).map(item => item.id),
+      ]);
+
+      function getOutstandingPooledIds() {
+        const persistedActiveIds = new Set((getDispatch().active || []).map(item => item.id));
+        const outstanding = new Set(getPooledDispatchIds());
+        for (const id of drainingPooledIds) {
+          if (persistedActiveIds.has(id)) outstanding.add(id);
+        }
+        return [...outstanding];
+      }
+
+      function finishShutdown(message, exitCode = 0) {
+        agentWorkerPool.shutdown();
         const stoppedWrite = markControlStoppedForOwner(controlOwner, e.ts());
         if (!stoppedWrite.changed) {
           e.log('warn', 'Graceful shutdown skipped control.json stopped transition; control file is owned by a different engine process');
         }
-        e.log('info', 'Graceful shutdown complete (no active agents)');
+        e.log(exitCode === 0 ? 'info' : 'warn', message);
         drainBuffers();
-        console.log('No active agents — stopped.');
-        process.exit(0);
+        console.log(message);
+        process.exit(exitCode);
+      }
+
+      let pooledIds = getOutstandingPooledIds();
+      if (pooledIds.length === 0 && agentWorkerPool.isDrained()) {
+        finishShutdown('No active pooled agents — stopped.');
+        return;
       }
 
-      console.log(`Waiting for ${e.activeProcesses.size} active agent(s) to finish...`);
+      console.log(`Waiting for ${pooledIds.length || 1} active pooled agent(s) to finish...`);
       const timeout = config.engine?.shutdownTimeout || shared.ENGINE_DEFAULTS.shutdownTimeout;
       const deadline = Date.now() + timeout;
 
       const poll = setInterval(() => {
-        if (e.activeProcesses.size === 0) {
+        pooledIds = getOutstandingPooledIds();
+        if (pooledIds.length === 0 && agentWorkerPool.isDrained()) {
           clearInterval(poll);
-          const stoppedWrite = markControlStoppedForOwner(controlOwner, e.ts());
-          if (!stoppedWrite.changed) {
-            e.log('warn', 'Graceful shutdown skipped control.json stopped transition; control file is owned by a different engine process');
-          }
-          e.log('info', 'Graceful shutdown complete (all agents finished)');
-          drainBuffers();
-          console.log('All agents finished — stopped.');
-          process.exit(0);
+          finishShutdown('All pooled agents finished — stopped.');
+          return;
         }
         if (Date.now() >= deadline) {
           clearInterval(poll);
-          const stoppedWrite = markControlStoppedForOwner(controlOwner, e.ts());
-          if (!stoppedWrite.changed) {
-            e.log('warn', 'Graceful shutdown skipped control.json stopped transition; control file is owned by a different engine process');
+          for (const id of pooledIds) {
+            const procInfo = e.activeProcesses.get(id);
+            if (procInfo?._pooled) {
+              try { procInfo.proc.kill(); } catch (err) {
+                e.log('warn', `Failed to cancel pooled dispatch ${id} during shutdown: ${err.message}`);
+              }
+              e.activeProcesses.delete(id);
+              e.realActivityMap.delete(id);
+            }
+            e.completeDispatch(
+              id,
+              DISPATCH_RESULT.ERROR,
+              'Pooled dispatch cancelled after graceful shutdown timeout',
+              '',
+              { failureClass: FAILURE_CLASS.TIMEOUT, retryable: true },
+            );
           }
-          e.log('warn', `Graceful shutdown timed out after ${timeout / 1000}s with ${e.activeProcesses.size} agent(s) still active`);
-          drainBuffers();
-          console.log(`Shutdown timeout (${timeout / 1000}s) — force exiting with ${e.activeProcesses.size} agent(s) still running.`);
-          process.exit(1);
+          finishShutdown(`Shutdown timeout (${timeout / 1000}s) — cancelled ${pooledIds.length} pooled agent(s) for retry.`, 1);
         }
       }, 2000);
     }
@@ -1230,8 +1263,7 @@ const commands = {
       for (const item of active) {
         console.log(`    - ${item.agentName || item.agent}: ${(item.task || '').slice(0, 80)}`);
       }
-      console.log('\n  These agents will continue running but the engine won\'t monitor them.');
-      console.log('  On next start, they\'ll get a 20-min grace period before being marked as orphans.');
+      console.log('\n  Detached agents will continue for restart reattachment; pooled agents will drain before exit.');
       console.log('  To kill them now, run: node engine.js kill\n');
     }
     // Write stop-intent BEFORE killing so the external supervisor (engine/
@@ -1243,11 +1275,18 @@ const commands = {
       e.log('warn', 'Failed to write stop-intent');
     }
     const control = getControl();
-    if (control.pid && control.pid !== process.pid) {
-      // killGracefully so the engine's SIGTERM graceful-shutdown handler runs
-      // and recurses into the child tree (bare process.kill defaults to a
-      // non-recursing SIGTERM that is Windows-broken — CLAUDE.md Footgun #4).
-      shared.killGracefully({ pid: control.pid });
+    if (control.pid && control.pid !== process.pid && isEngineProcessAlive(control)) {
+      // Cross-platform shutdown request. Do not use killGracefully here:
+      // taskkill /T would terminate pooled and detached cold-agent children
+      // before the daemon can drain/reattach them correctly.
+      mutateControl(current => ({
+        ...current,
+        _shutdownRequestedAt: Date.now(),
+        _shutdownRequestedByPid: process.pid,
+      }));
+      e.log('info', `Engine shutdown requested (PID ${control.pid})`);
+      console.log('Engine shutdown requested.');
+      return;
     }
     mutateControl(() => ({ state: 'stopped', stopped_at: e.ts() }));
     e.log('info', 'Engine stopped');
@@ -1528,7 +1567,7 @@ const commands = {
     }
 
     const config = getConfig();
-    const { getProjects, projectWorkItemsPath, resolveProjectSource, uid, safeJsonArr } = require('./shared');
+    const { getProjects, resolveProjectSource, uid } = require('./shared');
     const projects = getProjects(config);
     const target = opts.project ? resolveProjectSource(opts.project, projects, { allowCentral: false }) : null;
     if (target?.error) {
@@ -1540,8 +1579,7 @@ const commands = {
       console.log('No projects configured. Add a project before running work.');
       return;
     }
-    const wiPath = projectWorkItemsPath(targetProject);
-    const archivePath = wiPath.replace(/\.json$/, '-archive.json');
+    const scope = targetProject.name;
 
     // Caller-supplied id: validate and pre-check live + archive for collisions
     // BEFORE acquiring the work-items lock, so a rejection never mutates state.
@@ -1552,17 +1590,17 @@ const commands = {
         process.exit(1);
       }
       requestedId = opts.id.trim();
-      const liveItems = safeJsonArr(wiPath);
-      const archivedItems = safeJsonArr(archivePath);
+      const liveItems = readWorkItems(scope);
+      const archivedItems = require('./work-items-store').readArchivedWorkItemsForScope(scope);
       if (liveItems.some(w => w?.id === requestedId) || archivedItems.some(w => w?.id === requestedId)) {
-        console.log(`Error: work item id "${requestedId}" already exists in ${path.basename(wiPath)} or its archive`);
+        console.log(`Error: work item id "${requestedId}" already exists in scope "${scope}" or its archive`);
         process.exit(1);
       }
     }
 
     let item;
     let collision = false;
-    mutateWorkItems(wiPath, items => {
+    mutateWorkItems(scope, items => {
       const id = requestedId || ('W-' + uid());
       // Re-check inside the lock to close the TOCTOU race against other writers.
       if (items.some(w => w?.id === id)) {
@@ -1731,9 +1769,17 @@ const commands = {
         console.log(`  ${name}: ${status}`);
 
         let filePath = null;
-        if (name === 'workItems') filePath = shared.projectWorkItemsPath(project);
-        else if (name === 'pullRequests') filePath = shared.projectPrPath(project);
-        else if (src.path) filePath = path.resolve(root, src.path);
+        let workItems = null;
+        let pullRequests = null;
+        if (name === 'workItems') {
+          workItems = readWorkItems(project);
+          console.log(`    Store: SQLite scope ${project.name}`);
+        } else if (name === 'pullRequests') {
+          pullRequests = readPullRequests(project);
+          console.log(`    Store: SQLite scope ${project.name}`);
+        } else if (src.path) {
+          filePath = path.resolve(root, src.path);
+        }
         const exists = filePath && fs.existsSync(filePath);
         if (filePath) {
           console.log(`    Path: ${filePath} ${exists ? '(found)' : '(NOT FOUND)'}`);
@@ -1747,15 +1793,13 @@ const commands = {
             console.log(`    Items: ${missing.length} missing features`);
           }
         }
-        if (exists && name === 'pullRequests') {
-          const prs = safeJsonArr(filePath);
-          const pending = prs.filter(p => p.status === PR_STATUS.ACTIVE && (p.reviewStatus === REVIEW_STATUS.PENDING || p.reviewStatus === REVIEW_STATUS.WAITING));
-          const needsFix = prs.filter(p => p.status === PR_STATUS.ACTIVE && p.reviewStatus === REVIEW_STATUS.CHANGES_REQUESTED);
+        if (pullRequests) {
+          const pending = pullRequests.filter(p => p.status === PR_STATUS.ACTIVE && (p.reviewStatus === REVIEW_STATUS.PENDING || p.reviewStatus === REVIEW_STATUS.WAITING));
+          const needsFix = pullRequests.filter(p => p.status === PR_STATUS.ACTIVE && p.reviewStatus === REVIEW_STATUS.CHANGES_REQUESTED);
           console.log(`    PRs: ${pending.length} pending review, ${needsFix.length} need fixes`);
         }
-        if (exists && name === 'workItems') {
-          const items = safeJsonArr(filePath);
-          const queued = items.filter(i => i.status === WI_STATUS.QUEUED);
+        if (workItems) {
+          const queued = workItems.filter(i => i.status === WI_STATUS.QUEUED);
           console.log(`    Items: ${queued.length} queued`);
         }
         if (name === 'specs' || name === 'mergedDesignDocs') {
@@ -1811,19 +1855,17 @@ const commands = {
       return dispatch;
     });
 
-    // Reset work items outside the dispatch lock (work-items.json has its own lock)
+    // Reset work items outside the dispatch transaction.
     for (const item of killed) {
       if (item.meta) {
         e.updateWorkItemStatus(item.meta, WI_STATUS.PENDING, '');
         const itemId = item.meta.item?.id;
         if (itemId) {
-          const wiPath = (item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout')
-            ? path.join(MINIONS_DIR, 'work-items.json')
-            : item.meta.project?.localPath
-              ? shared.projectWorkItemsPath(shared.resolveProjectSource(item.meta.project, config.projects || [], { allowCentral: false }).project || item.meta.project)
-              : null;
-          if (wiPath) {
-            mutateWorkItems(wiPath, items => {
+          const wiScope = (item.meta.source === 'central-work-item' || item.meta.source === 'central-work-item-fanout')
+            ? 'central'
+            : item.meta.project?.name || null;
+          if (wiScope) {
+            mutateWorkItems(wiScope, items => {
               const target = items.find(i => i.id === itemId);
               if (target) {
                 target.status = WI_STATUS.PENDING;
@@ -1840,7 +1882,7 @@ const commands = {
       console.log(`Killed dispatch: ${item.id} (${item.agent}) — work item reset to pending`);
     }
 
-    // Agent status derived from dispatch.json — clearing dispatch.active is sufficient.
+    // Agent status derives from dispatch state — clearing dispatch.active is sufficient.
     console.log('All agents reset to idle (dispatch cleared)');
 
     console.log(`\nDone: ${killed.length} dispatches killed, agents reset.`);
@@ -2103,14 +2145,14 @@ const commands = {
   },
 
   // `minions bridge <subcommand>` — Constellation read-only bridge surface.
-  // Owns the on/off flag and the marker-file projection used by the
+  // Owns the on/off flag and the versioned metadata snapshot used by the
   // Constellation agent. Bridge polling logic itself lives in the
   // Constellation repo (P-wi1-bridge-readonly).
   //
   // Subcommands:
   //   status   Print enabled flag + last-seen Constellation agent timestamp.
-  //   health   Probe http://127.0.0.1:7331/api/status and print the same
-  //            curated projection the Constellation bridge would consume.
+  //   health   Probe the versioned local snapshot endpoint and print the same
+  //            metadata summary the Constellation bridge consumes.
   //   enable   Atomically set engine.constellationBridge.enabled = true.
   //   disable  Atomically set engine.constellationBridge.enabled = false.
   bridge(subcmd, ...rest) {
@@ -2121,7 +2163,7 @@ const commands = {
       console.log(BRIDGE_USAGE);
       console.log('');
       console.log('  status   Show enabled flag + last-seen Constellation agent timestamp');
-      console.log('  health   Probe http://127.0.0.1:7331/api/status and print bridge projection');
+      console.log('  health   Probe the local versioned Constellation snapshot');
       console.log('  enable   Set engine.constellationBridge.enabled = true');
       console.log('  disable  Set engine.constellationBridge.enabled = false');
       return;
@@ -2164,7 +2206,7 @@ const commands = {
     if (subcmd === 'health') {
       const http = require('http');
       const req = http.get(
-        { hostname: '127.0.0.1', port: 7331, path: '/api/status', timeout: 5000 },
+        { hostname: '127.0.0.1', port: 7331, path: '/api/constellation/v1/snapshot', timeout: 5000 },
         (res) => {
           let body = '';
           res.setEncoding('utf8');
@@ -2180,13 +2222,13 @@ const commands = {
               console.error(`error: dashboard response was not JSON: ${e.message}`);
               process.exit(1);
             }
-            const projection = bridge.projectStatusForBridge(parsed);
+            const projection = bridge.projectSnapshotHealthForBridge(parsed);
             if (!projection) {
-              console.error('error: dashboard /api/status returned an unexpected shape');
+              console.error('error: dashboard returned an incompatible Constellation snapshot');
               process.exit(1);
             }
             console.log('bridge: dashboard reachable on http://127.0.0.1:7331');
-            console.log('  projection (same fields the Constellation bridge would read):');
+            console.log('  snapshot (same metadata the Constellation bridge mirrors):');
             for (const [k, v] of Object.entries(projection)) {
               console.log(`    ${k}: ${v === null ? '(unknown)' : v}`);
             }

package/engine/cooldown.js

@@ -3,16 +3,15 @@
  * Extracted from engine.js.
  */
 
-const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
+const smallStateStore = require('./small-state-store');
 
-const { safeJson, safeJsonNoRestore, mutateCooldowns, log, ENGINE_DEFAULTS } = shared;
-const { ENGINE_DIR } = queries;
+const { mutateCooldowns, log, ENGINE_DEFAULTS } = shared;
 
 /**
  * Truncate any string fields on a pendingContexts entry so a single huge PR
- * comment / build log cannot bloat cooldowns.json to hundreds of MB (#1167).
+ * comment / build log cannot bloat cooldown state (#1167).
  * Returns a new entry object (does not mutate the caller's copy).
  */
 function _truncateContextEntry(entry, maxBytes) {
@@ -35,16 +34,11 @@ function _truncateContextEntry(entry, maxBytes) {
   return out;
 }
 
-const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
 const dispatchCooldowns = new Map(); // key → { timestamp, failures }
 let _lastDiskCooldownKeys = new Set();
 
 function loadCooldowns() {
-  // safeJsonNoRestore — cooldowns are time-bounded ephemeral state (24h TTL).
-  // Restoring a stale `cooldowns.json.backup` could resurrect expired entries
-  // that should already have been pruned, suppressing legitimate dispatches
-  // (P-bfa1d-safejson-no-restore). Missing/corrupt primary == "no cooldowns".
-  const saved = safeJsonNoRestore(COOLDOWN_PATH);
+  const saved = smallStateStore.readCooldowns();
   if (!saved) return;
   const now = Date.now();
   for (const [k, v] of Object.entries(saved)) {
@@ -56,12 +50,12 @@ function loadCooldowns() {
     }
   }
   _lastDiskCooldownKeys = new Set(dispatchCooldowns.keys());
-  log('info', `Loaded ${dispatchCooldowns.size} cooldowns from disk`);
+  log('info', `Loaded ${dispatchCooldowns.size} cooldowns from SQL`);
 }
 
 let _cooldownWriteTimer = null;
 /**
- * Persist the in-memory `dispatchCooldowns` Map to disk.
+ * Persist the in-memory `dispatchCooldowns` Map to SQL.
  *
  * Merges the in-memory map ON TOP of the lock-acquired on-disk snapshot
  * rather than replacing it (P-bfa3a → docs/cooldown-merge-semantics.md):
@@ -148,7 +142,7 @@ function saveCooldowns() {
         return merged;
       });
     } catch (err) {
-      log('warn', `saveCooldowns failed writing ${COOLDOWN_PATH}: ${err.message}`);
+      log('warn', `saveCooldowns failed: ${err.message}`);
     }
   }, 1000); // debounce — write at most once per second
 }
@@ -214,10 +208,10 @@ function setCooldownWithContext(key, context) {
   if (context) {
     // Truncate oversized string fields per-entry BEFORE storing so a single
     // huge payload (PR diff, build log, full repo dump) cannot bloat
-    // cooldowns.json regardless of array cap (#1167).
+    // cooldown state regardless of array cap (#1167).
     pendingContexts.push(_truncateContextEntry(context, ENGINE_DEFAULTS.maxPendingContextEntryBytes));
   }
-  // Cap to last N entries to prevent unbounded growth (cooldowns.json bloat)
+  // Cap to the most recent N entries.
   const cap = ENGINE_DEFAULTS.maxPendingContexts;
   if (pendingContexts.length > cap) pendingContexts = pendingContexts.slice(-cap);
   dispatchCooldowns.set(key, {
@@ -290,7 +284,6 @@ function isBranchActive(branch) {
 }
 
 module.exports = {
-  COOLDOWN_PATH,
   dispatchCooldowns,
   loadCooldowns,
   saveCooldowns,

package/engine/db/index.js

@@ -23,25 +23,26 @@ let _dbInitError = null;
 let _exitCheckpointRegistered = false;
 let _cleanedDbPath = null;
 
-function _cleanupRetiredJsonFiles(db, dbPath) {
-  if (_cleanedDbPath === dbPath) return;
-  const marker = db.prepare("SELECT value FROM state_markers WHERE key='sql_only_cutover'").get();
-  if (!marker) return;
-  const minionsDir = path.dirname(path.dirname(dbPath));
+function _retiredJsonTargets(minionsDir) {
   const engineDir = path.join(minionsDir, 'engine');
   const engineFiles = [
-    'dispatch.json', 'log.json', 'metrics.json', 'watches.json',
+    'dispatch.json', 'log.json', 'metrics.json', 'watches.json', 'state.json',
     'schedule-runs.json', 'pipeline-runs.json', 'managed-processes.json',
     'worktree-pool.json', 'qa-runs.json', 'qa-sessions.json', 'pr-links.json',
-    'cooldowns.json', 'pending-rebases.json', 'cc-sessions.json', 'doc-sessions.json',
+    'cooldowns.json', 'pending-rebases.json', 'cc-session.json', 'cc-sessions.json', 'doc-sessions.json',
   ];
   const targets = engineFiles.map(name => path.join(engineDir, name));
-  targets.push(path.join(minionsDir, 'work-items.json'), path.join(minionsDir, 'pull-requests.json'));
+  targets.push(
+    path.join(minionsDir, 'work-items.json'),
+    path.join(minionsDir, 'work-items-archive.json'),
+    path.join(minionsDir, 'pull-requests.json'),
+  );
   try {
     for (const project of fs.readdirSync(path.join(minionsDir, 'projects'), { withFileTypes: true })) {
       if (!project.isDirectory() || project.name === '.archived') continue;
       targets.push(
         path.join(minionsDir, 'projects', project.name, 'work-items.json'),
+        path.join(minionsDir, 'projects', project.name, 'work-items-archive.json'),
         path.join(minionsDir, 'projects', project.name, 'pull-requests.json'),
       );
     }
@@ -53,11 +54,23 @@ function _cleanupRetiredJsonFiles(db, dbPath) {
       }
     } catch { /* PRD directory is optional */ }
   }
+  return targets;
+}
+
+function cleanupRetiredJsonFiles(minionsDir) {
+  const targets = _retiredJsonTargets(minionsDir);
   for (const target of targets) {
     for (const suffix of ['', '.backup', '.lock']) {
       try { fs.unlinkSync(target + suffix); } catch (e) { if (e.code !== 'ENOENT') throw e; }
     }
   }
+}
+
+function _cleanupRetiredJsonFiles(db, dbPath) {
+  if (_cleanedDbPath === dbPath) return;
+  const marker = db.prepare("SELECT value FROM state_markers WHERE key='sql_only_cutover'").get();
+  if (!marker) return;
+  cleanupRetiredJsonFiles(path.dirname(path.dirname(dbPath)));
   _cleanedDbPath = dbPath;
 }
 
@@ -250,4 +263,4 @@ function prepareCached(db, sql) {
   return stmt;
 }
 
-module.exports = { getDb, closeDb, withTransaction, prepareCached };
+module.exports = { getDb, closeDb, withTransaction, prepareCached, cleanupRetiredJsonFiles };

package/engine/db/migrations/009-qa.js

@@ -7,7 +7,7 @@
 //
 // Mirrors the dual-write / content-hash divergence pattern established by
 // the watches and Phase 7 small-state stores. JSON sidecars stay in place as
-// dual-write mirrors for one release cycle (gated by `engine.qaDualWriteJson`).
+// At release time the imported files remained for a temporary compatibility window.
 
 const path = require('path');
 const fs = require('fs');

package/engine/db/migrations/020-qa-session-scopes.js

@@ -0,0 +1,23 @@
+module.exports = {
+  version: 20,
+  description: 'replace QA session work-item paths with SQL scopes',
+  up(db) {
+    const rows = db.prepare('SELECT id, data FROM qa_sessions').all();
+    const update = db.prepare('UPDATE qa_sessions SET data=?, updated_at=? WHERE id=?');
+    const now = Date.now();
+    for (const row of rows) {
+      let session;
+      try { session = JSON.parse(row.data); } catch { continue; }
+      if (!session || typeof session !== 'object' || Array.isArray(session)) continue;
+      const legacyPath = session.primaryWiPath;
+      if (typeof legacyPath === 'string' && legacyPath && !session.primaryScope) {
+        const normalized = legacyPath.replace(/\\/g, '/');
+        const match = normalized.match(/(?:^|\/)projects\/([^/]+)\/work-items\.json$/);
+        session.primaryScope = match ? match[1] : 'central';
+      }
+      if (!Object.prototype.hasOwnProperty.call(session, 'primaryWiPath')) continue;
+      delete session.primaryWiPath;
+      update.run(JSON.stringify(session), now, row.id);
+    }
+  },
+};