@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{timeout.js → orchestration/timeout.js}

@@ -1,5 +1,5 @@
 /**
- * engine/timeout.js — Runtime timeout, stale-orphan cleanup, steering, and idle checks.
+ * engine/orchestration/timeout.js — Runtime timeout, stale-orphan cleanup, steering, and idle checks.
  *
  * Live-checkout dispatches (project.checkoutMode === 'live') are killed by PID
  * exactly like isolated-mode dispatches — no special handling, no in-place
@@ -9,9 +9,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const queries = require('./queries');
-const steering = require('./steering');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
+const steering = require('../agents/steering');
 
 const { safeRead, safeWrite, safeJson, mutateWorkItems, getProjects, log, ts,
   ENGINE_DEFAULTS, ENGINE_DIR, WI_STATUS, WORK_TYPE, DISPATCH_RESULT, AGENT_STATUS, FAILURE_CLASS } = shared;
@@ -22,7 +22,7 @@ const MINIONS_DIR = shared.MINIONS_DIR;
 // Lazy require to break circular dependency with engine.js
 // Only needed for engine().activeProcesses and engine().engineRestartGraceUntil — log/ts come from shared.js
 let _engine = null;
-function engine() { if (!_engine) _engine = require('../engine'); return _engine; }
+function engine() { if (!_engine) _engine = require('../../engine'); return _engine; }
 
 function resolveDispatchBranchPath(item, config) {
   if (item?.worktreePath) return item.worktreePath;
@@ -57,7 +57,7 @@ function resolveDispatchProject(item, config) {
 
 function getWorktreeProcessAnchorReason(item, managedSpawnSpawnedCount = 0) {
   if (!item?.worktreePath) return null;
-  const decision = require('./worktree-gc').shouldGcDispatchWorktree({
+  const decision = require('../worktrees/gc').shouldGcDispatchWorktree({
     worktreePath: item.worktreePath,
     agentId: item.agent,
     managedSpawnSpawnedCount,
@@ -74,7 +74,7 @@ function gcRecoveredDispatchWorktree(item, project, config) {
     project.localPath,
     config.engine?.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot,
   );
-  require('./worktree-gc').gcDispatchWorktreeIfOrphan({
+  require('../worktrees/gc').gcDispatchWorktreeIfOrphan({
     worktreePath: item.worktreePath,
     gitRoot: project.localPath,
     worktreeRoot,
@@ -87,15 +87,28 @@ function gcRecoveredDispatchWorktree(item, project, config) {
 async function _finalizeDeadDispatch(item, reason, failureClass, config, deps = {}) {
   const preserveBranch = deps.preserveBranch || preserveDispatchBranch;
   const restoreLiveCheckout = deps.restoreLiveCheckout ||
-    require('./live-checkout').maybeRestoreLiveCheckoutFromRecord;
+    require('../worktrees/live-checkout').maybeRestoreLiveCheckoutFromRecord;
   const complete = deps.complete || dispatch().completeDispatch;
+  // W-ms9tcs3o01y03383 — optional observability label describing HOW this
+  // dispatch reached its terminal state (shared.DISPATCH_COMPLETION_PATH).
+  const completionPath = deps.completionPath || null;
   const deferredTerminal = item?._worktreeProtectionDeferred?.terminal || {};
   const terminalReason = deferredTerminal.reason || reason;
   const terminalResultSummary = deferredTerminal.resultSummary || '';
-  const terminalCompleteOpts = deferredTerminal.completeOpts
+  const terminalBaseCompleteOpts = deferredTerminal.completeOpts
     && typeof deferredTerminal.completeOpts === 'object'
     ? deferredTerminal.completeOpts
-    : (failureClass ? { failureClass } : {});
+    : (failureClass
+      ? {
+        failureClass,
+        ...(failureClass === FAILURE_CLASS.ENGINE_RESTART
+          ? { retryBudget: 'infrastructure', countAgentRetryFailure: false }
+          : {}),
+      }
+      : {});
+  const terminalCompleteOpts = completionPath
+    ? { ...terminalBaseCompleteOpts, completionPath }
+    : terminalBaseCompleteOpts;
 
   if (resolveDispatchBranchPath(item, config) && item.meta?.branch) {
     try {
@@ -203,7 +216,7 @@ const STEERING_KILL_INTERVALS_MS = [30000, 60000, 120000];
 // have already terminated (delivered/dropped/etc).
 const STEERING_ACTIVE_STATUSES = new Set(['queued', 'live_kill', 'deferred', 're_spawning']);
 
-// W-mq066js7000fff1f-c (Gap G): lazy require for engine/steering-store.js.
+// W-mq066js7000fff1f-c (Gap G): lazy require for engine/persistence/steering-store.js.
 // Sibling branch -d ships the store; my branch ships independently and no-ops
 // when the module is absent. Only swallows MODULE_NOT_FOUND for the exact
 // resolution — real syntax/runtime errors propagate so a broken store fails
@@ -214,11 +227,11 @@ function getSteeringStore() {
   if (_steeringStoreLoaded) return _steeringStore;
   _steeringStoreLoaded = true;
   try {
-    _steeringStore = require('./steering-store');
+    _steeringStore = require('../persistence/steering-store');
   } catch (err) {
     const isMissing = err && err.code === 'MODULE_NOT_FOUND' && /steering-store/.test(String(err.message || ''));
     if (!isMissing) {
-      try { log('warn', `Steering: failed to load engine/steering-store.js: ${err.message}`); } catch {}
+      try { log('warn', `Steering: failed to load engine/persistence/steering-store.js: ${err.message}`); } catch {}
     }
     _steeringStore = null;
   }
@@ -281,7 +294,7 @@ function runtimeSupportsMidRunSessionId(info) {
   if (typeof info?.runtime?.capabilities?.midRunSessionId === 'boolean') return info.runtime.capabilities.midRunSessionId;
   if (info?.runtimeName) {
     try {
-      const { resolveRuntime } = require('./runtimes');
+      const { resolveRuntime } = require('../runtimes');
       const runtime = resolveRuntime(info.runtimeName);
       if (typeof runtime.capabilities?.midRunSessionId === 'boolean') return runtime.capabilities.midRunSessionId;
     } catch {
@@ -316,7 +329,7 @@ function deferSteeringUntilCheckpoint(id, info, steerEntry) {
   // once the resumed turn produces output evidence.
   if (steerEntry?.steerId) {
     try {
-      const store = require('./steering-store');
+      const store = require('../persistence/steering-store');
       store.updateStatus(steerEntry.steerId, 'deferred', { dispatchId: id, runtime: info?.runtimeName || null });
     } catch { /* best-effort */ }
   }
