@yemi33/minions 0.1.2379 → 0.1.2381

package/engine/live-checkout.js

@@ -110,9 +110,11 @@
  * MOSTLY PURE — does NOT call completeDispatch. It does NOT mutate the tree or
  * write inbox alerts on any default path. The ONE opt-in exception is auto-reset
  * (W-mqvejug6000eeb20): when `liveCheckoutAutoReset` is enabled AND the tree is
- * dirty, it runs `git fetch origin` + `git reset --hard origin/<branch>` and
- * writes a single `live-checkout-autoreset-<wiId>` inbox note. Both the reset
- * git ops and the note writer are injectable (`_git`, `_writeInboxNote`) and the
+ * dirty, it runs `git reset --hard HEAD` + `git clean -fd` and writes a single
+ * `live-checkout-autoreset-<wiId>` inbox note. This preserves the current branch
+ * and committed history while explicitly discarding tracked and untracked WIP.
+ * Both destructive git ops and the note writer are injectable (`_git`,
+ * `_writeInboxNote`) and the
  * decision is injectable (`autoReset` / `_resolveAutoReset`), so unit tests stay
  * filesystem-free. Default (auto-reset off) keeps the helper free of side
  * effects — the dirty/blocked translation belongs in spawnAgent (engine.js).
@@ -568,6 +570,63 @@ async function _maybeAutoFreshenLocalMain(opts = {}) {
   return { freshened: true, before: beforeSha, after: afterSha, behind };
 }
 
+async function _inspectLiveCheckoutHead({ git, baseOpts, localPath, exists }) {
+  let gitDir;
+  try {
+    const gitDirRaw = await git(['rev-parse', '--git-dir'], baseOpts);
+    const gitDirStr = (typeof gitDirRaw === 'string' ? gitDirRaw : '').trim();
+    if (!gitDirStr) throw new Error('git rev-parse --git-dir returned empty output');
+    gitDir = path.isAbsolute(gitDirStr) ? gitDirStr : path.join(localPath, gitDirStr);
+  } catch (e) {
+    throw new Error('prepareLiveCheckout: could not resolve git dir for ' + localPath + ' — ' + (e && e.message));
+  }
+
+  const midOperationSentinels = [
+    { name: 'MERGE_HEAD', op: 'merge' },
+    { name: 'rebase-merge', op: 'rebase' },
+    { name: 'rebase-apply', op: 'rebase' },
+    { name: 'CHERRY_PICK_HEAD', op: 'cherry-pick' },
+    { name: 'REVERT_HEAD', op: 'revert' },
+    { name: 'BISECT_LOG', op: 'bisect' },
+  ];
+  for (const sentinel of midOperationSentinels) {
+    const sentinelPath = path.join(gitDir, sentinel.name);
+    if (exists(sentinelPath)) {
+      return { ok: false, reason: 'mid-operation', op: sentinel.op, details: sentinelPath };
+    }
+  }
+
+  try {
+    await git(['symbolic-ref', '-q', 'HEAD'], baseOpts);
+  } catch (symErr) {
+    if (!symErr || symErr.code !== 1) throw symErr;
+    let sha = '';
+    try {
+      const shaRaw = await git(['rev-parse', 'HEAD'], baseOpts);
+      sha = (typeof shaRaw === 'string' ? shaRaw : '').trim();
+    } catch {
+      // Best-effort diagnostic only.
+    }
+    return { ok: false, reason: 'detached-head', sha };
+  }
+
+  let originalRef = '';
+  let originalRefType = 'branch';
+  try {
+    const refRaw = await git(['symbolic-ref', '--short', 'HEAD'], baseOpts);
+    originalRef = (typeof refRaw === 'string' ? refRaw : '').trim();
+  } catch {
+    originalRefType = 'detached';
+    try {
+      const refRaw = await git(['rev-parse', 'HEAD'], baseOpts);
+      originalRef = (typeof refRaw === 'string' ? refRaw : '').trim();
+    } catch {
+      originalRef = '';
+    }
+  }
+  return { ok: true, originalRef, originalRefType };
+}
+
 async function prepareLiveCheckout(opts = {}) {
   const {
     localPath,
@@ -655,6 +714,19 @@ async function prepareLiveCheckout(opts = {}) {
   //    currently-running git process is never removed out from under it.
   shared.removeStaleIndexLock(localPath, { log: (level, msg) => logFn(msg, level) });
 
+  let originalRef = '';
+  let originalRefType = 'branch';
+  let headInspected = false;
+  const ensureHeadInspected = async () => {
+    if (headInspected) return null;
+    const state = await _inspectLiveCheckoutHead({ git, baseOpts, localPath, exists });
+    if (!state.ok) return state;
+    originalRef = state.originalRef;
+    originalRefType = state.originalRefType;
+    headInspected = true;
+    return null;
+  };
+
   // ── Step 1: git status --porcelain=v1 -b. Bail early on dirty tree. ─────
   // Skipped when `skipDirtyCheck:true` (issue #522): GVFS/VFS-for-Git repos
   // report all un-hydrated virtual files as modified — this is normal GVFS
@@ -726,6 +798,8 @@ async function prepareLiveCheckout(opts = {}) {
       if (dirtyFiles.length > 0) {
         const strayBranch = _extractBranchFromPorcelainHeader(branchInfo);
         if (strayBranch && strayBranch !== branchName && _looksLikeAgentBranch(strayBranch)) {
+          const blocked = await ensureHeadInspected();
+          if (blocked) return blocked;
           const commitRes = await _commitAgentWipWithRetry(
             git, baseOpts,
             `minions: auto-save orphaned WIP from ${strayBranch} (dispatch ${dispatchId || '(unknown)'})`,
@@ -737,8 +811,19 @@ async function prepareLiveCheckout(opts = {}) {
               `, switching back to '${mainRef}'`, 'info');
             try {
               await git(['checkout', mainRef], baseOpts);
+              originalRef = mainRef;
+              originalRefType = 'branch';
             } catch (backErr) {
               logFn(`[live-checkout] could not switch back to '${mainRef}' after self-healing '${strayBranch}': ${backErr && backErr.message}`, 'warn');
+              return {
+                ok: false,
+                reason: 'wrong-base',
+                headBranch: strayBranch,
+                expectedBase: mainRef,
+                switchError: String((backErr && backErr.message) || '').slice(0, 500),
+                originalRef,
+                originalRefType,
+              };
             }
             // Re-run the dirty check. Either the tree is now clean (self-heal
             // succeeded end-to-end) or something new appeared (rare) — either
@@ -751,13 +836,9 @@ async function prepareLiveCheckout(opts = {}) {
         }
       }
       if (dirtyFiles.length > 0) {
-        // W-mqvejug6000eeb20 — opt-in auto-reset. Default behavior is to bail with
-        // reason:'dirty' (spawnAgent translates to non-retryable LIVE_CHECKOUT_DIRTY
-        // and alerts the operator). When auto-reset is enabled — either the caller
-        // passed an explicit `autoReset` boolean, or the config-based resolver says
-        // so — we DISCARD the dirty state via `git fetch origin` + `git reset --hard
-        // origin/<branch>` and continue. This is destructive (the operator’s
-        // uncommitted work is gone), which is why it is strictly opt-in.
+        // W-mqvejug6000eeb20 — opt-in destructive recovery. It may discard
+        // tracked and untracked working-tree changes, but must never repoint the
+        // operator's current branch or discard committed history.
         let wantAutoReset = false;
         if (typeof autoReset === 'boolean') {
           wantAutoReset = autoReset;
@@ -769,176 +850,126 @@ async function prepareLiveCheckout(opts = {}) {
           return { ok: false, reason: 'dirty', dirtyFiles, branchInfo };
         }
 
-        // W-mrav3u0c0008ce38 — live-checkout WI types that never push a branch
-        // (setup/test/verify live-validation dispatches on checkoutMode:'live'
-        // or hybrid liveValidation projects) leave `origin/<branchName>`
-        // unresolvable, so a bare `reset --hard origin/<branchName>` fails every
-        // time with "ambiguous argument … unknown revision" and the tree stays
-        // dirty forever. Probe `origin/<branchName>` first (after the fetch, so
-        // it reflects the latest remote state); only fall back to
-        // `origin/<mainRef>` when that branch genuinely doesn't exist upstream.
-        // PR-continuation flows (fix/implement WIs resuming an existing pushed
-        // branch) keep resetting to `origin/<branchName>` exactly as before.
-        let resetOk = true;
-        let resetTarget = `origin/${branchName}`;
+        const blocked = await ensureHeadInspected();
+        if (blocked) return blocked;
+        const autoResetAttempt = {
+          resetSucceeded: false,
+          cleanAttempted: false,
+          cleanSucceeded: false,
+          recheckSucceeded: false,
+          errors: [],
+        };
         try {
-          await git(['fetch', 'origin'], baseOpts);
-          try {
-            await git(['rev-parse', '--verify', resetTarget], baseOpts);
-          } catch {
-            resetTarget = `origin/${mainRef}`;
-            if (typeof log === 'function') {
-              log(`live-checkout auto-reset: origin/${branchName} does not exist (never pushed) — falling back to '${resetTarget}'`);
-            }
-          }
           if (typeof log === 'function') {
-            log(`live-checkout auto-reset: discarding ${dirtyFiles.length} dirty path(s) on '${branchName}' via fetch + reset --hard ${resetTarget}`);
+            log(`live-checkout auto-reset: discarding ${dirtyFiles.length} dirty path(s) without changing the current branch or HEAD`);
           }
-          await git(['reset', '--hard', resetTarget], baseOpts);
+          await git(['reset', '--hard', 'HEAD'], baseOpts);
+          autoResetAttempt.resetSucceeded = true;
         } catch (e) {
-          resetOk = false;
+          const error = e && e.message ? e.message : String(e);
+          autoResetAttempt.errors.push(`reset --hard HEAD: ${error}`);
           if (typeof log === 'function') {
-            log(`live-checkout auto-reset FAILED (fetch/reset): ${e && e.message ? e.message : e}`);
+            log(`live-checkout auto-reset FAILED (reset --hard HEAD): ${error}`);
           }
         }
-
-        // Re-run the porcelain preflight once. If the tree is now clean we proceed;
-        // otherwise (reset failed, or something is still dirty) we fall back to the
-        // safe dirty refusal so we never dispatch onto an unexpected tree.
-        let stillDirty = dirtyFiles;
-        if (resetOk) {
+        if (autoResetAttempt.resetSucceeded) {
+          autoResetAttempt.cleanAttempted = true;
           try {
-            const recheckRaw = await git(['status', '--porcelain=v1', '-b'], baseOpts);
-            const recheckStr = typeof recheckRaw === 'string' ? recheckRaw : '';
-            stillDirty = recheckStr
-              .split(/\r?\n/)
-              .map((line) => line.replace(/\s+$/, ''))
-              .filter((line) => line.length > 0 && !line.startsWith('## '));
+            await git(['clean', '-fd'], baseOpts);
+            autoResetAttempt.cleanSucceeded = true;
           } catch (e) {
-            resetOk = false;
+            const error = e && e.message ? e.message : String(e);
+            autoResetAttempt.errors.push(`clean -fd: ${error}`);
             if (typeof log === 'function') {
-              log(`live-checkout auto-reset re-check FAILED: ${e && e.message ? e.message : e}`);
+              log(`live-checkout auto-reset FAILED (clean -fd): ${error}`);
             }
           }
         }
 
-        if (!resetOk || stillDirty.length > 0) {
-          return { ok: false, reason: 'dirty', dirtyFiles: stillDirty, branchInfo };
+        // A failed git command may still have changed part of the tree. Always
+        // re-run porcelain after the destructive attempt so both the refusal and
+        // audit note report what actually remains.
+        let stillDirty = dirtyFiles;
+        try {
+          const recheckRaw = await git(['status', '--porcelain=v1', '-b'], baseOpts);
+          const rechecked = parsePorcelain(recheckRaw);
+          stillDirty = rechecked.dirtyFiles;
+          branchInfo = rechecked.branchInfo || branchInfo;
+          autoResetAttempt.recheckSucceeded = true;
+        } catch (e) {
+          const error = e && e.message ? e.message : String(e);
+          autoResetAttempt.errors.push(`status re-check: ${error}`);
+          if (typeof log === 'function') {
+            log(`live-checkout auto-reset re-check FAILED: ${error}`);
+          }
         }
 
-        // Audit trail: record the discarded paths so the operator can recover from
-        // reflog / understand why their tree changed. Best-effort, never throws.
+        const recoveryVerified = autoResetAttempt.recheckSucceeded && stillDirty.length === 0;
+        // Audit every destructive attempt, including partial failures. A git
+        // command can mutate some paths before returning an error.
         try {
           const writeNote = (typeof _writeInboxNote === 'function') ? _writeInboxNote : _defaultWriteInboxNote;
-          const slug = `live-checkout-autoreset-${wiId || dispatchId || 'unknown'}`;
+          const slug = `live-checkout-autoreset-${shared.uid()}-${dispatchId || wiId || 'unknown'}`;
+          autoResetAttempt.auditSlug = slug;
+          const resetOutcome = autoResetAttempt.resetSucceeded ? 'succeeded' : 'FAILED';
+          let cleanOutcome = 'not run because reset failed';
+          if (autoResetAttempt.cleanAttempted) {
+            cleanOutcome = autoResetAttempt.cleanSucceeded ? 'succeeded' : 'FAILED or partially applied';
+          }
+          let verifyOutcome = 'FAILED — remaining tree state is unknown';
+          if (autoResetAttempt.recheckSucceeded) {
+            verifyOutcome = stillDirty.length === 0 ? 'clean' : `${stillDirty.length} dirty path(s) remain`;
+          }
           const body = [
-            `# Live-checkout auto-reset on '${branchName}'`,
+            `# Live-checkout auto-reset ${recoveryVerified ? 'completed' : 'incomplete'} before '${branchName}'`,
+            '',
+            `The live-checkout tree at \`${localPath}\` was dirty and \`liveCheckoutAutoReset\``,
+            'attempted destructive WIP cleanup. The current branch and committed history were preserved.',
+            '',
+            '## Outcome',
             '',
-            `⚠️ The live-checkout tree at \`${localPath}\` was dirty at dispatch time and`,
-            '`liveCheckoutAutoReset` is enabled, so it was force-reset to',
-            `\`${resetTarget}\`. **The following uncommitted changes were DISCARDED**`,
-            '(recover from `git reflog` / `git fsck --lost-found` if needed):',
+            `- \`git reset --hard HEAD\`: ${resetOutcome}`,
+            `- \`git clean -fd\`: ${cleanOutcome}`,
+            `- post-cleanup status check: ${verifyOutcome}`,
+            ...(autoResetAttempt.errors.length > 0
+              ? ['', 'Errors:', ...autoResetAttempt.errors.map(error => `- ${error}`)]
+              : []),
+            '',
+            '## Changes present before the attempt',
             '',
             '```',
             ...dirtyFiles,
             '```',
+            ...(autoResetAttempt.recheckSucceeded
+              ? [
+                '',
+                '## Changes remaining after the attempt',
+                '',
+                '```',
+                ...(stillDirty.length > 0 ? stillDirty : ['(clean)']),
+                '```',
+              ]
+              : []),
           ].join('\n');
           writeNote(slug, body);
         } catch { /* best-effort audit note */ }
+
+        if (!recoveryVerified) {
+          return {
+            ok: false,
+            reason: 'dirty',
+            dirtyFiles: stillDirty,
+            branchInfo,
+            autoResetAttempt,
+          };
+        }
         // Fall through — tree is now clean, continue with normal preparation.
       }
     }
   }
 
-  // ── Step 2: mid-operation / detached-HEAD preflight (P-b2e8d4a6). ──────
-  // Runs AFTER the dirty bail and BEFORE branch resolution — never mutates.
-  // Resolve the git dir via rev-parse (NOT localPath/.git) so submodule /
-  // gitdir-file / repo-managed trees resolve correctly. A FAILURE here is a
-  // real git-health problem (and on the very submodule / gitdir-file /
-  // repo-managed trees live mode targets, <localPath>/.git is NOT a directory,
-  // so the old fabricated-path fallback made every sentinel probe miss and
-  // silently skipped mid-operation detection). Throw so the caller classifies
-  // it as a retryable LIVE_CHECKOUT_FAILED instead of barging into a branch
-  // switch on top of a half-finished operation we couldn't see.
-  let gitDir;
-  try {
-    const gitDirRaw = await git(['rev-parse', '--git-dir'], baseOpts);
-    const gitDirStr = (typeof gitDirRaw === 'string' ? gitDirRaw : '').trim();
-    if (!gitDirStr) {
-      throw new Error('git rev-parse --git-dir returned empty output');
-    }
-    gitDir = path.isAbsolute(gitDirStr) ? gitDirStr : path.join(localPath, gitDirStr);
-  } catch (e) {
-    throw new Error('prepareLiveCheckout: could not resolve git dir for ' + localPath + ' — ' + (e && e.message));
-  }
-
-  // Probe sentinel paths under the resolved git dir. First hit wins; map each
-  // to its in-progress operation. rebase-merge/ (interactive/merge rebase) and
-  // rebase-apply/ (am-based rebase) both mean a rebase is underway. BISECT_LOG
-  // covers an in-progress `git bisect` (bisect state is HEAD-keyed, so a branch
-  // switch would silently destroy it — the doc + header imply bisect coverage).
-  const MID_OP_SENTINELS = [
-    { name: 'MERGE_HEAD', op: 'merge' },
-    { name: 'rebase-merge', op: 'rebase' },
-    { name: 'rebase-apply', op: 'rebase' },
-    { name: 'CHERRY_PICK_HEAD', op: 'cherry-pick' },
-    { name: 'REVERT_HEAD', op: 'revert' },
-    { name: 'BISECT_LOG', op: 'bisect' },
-  ];
-  for (const sentinel of MID_OP_SENTINELS) {
-    const sentinelPath = path.join(gitDir, sentinel.name);
-    if (exists(sentinelPath)) {
-      return { ok: false, reason: 'mid-operation', op: sentinel.op, details: sentinelPath };
-    }
-  }
-
-  // Detached HEAD: `git symbolic-ref -q HEAD` exits 1 when HEAD does not point
-  // at a branch. Branching off a detached HEAD would strand the operator's
-  // anonymous commits, so refuse. But distinguish a REAL detachment (git ran
-  // and returned exit code 1) from a TRANSIENT failure (spawn error / timeout /
-  // ENOENT) — the latter is not proof of detachment and must NOT permanently
-  // refuse an on-a-branch tree; rethrow so it becomes a retryable
-  // LIVE_CHECKOUT_FAILED instead.
-  let detached = false;
-  try {
-    await git(['symbolic-ref', '-q', 'HEAD'], baseOpts);
-  } catch (symErr) {
-    if (symErr && symErr.code === 1) {
-      detached = true; // git ran, HEAD is not a symbolic ref → genuinely detached
-    } else {
-      throw symErr; // spawn failure / timeout / other → transient, not detachment
-    }
-  }
-  if (detached) {
-    let sha = '';
-    try {
-      const shaRaw = await git(['rev-parse', 'HEAD'], baseOpts);
-      sha = (typeof shaRaw === 'string' ? shaRaw : '').trim();
-    } catch {
-      // best-effort sha; leave empty if even rev-parse fails
-    }
-    return { ok: false, reason: 'detached-head', sha };
-  }
-
-  // ── Step 3: original-ref capture (P-b2e8d4a6). ────────────────────────
-  // Capture the operator's starting ref BEFORE any checkout so the
-  // dispatch-end auto-restore can put the tree back. Prefer the symbolic
-  // branch name; fall back to the raw HEAD sha when symbolic-ref fails.
-  let originalRef = '';
-  let originalRefType = 'branch';
-  try {
-    const refRaw = await git(['symbolic-ref', '--short', 'HEAD'], baseOpts);
-    originalRef = (typeof refRaw === 'string' ? refRaw : '').trim();
-    originalRefType = 'branch';
-  } catch {
-    originalRefType = 'detached';
-    try {
-      const refRaw = await git(['rev-parse', 'HEAD'], baseOpts);
-      originalRef = (typeof refRaw === 'string' ? refRaw : '').trim();
-    } catch {
-      originalRef = '';
-    }
-  }
+  const blocked = await ensureHeadInspected();
+  if (blocked) return blocked;
 
   // ── Step 4: branch resolution + checkout. ─────────────────────────────
   // NO `git fetch` (issue #226): the operator's existing HEAD is the
@@ -1195,6 +1226,7 @@ async function prepareLiveCheckout(opts = {}) {
       }
       logFn('info',
         `live-checkout: HEAD was on '${headBranch}' (not base '${mainRef}') — switched to local '${mainRef}' before forking '${branchName}' (no fetch, issue #226 preserved)`);
+      curBranch = mainRef;
       // ── originalRef correction (W-mrb6an8300058fd8). ─────────────────────
       // originalRef/originalRefType were captured at Step 3 from the STALE
       // headBranch, BEFORE this self-heal ran. The tree has now been switched
@@ -1883,6 +1915,8 @@ async function performLiveCheckoutAutoStash(opts = {}) {
  *     or — W-mrawgw4q000a6bff — to an explicit `liveCheckoutAutoReset` fallback
  *     when that policy also resolves true; see engine.js spawnAgent).
  *   - `{ outcome:'stashed', liveResult }`   — stashed + re-preflighted; proceed.
+ *   - `{ outcome:'blocked', liveResult }`     — mutation preflight found an
+ *     in-progress repository operation or detached HEAD; caller must refuse.
  *   - `{ outcome:'threw', error }`           — the re-preflight threw; caller must
  *     fail the dispatch as LIVE_CHECKOUT_FAILED (engine-specific completion).
  *
@@ -1903,7 +1937,7 @@ async function performLiveCheckoutAutoStash(opts = {}) {
  * tree if the ff fails — so it was deliberately left out.
  *
  * @param {object} opts
- * @returns {Promise<{outcome:'unchanged'|'stashed'|'threw', liveResult?:object, error?:Error}>}
+ * @returns {Promise<{outcome:'unchanged'|'blocked'|'stashed'|'threw', liveResult?:object, error?:Error}>}
  */
 async function applyLiveCheckoutAutoStash(opts = {}) {
   const {
@@ -1911,12 +1945,22 @@ async function applyLiveCheckoutAutoStash(opts = {}) {
     gitOpts, dispatchId, wiId, log,
     clearDirtyStamp, writeStashNote,
     _git, // private injection for testing — forwarded to performLiveCheckoutAutoStash + the re-preflight prepareLiveCheckout call
+    _exists,
   } = opts;
   const logFn = (typeof log === 'function') ? log : () => {};
   const reason = (liveResult && liveResult.ok === false) ? liveResult.reason : null;
   if (reason !== 'dirty' || !resolveLiveCheckoutAutoStash({ project, engine })) {
     return { outcome: 'unchanged', liveResult };
   }
+  try {
+    const git = (typeof _git === 'function') ? _git : shared.shellSafeGit;
+    const exists = (typeof _exists === 'function') ? _exists : fs.existsSync;
+    const baseOpts = { cwd: localPath, maxBuffer: LIVE_CHECKOUT_GIT_MAX_BUFFER, ...(gitOpts || {}) };
+    const state = await _inspectLiveCheckoutHead({ git, baseOpts, localPath, exists });
+    if (!state.ok) return { outcome: 'blocked', liveResult: state };
+  } catch (preflightErr) {
+    return { outcome: 'threw', error: preflightErr };
+  }
   let stashResult;
   try {
     stashResult = await performLiveCheckoutAutoStash({ localPath, dispatchId, gitOpts, log, _git });

package/engine/llm.js

@@ -33,7 +33,7 @@ const EXIT_DRAIN_FALLBACK_MS = 100;
 //
 // Updates accumulate in an in-memory buffer and flush every
 // metricsFlushIntervalMs (default 10s). Replaces the per-call mutateJsonFileLocked
-// that was both serializing the LLM hot path and bumping metrics.json mtime
+// that was serializing the LLM hot path
 // on every call — defeating the dashboard fast-state mtime-based early-exit.
 
 let _pendingMetrics = { engine: Object.create(null), daily: Object.create(null) };

package/engine/logs-store.js

@@ -1,4 +1,4 @@
-// engine/logs-store.js — SQL-backed implementation of engine/log.json.
+// engine/logs-store.js — SQL-backed engine logs.
 //
 // Logs differ from work_items / pull_requests / dispatches: they are
 // pure append-only with a tail-cap, so the store exposes a different
@@ -168,7 +168,7 @@ function readRecentLogs(n, opts) {
   return out;
 }
 
-// Convenience: same shape as the legacy `JSON.parse(log.json).slice(-N)`
+// Convenience: return the latest N entries in chronological order.
 // — chronological order (oldest first). Inverts the readRecentLogs DESC
 // output so existing callers can drop in without re-sorting.
 function readRecentLogsChronological(n, opts) {

package/engine/managed-spawn.js

@@ -28,7 +28,6 @@ const queries = require('./queries');
 const { log, ENGINE_DEFAULTS } = shared;
 
 const MANAGED_SPAWN_FILENAME = 'managed-spawn.json';
-const MANAGED_PROCESSES_STATE_FILE = 'managed-processes.json';
 const MANAGED_LOGS_DIR = 'managed-logs';
 const INVALID_WORKDIR_REASON_PREFIX = 'invalid-workdir: ';
 
@@ -760,7 +759,7 @@ function buildManagedSpawnHint(opts) {
 //                                    spawnDashboard detached-spawn pattern.
 //                                    Returns {pid, started_at, log_path}.
 //   3. recordManagedSpec(spec,     → writes one entry to
-//      runtime, ctx)                 engine/managed-processes.json via
+//      runtime, ctx)                 SQL managed-process state via
 //                                    mutateJsonFileLocked. Replaces any
 //                                    existing entry with the same name
 //                                    (idempotent under retry).
@@ -777,16 +776,6 @@ function buildManagedSpawnHint(opts) {
 //                                    (playbook injection) + items 3/7
 //                                    (sweep + boot reconcile).
 //
-// All state writes go through mutateJsonFileLocked per the repo convention
-// ('Key conventions' in copilot-instructions.md). Callbacks stay synchronous
-// and fast — no kill / no spawn inside the lock callback. Healthcheck loops,
-// dispatch ERROR gating on healthcheck failure, per-tick sweep, boot
-// reconcile, and dashboard endpoints are deferred to items 3/4/5/7.
-
-function _getStatePath() {
-  return path.join(shared.MINIONS_DIR, 'engine', MANAGED_PROCESSES_STATE_FILE);
-}
-
 function _getLogsDir() {
   return path.join(shared.MINIONS_DIR, 'engine', MANAGED_LOGS_DIR);
 }
@@ -906,7 +895,6 @@ function _toStateRecord(spec, runtime, ctx) {
 
 function recordManagedSpec(spec, runtime, ctx) {
   if (!spec || !spec.name) throw new Error('recordManagedSpec: spec.name required');
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
       data = _initialStateShape();
@@ -921,7 +909,6 @@ function recordManagedSpec(spec, runtime, ctx) {
 
 function recordManagedBatch(items, ctx) {
   if (!Array.isArray(items) || items.length === 0) return;
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
       data = _initialStateShape();
@@ -942,7 +929,6 @@ function recordManagedBatch(items, ctx) {
 function removeManagedSpec(name) {
   if (typeof name !== 'string' || name.length === 0) return;
   let killPid = null;
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const idx = data.specs.findIndex(s => s && s.name === name);
@@ -968,8 +954,7 @@ function removeManagedSpec(name) {
 
 function listManagedSpecs(opts) {
   opts = opts || {};
-  const statePath = _getStatePath();
-  const parsed = shared.safeJsonObj(statePath);
+  const parsed = require('./small-state-store').readManagedProcesses();
   const specs = (parsed && Array.isArray(parsed.specs)) ? parsed.specs : [];
   if (opts.project) return specs.filter(s => s && s.owner_project === opts.project);
   return specs.slice();
@@ -1090,7 +1075,6 @@ async function runHealthcheck(spec) {
 // waitForFirstHealth on the first pass. Callers MUST be outside any other
 // lock — this acquires its own.
 function _markHealthy(name, now) {
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const rec = data.specs.find(s => s && s.name === name);
@@ -1404,7 +1388,6 @@ function _runManagedReconcile(opts) {
     rotatedLogs: 0,
     malformed: 0,
   };
-  const statePath = _getStatePath();
   const ttlPidsToKill = [];
   const survivors = []; // [{name, log_path}] post-mutation, used for log rotation + bootReconcile probes
   shared.mutateManagedProcesses((data) => {
@@ -1459,7 +1442,6 @@ function sweepManagedSpawn(opts) {
 // rely on the per-spec loop to refresh post-success, or item 7 boot reconcile
 // to (re)establish initial truth on engine restart).
 function _markBootProbe(name, result) {
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const rec = data.specs.find(s => s && s.name === name);
@@ -1510,7 +1492,6 @@ function removeManagedSpecsForProject(projectName) {
   if (typeof projectName !== 'string' || projectName.length === 0) {
     return { killed: 0, unlinked: 0, scanned: 0 };
   }
-  const statePath = _getStatePath();
   let toKill = [];
   let logPaths = [];
   shared.mutateManagedProcesses((data) => {
@@ -1546,7 +1527,6 @@ function removeManagedSpecsForProject(projectName) {
 
 module.exports = {
   MANAGED_SPAWN_FILENAME: MANAGED_SPAWN_FILENAME,
-  MANAGED_PROCESSES_STATE_FILE: MANAGED_PROCESSES_STATE_FILE,
   MANAGED_LOGS_DIR: MANAGED_LOGS_DIR,
   INVALID_WORKDIR_REASON_PREFIX: INVALID_WORKDIR_REASON_PREFIX,
   HEALTHCHECK_TYPES: HEALTHCHECK_TYPES,
@@ -1561,7 +1541,6 @@ module.exports = {
   recordManagedBatch: recordManagedBatch,
   removeManagedSpec: removeManagedSpec,
   listManagedSpecs: listManagedSpecs,
-  getStatePath: _getStatePath,
   // Item 3 (P-9c1f47a6): healthcheck implementations + first-pass waiter.
   runHealthcheck: runHealthcheck,
   waitForFirstHealth: waitForFirstHealth,

package/engine/meeting.js

@@ -10,6 +10,7 @@ const { safeJson, uid, log, ts, ENGINE_DEFAULTS, WORK_TYPE, DISPATCH_RESULT, MEE
 const queries = require('./queries');
 const { getDispatch, getConfig } = queries;
 const { renderPlaybook } = require('./playbook');
+const dispatchModule = require('./dispatch');
 
 /** Patterns that indicate an agent returned no meaningful output */
 const EMPTY_OUTPUT_PATTERNS = ['(no output)', '(no findings)', '(no response)'];
@@ -514,7 +515,7 @@ function discoverMeetingWork(config) {
 
     // Pre-flight validation: meetings missing required template vars (agenda)
     // would otherwise fail playbook rendering on every tick (~1/min), spamming
-    // log.json with the same "missing required template variables: agenda"
+    // the engine log with the same "missing required template variables: agenda"
     // error. Skip them silently here; emit one structured warning per meeting
     // ID per process so the operator still has signal without the spam.
     if (!meeting.agenda || !String(meeting.agenda).trim()) {
@@ -757,12 +758,11 @@ function addMeetingNote(meetingId, note) {
 
 function _killMeetingDispatches(meetingId) {
   try {
-    const DISPATCH_PATH = path.join(shared.MINIONS_DIR, 'engine', 'dispatch.json');
     const tmpDir = path.join(shared.MINIONS_DIR, 'engine', 'tmp');
     const entriesToStop = [];
     const filesToDelete = [];
     const dispatchDirsToRemove = [];
-    shared.mutateJsonFileLocked(DISPATCH_PATH, (dp) => {
+    dispatchModule.mutateDispatch((dp) => {
       dp.pending = Array.isArray(dp.pending) ? dp.pending : [];
       dp.active = Array.isArray(dp.active) ? dp.active : [];
       dp.completed = Array.isArray(dp.completed) ? dp.completed : [];
@@ -828,7 +828,7 @@ function advanceMeetingRound(meetingId) {
   if (!existing || existing.status === MEETING_STATUS.COMPLETED || existing.status === MEETING_STATUS.ARCHIVED) return null;
 
   // CRITICAL: kill BEFORE acquiring the meeting lock. _killMeetingDispatches
-  // takes the dispatch.json lock and shells out to kill processes — never
+  // mutates dispatch state and shells out to kill processes — never
   // run that under the meeting lock (per CLAUDE.md, lock callbacks must
   // stay fast and never spawn / kill / await).
   _killMeetingDispatches(meetingId);
@@ -923,13 +923,13 @@ function checkMeetingTimeouts(config) {
     // BUG-H11: when a hard timeout will fire, kill in-flight meeting
     // dispatches BEFORE entering the meeting lock so they stop consuming
     // worker slots / LLM tokens immediately rather than draining over the
-    // next tens of minutes. _killMeetingDispatches takes the dispatch.json
+    // next tens of minutes. _killMeetingDispatches takes the dispatch
     // lock and shells out to kill processes — per CLAUDE.md and the
     // advanceMeetingRound/endMeeting/deleteMeeting pattern at L834, that
     // MUST run outside the meeting lock. We pre-evaluate eligibility from
     // the snapshot using the same predicate the mutate callback below
     // re-checks under lock; if the timeout has already advanced/cleared,
-    // the kill is a no-op on dispatch.json (no matching meetingId entries).
+    // the kill is a no-op in dispatch state (no matching meetingId entries).
     const snapshotRoundName = snapshot.status === 'investigating'
       ? 'investigate'
       : snapshot.status === 'debating'