@@ -369,29 +382,46 @@ function checkDeferredStranded(activeProcesses, config) {
   }
 }
 
-// P-6e2a4c15 — cancel-vs-kill for pooled dispatches. A pooled dispatch's
-// `activeProcesses` record (`info`) carries `_pooled: true` (stamped by
-// engine.js#spawnAgent, P-1d8f0b93) and its `.proc` is a PooledAgentProcess
-// facade whose `.pid` is the SHARED, long-lived ACP worker's real OS pid —
-// not a per-dispatch child process. Every OS-level kill helper in this file
-// (`shared.killGracefully`, `shared.killImmediate`, `_escalatePlatformKill`)
-// ultimately runs `taskkill /F /T /PID <pid>` or SIGKILLs that pid's whole
-// process tree. Doing that to a pooled dispatch would kill the shared worker
-// out from under every OTHER dispatch waiting to reuse it from the pool —
-// exactly the collateral-damage risk `PooledAgentProcess#kill()` (P-1d8f0b93)
-// was built to avoid: it cancels the in-flight ACP turn and releases the
-// worker back to the pool without touching the OS process. Route every kill
-// request here through this helper so no call site can accidentally bypass
-// that primitive for a pooled record.
-function killTrackedProcess(info, { graceMs } = {}) {
-  if (!info || !info.proc) return;
+// A pooled dispatch PID belongs to its shared ACP worker. Its registered
+// gateway site cancels the facade; cold sites verify the tracked PID identity.
+function killTrackedProcess(info, { graceMs, processes } = {}) {
+  if (!info || !info.proc) return false;
   if (info._pooled && typeof info.proc.kill === 'function') {
-    try { info.proc.kill(); }
+    try { return shared.terminateProcess('engine.timeout.tracked-pooled', info.proc); }
     catch (err) { try { log('warn', `Pooled dispatch cancel failed for ${info.agentId || '?'}: ${err.message}`); } catch {} }
-    return;
+    return false;
+  }
+  const ownership = {
+    recordedAtMs: info.runtimePidObservedAt,
+    tracked: true,
+    ...(Array.isArray(processes) ? { processes } : {}),
+  };
+  if (graceMs == null) {
+    return shared.terminateProcess('engine.timeout.tracked-cold', info.proc, ownership);
   }
-  if (graceMs == null) shared.killImmediate(info.proc);
-  else shared.killGracefully(info.proc, graceMs);
+  return shared.terminateProcess('engine.timeout.tracked-cold-graceful', info.proc, {
+    ...ownership,
+    graceMs,
+  });
+}
+
+function cancelTrackedProcessesWithoutDispatch(activeProcesses, activeDispatchItems, opts = {}) {
+  const activeIds = new Set((activeDispatchItems || []).map(item => item?.id).filter(Boolean));
+  let cancelled = 0;
+  let processSnapshot = Array.isArray(opts.processes) ? opts.processes : null;
+  for (const [id, info] of activeProcesses.entries()) {
+    if (activeIds.has(id)) continue;
+    if (!info?._pooled && !processSnapshot) processSnapshot = shared.listAllProcesses();
+    const stopped = killTrackedProcess(info, { processes: processSnapshot });
+    if (stopped) {
+      log('warn', `Cancelling tracked process ${id} after its dispatch record was removed`);
+      cancelled++;
+    } else if (!info?._pooled) {
+      log('warn', `Dropping unowned tracked process ${id} without killing its PID`);
+    }
+    activeProcesses.delete(id);
+  }
+  return cancelled;
 }
 
 // W-mq066js7000fff1f-c (Gap C): runs the kill-retry escalation ladder for an
@@ -451,49 +481,16 @@ function _escalatePlatformKill(info) {
   // ACP turn and release the worker instead of taskkill/SIGKILLing the
   // shared worker process. See killTrackedProcess's comment above.
   if (info?._pooled && info.proc && typeof info.proc.kill === 'function') {
-    try { info.proc.kill(); } catch { /* best-effort */ }
-    return;
-  }
-  const pid = info?.proc?.pid;
-  if (!pid) return;
-  if (process.platform === 'win32') {
-    try { shared.exec(`taskkill /F /T /PID ${pid}`, { timeout: 3000 }); }
-    catch { /* may already be dead */ }
+    try { shared.terminateProcess('engine.timeout.tracked-pooled', info.proc); } catch { /* best-effort */ }
     return;
   }
-  // Unix: collect descendant PIDs (deepest first), SIGKILL each, then a final
-  // `pkill -KILL -P <pid>` sweep for anything pgrep missed.
-  const descendants = _collectDescendantPids(pid);
-  for (const child of descendants) {
-    try { process.kill(child, 'SIGKILL'); } catch { /* gone */ }
-  }
-  try { shared.exec(`pkill -KILL -P ${pid}`, { timeout: 3000 }); }
-  catch { /* children may already be dead */ }
-  try { process.kill(pid, 'SIGKILL'); } catch { /* parent may already be dead */ }
-}
-
-function _collectDescendantPids(rootPid) {
-  // Returns descendant PIDs ordered deepest-first so leaves die before parents
-  // (otherwise grandchildren get re-parented to init and disappear from pgrep -P
-  // <pid>). BFS the tree, then reverse.
-  const visited = new Set();
-  const queue = [rootPid];
-  const order = [];
-  while (queue.length) {
-    const current = queue.shift();
-    if (visited.has(current)) continue;
-    visited.add(current);
-    let out = '';
-    try { out = String(shared.exec(`pgrep -P ${current}`, { timeout: 2000 }) || ''); }
-    catch { /* no children or pgrep missing */ continue; }
-    const children = out.split(/\s+/).map(s => Number(s)).filter(n => Number.isFinite(n) && n > 0);
-    for (const child of children) {
-      if (visited.has(child)) continue;
-      order.push(child);
-      queue.push(child);
-    }
-  }
-  return order.reverse();
+  if (!info?.proc?.pid) return;
+  try {
+    shared.terminateProcess('engine.timeout.tracked-cold-escalation', info.proc, {
+      recordedAtMs: info.runtimePidObservedAt,
+      tracked: true,
+    });
+  } catch { /* may already be dead */ }
 }
 
 function checkSteering(config) {
@@ -604,7 +601,7 @@ function checkSteering(config) {
     // process to deliver this message via session resume. Best-effort.
     if (steerEntry?.steerId) {
       try {
-        const store = require('./steering-store');
+        const store = require('../persistence/steering-store');
         store.updateStatus(steerEntry.steerId, 'live_kill', { dispatchId: id, runtime: info?.runtimeName || null });
       } catch { /* best-effort */ }
     }
@@ -657,7 +654,7 @@ function trackedProcessPid(procInfo) {
   return Number.isFinite(pid) && pid > 0 ? pid : null;
 }
 
-function isTrackedProcessAlive(procInfo) {
+function isTrackedProcessAlive(procInfo, opts = {}) {
   if (!procInfo) return false;
   const proc = procInfo.proc;
   if (proc && Object.prototype.hasOwnProperty.call(proc, 'exitCode') && proc.exitCode !== null) {
@@ -666,12 +663,9 @@ function isTrackedProcessAlive(procInfo) {
 
   const pid = trackedProcessPid(procInfo);
   if (!pid) return !!proc && proc.killed !== true;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
+  // W-ms6dmv99005o26f4 — EPERM means the kernel FOUND the process and refused the
+  // signal; only ESRCH proves absence. See process-utils#inspectPidLiveness.
+  return shared.inspectPidLiveness(pid, opts).alive;
 }
 
 // Read the on-disk PID for a dispatch ID, or null if missing/invalid. Shared by
@@ -689,16 +683,43 @@ function _readDispatchPid(itemId) {
   return Number.isFinite(pid) && pid > 0 ? pid : null;
 }
 
+// W-ms6dmv99005o26f4 — decide whether an ALIVE OS PID may be demoted to "dead"
+// because its command line does not look like an agent runtime.
+//
+// The recycled-PID cross-check this backs is real and must stay (Windows reuses
+// PIDs aggressively, and a coincidentally-alive unrelated process would otherwise
+// park the dispatch as `active` forever). But `isProcessCommandLineMatchingAgent`
+// returns a bare `false` for BOTH "I read the command line and it isn't an agent"
+// and "I could not read the command line at all". Collapsing those made a probe
+// outage — PowerShell Get-CimInstance timing out under fleet load, a `/proc` read
+// racing teardown, `ps` failing to spawn — read as proof of death for every silent
+// dispatch simultaneously. That is the second link of the 2026-07-29T17:44Z
+// false-orphan storm, and unlike the restart link it needs no engine restart to
+// fire.
+//
+// Only a CONCLUSIVE mismatch demotes the PID. An unobservable one is kept, exactly
+// as if the cross-check had not run — the dispatch stays on its normal bounded
+// orphan path and is re-evaluated next tick.
+function evaluateLivePidCommandLine(livePid, opts = {}) {
+  if (!livePid) return { treatAsDead: false, inconclusive: true, reason: 'no-pid-file' };
+  const inspect = opts.inspect || shared.inspectProcessCommandLineForAgent;
+  const evidence = inspect(livePid, opts.inspectOpts || {}) || {};
+  if (!evidence.conclusive) {
+    return { treatAsDead: false, inconclusive: true, reason: evidence.reason || 'unobservable' };
+  }
+  return { treatAsDead: !evidence.match, inconclusive: false, reason: evidence.reason || 'conclusive' };
+}
+
 // Last-resort liveness check via the on-disk PID file (engine/tmp/pid-<safeId>.pid).
 // Used by orphan detection to avoid false-positive kills when the engine has lost the
 // tracked process handle (engine restart, never-tracked spawn, etc.) but the OS-level
 // child process is still alive and healthy. The safeId here mirrors engine.js spawn
-// (id.replace(/[:\\/*?"<>|]/g, '-')) — same pattern engine/cli.js uses to re-attach.
-function isOsPidAliveForDispatch(itemId) {
+// (id.replace(/[:\\/*?"<>|]/g, '-')) — same pattern engine/operations/cli.js uses to re-attach.
+function isOsPidAliveForDispatch(itemId, opts = {}) {
   const pid = _readDispatchPid(itemId);
   if (!pid) return false;
-  try { process.kill(pid, 0); return true; }
-  catch { return false; }
+  // W-ms6dmv99005o26f4 — EPERM is proof of existence, not of death.
+  return shared.inspectPidLiveness(pid, opts).alive;
 }
 
 function readFileTail(filePath, maxBytes) {
@@ -733,10 +754,10 @@ function readAcceptedCompletionReport(item, procInfo) {
   const expectedNonce = procInfo?._completionNonce || null;
   if (!expectedNonce) return null;
   try {
-    const report = require('./lifecycle').parseCompletionReportFile(item);
-    if (!report) return null;
-    if (typeof report.nonce !== 'string' || report.nonce !== expectedNonce) return null;
-    return report;
+    return shared.acceptCompletionReportForNonce(
+      require('./lifecycle').parseCompletionReportFile(item),
+      expectedNonce,
+    );
   } catch (e) {
     log('warn', `resume-stall completion-report probe failed for ${item?.id}: ${e.message}`);
     return null;
@@ -745,12 +766,14 @@ function readAcceptedCompletionReport(item, procInfo) {
 
 function parseProcessExitCode(logText) {
   if (!logText) return null;
-  const exitPattern = /(?:^|\n)\[process-exit\]\s+(?:code=)?(-?\d+|spawn-failed)(?=\s|$)/g;
-  let lastMatch = null;
-  let m;
-  while ((m = exitPattern.exec(logText)) !== null) lastMatch = m;
-  if (!lastMatch) return null;
-  return lastMatch[1] === 'spawn-failed' ? -1 : parseInt(lastMatch[1], 10);
+  // A sentinel is terminal evidence only while it remains the final non-empty
+  // line. Agent live-output files survive engine restarts and can therefore
+  // contain an old sentinel followed by a newer attempt's active output.
+  const match = String(logText).match(
+    /(?:^|\n)\[process-exit\]\s+(?:code=)?(-?\d+|spawn-failed)[^\S\r\n]*(?:\r?\n)?\s*$/
+  );
+  if (!match) return null;
+  return match[1] === 'spawn-failed' ? -1 : parseInt(match[1], 10);
 }
 
 function terminalResultIndicatesError(obj) {
@@ -817,11 +840,12 @@ function checkTimeouts(config) {
   //    The exception is a resumed runtime that has not produced its first stdout/stderr
   //    heartbeat after spawn; that is the "alive but stuck in --resume" failure mode.
   const dispatchData = getDispatch();
+  cancelTrackedProcessesWithoutDispatch(activeProcesses, dispatchData.active);
   const deadItems = [];
   const legacyAnnotationClears = new Set();
   const finalizationPromises = [];
 
-  function completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess, expectedProcInfo = activeProcesses.get(item.id)) {
+  function completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess, expectedProcInfo = activeProcesses.get(item.id), completionPath = shared.DISPATCH_COMPLETION_PATH.OUTPUT_DETECTION) {
     if (hasProcess && (
       expectedProcInfo?._steeringAt
       || expectedProcInfo?._steeringMessage
@@ -951,6 +975,7 @@ function checkTimeouts(config) {
       }
 
       const completionOpts = {
+        completionPath,
         ...(structuredCompletion?._path ? { completionReportPath: structuredCompletion._path } : {}),
         ...(structuredCompletion ? { structuredCompletion } : {}),
       };
@@ -1040,7 +1065,7 @@ function checkTimeouts(config) {
 
       if (shared.isLiveCheckoutDispatchRecord(item, config)) {
         try {
-          await require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
+          await require('../worktrees/live-checkout').maybeRestoreLiveCheckoutFromRecord({
             item,
             config,
             isTerminalFailure: effectiveResult === DISPATCH_RESULT.ERROR,
@@ -1210,7 +1235,8 @@ function checkTimeouts(config) {
             // race against our own cleanup. procInfo is still passed as the
             // expected proc info so the per-spawn nonce is available to the
             // lifecycle hooks.
-            completeFromOutput(item, liveLogPath, 0, liveLogTailForItem(liveLogPath), false, procInfo);
+            completeFromOutput(item, liveLogPath, 0, liveLogTailForItem(liveLogPath), false, procInfo,
+              shared.DISPATCH_COMPLETION_PATH.RESUME_STALL_REPORT);
             activeProcesses.delete(item.id);
             killTrackedProcess(procInfo, { graceMs: 5000 });
             continue;
@@ -1223,7 +1249,12 @@ function checkTimeouts(config) {
           try { shared.safeUnlink(path.join(AGENTS_DIR, item.agent, 'session.json')); } catch {}
           activeProcesses.delete(item.id);
           killTrackedProcess(procInfo, { graceMs: 5000 });
-          deadItems.push({ item, reason, failureClass: FAILURE_CLASS.TIMEOUT });
+          deadItems.push({
+            item,
+            reason,
+            failureClass: FAILURE_CLASS.TIMEOUT,
+            completionPath: shared.DISPATCH_COMPLETION_PATH.RESUME_STALL_TIMEOUT,
+          });
         }
       }
       continue;
@@ -1276,7 +1307,7 @@ function checkTimeouts(config) {
       // Last-resort PID check: lost tracked handle but OS process may still be alive.
       // P-3f5b7d26 — SKIPPED for pooled dispatches (item.pooled, persisted by
       // engine.js#spawnAgent). The PID recorded for a pooled dispatch is the
-      // shared ACP worker's real OS pid (engine/acp-transport.js#spawnAcp),
+      // shared ACP worker's real OS pid (engine/agents/acp-transport.js#spawnAcp),
       // whose command line is literally `copilot --acp ...` — it would always
       // pass isProcessCommandLineMatchingAgent's `cmdline.includes('copilot')`
       // check below even though that worker has no relationship to THIS
@@ -1290,11 +1321,23 @@ function checkTimeouts(config) {
         // under an unrelated process (Windows reuses PIDs aggressively). Without
         // this cmdline gate, the dispatch is parked indefinitely as 'active'
         // pinned to a process that has nothing to do with the agent.
+        //
+        // W-ms6dmv99005o26f4 — this gate must fire on OBSERVED mismatch only. The
+        // boolean helper also returns false when the per-PID command-line probe
+        // itself fails (PowerShell Get-CimInstance timing out under fleet load,
+        // /proc read racing a namespace, `ps` spawn EAGAIN), which turned a probe
+        // outage into "treating as dead" for every silent dispatch at once — the
+        // second link of the 2026-07-29T17:44Z false-orphan storm. An alive OS PID
+        // we merely failed to inspect is kept, exactly as if the probe had not run.
         const livePid = _readDispatchPid(item.id);
-        if (livePid && !shared.isProcessCommandLineMatchingAgent(livePid)) {
+        const cmdlineEvidence = evaluateLivePidCommandLine(livePid);
+        if (cmdlineEvidence.treatAsDead) {
           log('warn', `Orphan check: ${item.agent} (${item.id}) — PID ${livePid} alive but command line doesn't match agent, treating as dead`);
           processAlive = false;
         } else {
+          if (cmdlineEvidence.inconclusive) {
+            log('warn', `Orphan check: ${item.agent} (${item.id}) — PID ${livePid} alive but command line could not be observed (${cmdlineEvidence.reason}); keeping the dispatch rather than inferring death`);
+          }
           log('info', `Orphan check: ${item.agent} (${item.id}) silent ${silentSec}s but OS PID is alive — keeping [${_logState}]`);
           continue;
         }
@@ -1324,16 +1367,20 @@ function checkTimeouts(config) {
       dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, `Orphaned — no process, silent for ${silentSec}s`);
       // Clear session so retry starts fresh
       try { shared.safeUnlink(path.join(AGENTS_DIR, item.agent, 'session.json')); } catch {}
-      deadItems.push({ item, reason: `Orphaned — no process, silent for ${silentSec}s` });
+      deadItems.push({
+        item,
+        reason: `Orphaned — no process, silent for ${silentSec}s`,
+        failureClass: confirmedDeadAtRestart ? FAILURE_CLASS.ENGINE_RESTART : FAILURE_CLASS.TIMEOUT,
+      });
       activeProcesses.delete(item.id);
     }
   }
 
   // Clean up dead items
-  for (const { item, reason, failureClass } of deadItems) {
+  for (const { item, reason, failureClass, completionPath } of deadItems) {
     const finalizationOwner = 'timeout-orphan';
     if (!shared.claimDispatchFinalization(item.id, finalizationOwner)) continue;
-    const finalizationPromise = _finalizeDeadDispatch(item, reason, failureClass, config, { complete: completeDispatch })
+    const finalizationPromise = _finalizeDeadDispatch(item, reason, failureClass, config, { complete: completeDispatch, completionPath })
       .catch(err => log('warn', `Orphan cleanup failed for ${item.id}: ${err.message}`))
       .finally(() => shared.releaseDispatchFinalization(item.id, finalizationOwner));
     finalizationPromises.push(finalizationPromise);
@@ -1413,14 +1460,16 @@ module.exports = {
   checkIdleThreshold,
   dropSteeringForPurgedSession,
   isOsPidAliveForDispatch,
+  evaluateLivePidCommandLine, // exported for testing
+  _isTrackedProcessAlive: isTrackedProcessAlive, // exported for testing
   parseProcessExitCode, terminalResultIndicatesError, parseTerminalResultFallbackExitCode, // exported for testing
   readFileTail, runtimeSupportsMidRunSessionId, // exported for testing
   readAcceptedCompletionReport, liveLogTailForItem, // exported for testing (W-ms0vk9nv000z985b)
   // exported for testing
-  rememberDeferredSteering, checkDeferredStranded, _runSteeringKillLadder, _collectDescendantPids,
+  rememberDeferredSteering, checkDeferredStranded, _runSteeringKillLadder,
   _resetSteeringStoreCacheForTest, _setSteeringStoreForTest,
   // exported for testing — steering clamp helpers and deferred checkpoint
   _clampSteeringDeferredMaxMs, _clampSteeringMaxKillRetries, _appendLiveOutputLine, deferSteeringUntilCheckpoint,
-  killTrackedProcess, _escalatePlatformKill, // exported for testing — P-6e2a4c15 cancel-vs-kill
+  killTrackedProcess, cancelTrackedProcessesWithoutDispatch, _escalatePlatformKill, // exported for testing — P-6e2a4c15 cancel-vs-kill
   _finalizeDeadDispatch, // exported for testing
 };

package/engine/{db-events.js → persistence/db-events.js}

@@ -1,4 +1,4 @@
-// engine/db-events.js — `emitStateEvent(topic, payload?)` helper.
+// engine/persistence/db-events.js — `emitStateEvent(topic, payload?)` helper.
 //
 // Append a row to the `events` table so the dashboard's status cache (and
 // any future topic-scoped subscriber) sees the change on its next poll.
@@ -16,7 +16,7 @@ let _logged = false;
 
 function emitStateEvent(topic, payload) {
   try {
-    const { getDb } = require('./db');
+    const { getDb } = require('../db');
     const db = getDb();
     if (payload !== undefined && payload !== null) {
       db.prepare('INSERT INTO events (topic, payload) VALUES (?, ?)')

package/engine/{dispatch-store.js → persistence/dispatch-store.js}

@@ -1,4 +1,4 @@
-// engine/dispatch-store.js — SQL-backed section-shaped dispatch state:
+// engine/persistence/dispatch-store.js — SQL-backed section-shaped dispatch state:
 //
 //   readDispatchSectioned()   -> { pending, active, completed, review }
 //   applyDispatchMutation(fn) -> runs fn against the section object,
@@ -9,8 +9,8 @@
 //                                (event emission, cache invalidation)
 //                                when nothing actually changed.
 //
-// All callers go through engine/dispatch.js#mutateDispatch and
-// engine/queries.js#getDispatch as before — those are thin wrappers
+// All callers go through engine/orchestration/dispatch.js#mutateDispatch and
+// engine/core/queries.js#getDispatch as before — those are thin wrappers
 // over the helpers here. Zero changes at any call site.
 
 const SECTIONS = ['pending', 'active', 'completed', 'review'];
@@ -33,7 +33,7 @@ function _parseRow(row) {
 }
 
 function readDispatchSectioned() {
-  const { getDb } = require('./db');
+  const { getDb } = require('../db');
   const db = getDb();
 
   // Return the complete dispatch state regardless of how old
@@ -59,7 +59,7 @@ function readDispatchSectioned() {
 // not just the recent window. Mutators that prune old completed
 // dispatches MUST see those rows or the prune is a no-op.
 function _readDispatchSectionedFull() {
-  const { getDb } = require('./db');
+  const { getDb } = require('../db');
   let db;
   try { db = getDb(); }
   catch { return _emptySectioned(); }
@@ -169,11 +169,11 @@ function _applyDispatchDiff(db, diff) {
 //            mutator mutated in place + returned undefined). Same
 //            contract as the legacy mutateJsonFileLocked-based path.
 function applyDispatchMutation(mutator) {
-  const { getDb, withTransaction } = require('./db');
+  const { getDb, withTransaction } = require('../db');
   let db;
   try { db = getDb(); }
   catch (e) {
-    throw new Error(`engine/dispatch-store: SQLite unavailable (${e.message}); cannot mutate dispatch state`);
+    throw new Error(`engine/persistence/dispatch-store: SQLite unavailable (${e.message}); cannot mutate dispatch state`);
   }
 
   // withTransaction is nestable: shared.mutateWorkItems → mutator → cli

package/engine/{inbox-store.js → persistence/inbox-store.js}

@@ -1,4 +1,4 @@
-// engine/inbox-store.js — SQL-backed inbox_entries table handlers.
+// engine/persistence/inbox-store.js — SQL-backed inbox_entries table handlers.
 //
 // Provides read/write helpers for the operator and agent inbox message queue.
 // Inboxes are decoupled from the runtime work-item/dispatch lifecycle and
@@ -7,7 +7,7 @@
 // Schema: docs/design-inbox-entries-schema.md
 
 const crypto = require('node:crypto');
-const { getDb, withTransaction } = require('./db');
+const { getDb, withTransaction } = require('../db');
 
 // Per CLAUDE.md's "State storage" mutator contract, every mutator wrapper
 // must call emitStateEvent() after a successful write so the dashboard's

package/engine/{note-link-backfill.js → persistence/note-link-backfill.js}

@@ -1,4 +1,4 @@
-// engine/note-link-backfill.js
+// engine/persistence/note-link-backfill.js
 //
 // One-time repair for work-item note links that broke BEFORE the live
 // rewrite landed (W-mq1j85cj00055a8f extended to _artifacts.notes / artifacts).
@@ -18,7 +18,7 @@
 // notes.md) are left untouched. Idempotent: a second pass finds nothing because
 // the repaired links no longer reference `notes/inbox/`.
 //
-// Wired as an idempotent engine-boot sweep (engine/cli.js, alongside the other
+// Wired as an idempotent engine-boot sweep (engine/operations/cli.js, alongside the other
 // one-shot boot migrations). It runs through shared.mutateWorkItems — the same
 // write path the live rewriter uses — so the canonical SQL store and its JSON
 // mirror stay consistent, and it's a no-op once every link is healed.
@@ -53,7 +53,7 @@ function buildNoteResolver(dirs) {
   const kbCategories = Array.isArray(dirs.kbCategories) ? dirs.kbCategories : [];
   // Reuse the live rewriter's encoder so the backfill and the live path emit
   // byte-identical pill tokens (one source for the archive:/kb: grammar).
-  const tokenFor = require('./shared')._artifactNoteFileToken;
+  const tokenFor = require('../core/shared')._artifactNoteFileToken;
 
   const archiveByBase = new Map();
   let archiveFiles = [];
@@ -150,7 +150,7 @@ function repointItemNoteLinks(item, resolve) {
 
 // Repair broken note links across every project scope plus central.
 function runNoteLinkBackfill(opts = {}) {
-  const shared = require('./shared');
+  const shared = require('../core/shared');
   const minionsDir = opts.minionsDir || shared.MINIONS_DIR;
   const resolve = buildNoteResolver({
     inboxDir: path.join(minionsDir, 'notes', 'inbox'),