@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{cli.js → operations/cli.js}

@@ -1,27 +1,27 @@
 /**
- * engine/cli.js — CLI command handlers for Minions engine.
+ * engine/operations/cli.js — CLI command handlers for Minions engine.
  * Extracted from engine.js to reduce monolith size.
  */
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/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 { resolveCommentExecutionModel } = require('./execution-model');
+const queries = require('../core/queries');
+const agentWorkerPool = require('../agents/agent-worker-pool');
+const { resolveCommentExecutionModel } = require('../core/execution-model');
 const { getConfig, getControl, getDispatch, getAgentStatus,
   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;
 function engine() {
-  if (!_engine) _engine = require('../engine');
+  if (!_engine) _engine = require('../../engine');
   return _engine;
 }
 
 let _dispatchModule = null;
-function dispatchModule() { if (!_dispatchModule) _dispatchModule = require('./dispatch'); return _dispatchModule; }
+function dispatchModule() { if (!_dispatchModule) _dispatchModule = require('../orchestration/dispatch'); return _dispatchModule; }
 
 function spawnPendingDispatch(e, item, config) {
   return e._withSpawnAttemptLease(
@@ -81,13 +81,54 @@ function readDispatchPid(itemId) {
   catch { return null; }
 }
 
-function isPidAlive(pid) {
-  try {
-    process.kill(shared.validatePid(pid), 0);
-    return true;
-  } catch {
-    return false;
+// W-ms6dmv99005o26f4 — routed through the tri-state probe in engine/process-utils.js
+// so an EPERM (process EXISTS, signal refused) is no longer read as death. A false
+// here zeroes `agentPid` at reattach, which is the `hadPid && !agentPid` condition
+// that marks a dispatch confirmed-dead and exempts it from the orphan grace window.
+function isPidAlive(pid, opts = {}) {
+  let value;
+  try { value = shared.validatePid(pid); }
+  catch { return false; }
+  return shared.inspectPidLiveness(value, opts).alive;
+}
+
+// W-ms6dmv99005o26f4 — restart reattach evidence, exported for testing.
+//
+// Decides whether a surviving OS PID may be reattached to a dispatch, and — just
+// as importantly — whether a refusal is backed by evidence. `conclusive: false`
+// means "we could not observe this process", which is NOT the same as "this
+// process is gone" and must never be escalated to a confirmed-dead marking.
+function evaluateReattachEvidence({ pid, runtimePidObservedAt, snapshot, probes = {} } = {}) {
+  const inspectIdentity = probes.inspectProcessIdentity || shared.inspectProcessIdentity;
+  const inspectCommandLine = probes.inspectProcessCommandLineForAgent || shared.inspectProcessCommandLineForAgent;
+  const observedAt = Number(runtimePidObservedAt);
+
+  // Recycled-PID guard: a process that started AFTER we recorded the launch cannot
+  // be our agent. Only meaningful when a launch timestamp was persisted.
+  if (observedAt > 0) {
+    const identity = inspectIdentity(pid, { processes: snapshot });
+    if (!identity.conclusive) {
+      return { reattach: false, conclusive: false, reason: `PID ${pid} identity evidence unavailable (${identity.reason})` };
+    }
+    if (!shared.isProcessIdentityCompatible(identity.identity, observedAt, 2000)) {
+      return { reattach: false, conclusive: true, reason: `PID ${pid} identity does not match the recorded launch` };
+    }
+  }
+
+  const cmdline = inspectCommandLine(pid, { processes: snapshot });
+  if (!cmdline.conclusive) {
+    return { reattach: false, conclusive: false, reason: `PID ${pid} command-line evidence unavailable (${cmdline.reason})` };
+  }
+  if (!cmdline.match) {
+    return { reattach: false, conclusive: true, reason: `PID ${pid} command line does not match an agent runtime` };
   }
+  return { reattach: true, conclusive: true, reason: 'verified' };
+}
+
+// W-ms6dmv99005o26f4 — the single decision that turns a restart-time observation
+// into an instant orphan. Exported for testing.
+function shouldMarkConfirmedDeadAtRestart({ hadPid, agentPid, inconclusive } = {}) {
+  return !!hadPid && !agentPid && !inconclusive;
 }
 
 function summarizeActiveDispatchPids(activeItems = []) {
@@ -356,7 +397,7 @@ function _parseRuntimeFlags(args) {
 function _modelLooksIncompatible(runtime, model) {
   if (!model) return false;
   let adapter;
-  try { adapter = require('./runtimes').resolveRuntime(runtime); }
+  try { adapter = require('../runtimes').resolveRuntime(runtime); }
   catch { return false; } // unknown runtime → no opinion
   if (typeof adapter.modelLooksFamiliar !== 'function') return false; // adapter doesn't claim a model namespace → no opinion
   return !adapter.modelLooksFamiliar(model);
@@ -381,7 +422,7 @@ function _applyRuntimeFlags({ cli, model, modelExplicit }) {
   // Validate the runtime name BEFORE touching disk so typos fail loudly with
   // a list of registered runtimes — same UX shape as resolveRuntime() throws.
   let registered = [];
-  try { registered = require('./runtimes').listRuntimes(); }
+  try { registered = require('../runtimes').listRuntimes(); }
   catch { /* registry missing during partial install — skip validation */ }
   if (cli !== undefined && registered.length > 0 && !registered.includes(cli)) {
     const err = new Error(`Unknown CLI runtime "${cli}". Registered runtimes: ${registered.join(', ')}`);
@@ -449,7 +490,7 @@ const commands = {
 
     // Run preflight checks (warn but don't block — engine may still be useful)
     try {
-      const { runPreflight, printPreflight } = require('./preflight');
+      const { runPreflight, printPreflight } = require('../agents/preflight');
       // Pass config so runtime-fleet warnings (P-3b8e5f1d) can fire pre-start.
       // getConfig() is cheap (cached); failure here is non-fatal — preflight
       // simply skips the runtime-config warnings when config is missing.
@@ -497,9 +538,9 @@ const commands = {
     // Bust require cache so npm updates are detected after minions restart
     let codeVersion = null;
     try {
-      const pkgPath = require.resolve('../package.json');
+      const pkgPath = require.resolve('../../package.json');
       delete require.cache[pkgPath];
-      codeVersion = require('../package.json').version;
+      codeVersion = require('../../package.json').version;
     } catch {}
     if (!codeVersion) {
       try {
@@ -509,7 +550,7 @@ const commands = {
       } catch {}
     }
     let codeCommit = null;
-    try { codeCommit = require('child_process').execSync('git rev-parse --short HEAD', { cwd: path.resolve(__dirname, '..'), encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] }).trim(); } catch {}
+    try { codeCommit = require('child_process').execSync('git rev-parse --short HEAD', { cwd: path.resolve(__dirname, '..', '..'), encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] }).trim(); } catch {}
     const controlOwner = createControlOwner();
     mutateControl(() => ({
       state: 'running',
@@ -556,7 +597,7 @@ const commands = {
     // 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 });
+      const res = require('../persistence/note-link-backfill').runNoteLinkBackfill({ config });
       if (res.fixedLinks > 0) {
         e.log('info', `Repointed ${res.fixedLinks} broken note link(s) across ${res.fixedItems} work item(s)`);
         console.log(`  Repaired ${res.fixedLinks} broken note link(s) in ${res.fixedItems} work item(s).`);
@@ -565,7 +606,7 @@ const commands = {
 
     // Backfill work_items.prd_item_id for rows created before FK stamping.
     try {
-      const fk = require('./prd-store').backfillWorkItemPrdItemIds();
+      const fk = require('../planning/prd-store').backfillWorkItemPrdItemIds();
       const filled = (fk.byWorkItemId || 0) + (fk.bySourcePlan || 0);
       if (fk.ok && filled > 0) {
         e.log('info', `Backfilled prd_item_id on ${filled} work item(s) (${fk.byWorkItemId} by workItemId, ${fk.bySourcePlan} by sourcePlan)`);
@@ -596,7 +637,7 @@ const commands = {
     } catch (err) { e.log('warn', `workSources auto-heal failed: ${err.message}`); }
     const interval = config.engine?.tickInterval || shared.ENGINE_DEFAULTS.tickInterval;
 
-    const { getProjects } = require('./shared');
+    const { getProjects } = require('../core/shared');
     const projects = getProjects(config);
     if (projects.length === 0) {
       console.log('  \x1b[33mNo projects configured.\x1b[0m Link one with: minions add <path-to-repo>');
@@ -624,6 +665,15 @@ const commands = {
     const dispatch = getDispatch();
     const activeOnStart = (dispatch.active || []);
     if (activeOnStart.length > 0) {
+      let processSnapshot = shared.captureProcessSnapshot();
+      if (!processSnapshot.ok) {
+        // W-ms6dmv99005o26f4 — a failed enumeration used to be swallowed into an
+        // empty array that then "proved" every active dispatch was gone. Log it
+        // loudly: the reattach verdicts below now degrade to inconclusive, which
+        // keeps the fleet on the normal bounded orphan grace window instead of
+        // reaping it on the next tick.
+        e.log('warn', `Restart: process enumeration unavailable (${processSnapshot.reason}) — reattach evidence will be re-probed per PID`);
+      }
       let reattached = 0;
       for (const item of activeOnStart) {
         const agentId = item.agent;
@@ -631,10 +681,10 @@ const commands = {
         // P-3f5b7d26 — a pooled dispatch (engine.js#spawnAgent, item.pooled
         // persisted at dispatch-time) can NEVER be reattached, regardless of
         // what the PID file says. The ACP worker child
-        // (engine/acp-transport.js#spawnAcp) is not spawned with
+        // (engine/agents/acp-transport.js#spawnAcp) is not spawned with
         // `detached: true` like the cold-spawn path, and even on the rare
         // chance its OS process survived the restart, the freshly-started
-        // engine's engine/agent-worker-pool.js always cold-starts with an
+        // engine's engine/agents/agent-worker-pool.js always cold-starts with an
         // empty worker set — there is no in-process handle whose stdio could
         // be reconnected to that PID. Treating a live-but-orphaned worker PID
         // as "still running" here would silently hang the dispatch forever
@@ -688,17 +738,50 @@ const commands = {
           }
         }
 
+        const runtimePidObservedAt = Number(item.runtimePidObservedAt);
         if (agentPid && agentPid > 0 && !isPidAlive(agentPid)) agentPid = null;
+        // W-ms6dmv99005o26f4 — `inconclusiveEvidence` records that we refused the
+        // reattach because we could not OBSERVE the process, not because we saw it
+        // gone. Refusing is still correct (never reattach to an unverified PID),
+        // but the confirmed-dead marking below must not follow from it.
+        let inconclusiveEvidence = false;
+        if (agentPid && agentPid > 0) {
+          const verdict = evaluateReattachEvidence({
+            pid: agentPid,
+            runtimePidObservedAt,
+            snapshot: processSnapshot,
+          });
+          if (!verdict.reattach) {
+            e.log('warn', `Reattach: refusing ${item.id} — ${verdict.reason}`);
+            if (!verdict.conclusive) inconclusiveEvidence = true;
+            agentPid = null;
+          }
+        }
         if (agentPid && !shared.isDispatchExecutionPathSafe(item, config)) {
           e.log('warn', `Reattach: refusing ${item.id} — persisted execution path is not safe under current checkout config`);
-          try { shared.killImmediate({ pid: agentPid }); }
+          try {
+            shared.terminateProcess('engine.cli.unsafe-reattach', { pid: agentPid }, {
+              recordedAtMs: runtimePidObservedAt,
+              processes: processSnapshot,
+              skewMs: 2000,
+            });
+          }
           catch (err) { e.log('warn', `Reattach: failed to terminate unsafe dispatch ${item.id}: ${err.message}`); }
           agentPid = null;
         }
 
-        // PID was found but confirmed dead — exempt from restart grace period (#869)
-        if (hadPid && !agentPid) {
+        // PID was found but confirmed dead — exempt from restart grace period (#869).
+        // W-ms6dmv99005o26f4 — the exemption sets `confirmedDeadAtRestart` in
+        // engine/timeout.js, which bypasses BOTH minAliveBeforeOrphanMs and the
+        // engine-restart grace window, so the dispatch is orphaned on the very next
+        // tick after only seconds of silence. That is the correct handling for a PID
+        // we OBSERVED to be dead, and catastrophic for one we merely failed to
+        // observe — hence the conclusive-evidence gate.
+        if (shouldMarkConfirmedDeadAtRestart({ hadPid, agentPid, inconclusive: inconclusiveEvidence })) {
           e.engineRestartGraceExempt.add(item.id);
+          e.log('info', `Restart: ${agentId} (${item.id}) runtime PID confirmed dead or mismatched — marking for infrastructure recovery`);
+        } else if (hadPid && !agentPid) {
+          e.log('warn', `Restart: ${agentId} (${item.id}) liveness evidence was unavailable — NOT marking confirmed dead; the standard orphan grace window applies`);
         }
 
         if (agentPid) {
@@ -723,7 +806,15 @@ const commands = {
             }
           } catch {}
           const runtimeName = item.runtimeName || item.runtime || item.meta?.runtimeName || item.meta?.runtime || null;
-          e.activeProcesses.set(item.id, { proc: { pid: agentPid > 0 ? agentPid : null }, agentId, startedAt: item.created_at, reattached: true, sessionId, runtimeName });
+          e.activeProcesses.set(item.id, {
+            proc: { pid: agentPid > 0 ? agentPid : null },
+            agentId,
+            startedAt: item.created_at,
+            reattached: true,
+            sessionId,
+            runtimeName,
+            runtimePidObservedAt: item.runtimePidObservedAt,
+          });
           // Sync work item status to dispatched — atomic write to avoid lifecycle lazy init issues
           if (item.meta?.item?.id && item.meta?.project?.localPath) {
             try {
@@ -761,8 +852,8 @@ const commands = {
     // check if the agent actually completed by scanning its output file.
     // If it did, run the post-completion hooks now so work items get updated.
     (function detectOrphanCompletions() {
-      const shared = require('./shared');
-      const lifecycle = require('./lifecycle');
+      const shared = require('../core/shared');
+      const lifecycle = require('../orchestration/lifecycle');
       let recovered = 0;
 
       for (const item of activeOnStart) {
@@ -859,7 +950,7 @@ const commands = {
           // originalRef fields.
           if (shared.isLiveCheckoutDispatchRecord(item, config)) {
             try {
-              require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
+              require('../worktrees/live-checkout').maybeRestoreLiveCheckoutFromRecord({
                 item,
                 config,
                 isTerminalFailure: !isSuccess,
@@ -887,7 +978,7 @@ const commands = {
 
     // Recovery sweep
     (function recoverBrokenState() {
-      const shared = require('./shared');
+      const shared = require('../core/shared');
       const projects = shared.getProjects(config);
       let fixes = 0;
 
@@ -927,7 +1018,7 @@ const commands = {
     // operates on `active`/`linked`, so there is no per-record race.
     (function startupReconcileAbandonedPrs() {
       try {
-        const reconciler = require('./abandoned-pr-reconciliation');
+        const reconciler = require('../providers/abandoned-pr-reconciliation');
         Promise.resolve(reconciler.runStartupReconciliation(config))
           .then(result => {
             if (!result.skipped && result.totals.flipped > 0) {
@@ -948,7 +1039,7 @@ const commands = {
     // dead). Run once at boot before the first tick. Idempotent.
     (function startupReconcileKeepProcesses() {
       try {
-        const { sweepKeepProcesses } = require('./keep-process-sweep');
+        const { sweepKeepProcesses } = require('../processes/keep-process-sweep');
         const stats = sweepKeepProcesses();
         if (stats.scanned > 0 && (stats.expiredFiles || stats.deadFiles)) {
           console.log(`  Keep-processes boot reconcile: ${stats.expiredFiles} expired, ${stats.deadFiles} dead, ${stats.killedPids} killed`);
@@ -966,8 +1057,8 @@ const commands = {
     // fire-and-forget — the first tick is allowed to start regardless.
     (function startupReconcileManagedSpawn() {
       try {
-        const managedSpawn = require('./managed-spawn');
-        const limits = (require('./shared').ENGINE_DEFAULTS.managedSpawn || {});
+        const managedSpawn = require('../processes/managed-spawn');
+        const limits = (require('../core/shared').ENGINE_DEFAULTS.managedSpawn || {});
         if (limits.enabled === false) return;
         const maxMs = Math.max(1, Number(limits.bootReconcileMaxMs) || 2000);
         let settled = false;
@@ -1004,11 +1095,11 @@ const commands = {
     // boot prune just keeps re-attach sane.
     (function startupReconcileWorktreePool() {
       try {
-        const worktreePool = require('./worktree-pool');
-        const dispatchSnap = require('./queries').getDispatch();
+        const worktreePool = require('../worktrees/pool');
+        const dispatchSnap = require('../core/queries').getDispatch();
         const activeIds = new Set((dispatchSnap.active || []).map(d => d.id));
-        const cfg = require('./queries').getConfig();
-        const idleTtlMs = cfg?.engine?.worktreePoolIdleTtlMs ?? require('./shared').ENGINE_DEFAULTS.worktreePoolIdleTtlMs;
+        const cfg = require('../core/queries').getConfig();
+        const idleTtlMs = cfg?.engine?.worktreePoolIdleTtlMs ?? require('../core/shared').ENGINE_DEFAULTS.worktreePoolIdleTtlMs;
         const result = worktreePool.pruneStale({ activeDispatchIds: activeIds, idleTtlMs });
         if (result.evicted > 0) {
           console.log(`  Worktree-pool boot reconcile: evicted ${result.evicted} stale entr${result.evicted === 1 ? 'y' : 'ies'}`);
@@ -1029,10 +1120,10 @@ const commands = {
     // about to be pruned but still appeared as a pool member).
     (function startupReconcileOrphanWorktrees() {
       try {
-        const sharedMod = require('./shared');
-        const worktreeGc = require('./worktree-gc');
-        const dispatchSnap = require('./queries').getDispatch();
-        const cfg = require('./queries').getConfig();
+        const sharedMod = require('../core/shared');
+        const worktreeGc = require('../worktrees/gc');
+        const dispatchSnap = require('../core/queries').getDispatch();
+        const cfg = require('../core/queries').getConfig();
         const projects = sharedMod.getProjects(cfg);
         if (projects.length === 0) return;
         const worktreeProjects = projects.filter((project) => {
@@ -1092,7 +1183,7 @@ const commands = {
     // /api/knowledge/sweep/status until someone POSTs a new sweep. Idempotent.
     (function startupReconcileKbSweep() {
       try {
-        const { reconcileSweepStateOnBoot } = require('./kb-sweep');
+        const { reconcileSweepStateOnBoot } = require('../memory/kb-sweep');
         const stats = reconcileSweepStateOnBoot();
         if (stats.released > 0) {
           console.log(`  KB-sweep boot reconcile: released stale ${stats.prevStatus} record (pid=${stats.prevPid}, reason=${stats.reason})`);
@@ -1109,7 +1200,7 @@ const commands = {
     // shares the same promise.
     (function warmKnowledgeBaseCache() {
       try {
-        const queries = require('./queries');
+        const queries = require('../core/queries');
         Promise.resolve(queries.getKnowledgeBaseEntries())
           .catch(err => e.log('warn', `KB cache warm failed: ${err && err.message}`));
       } catch (err) {
@@ -1140,7 +1231,7 @@ const commands = {
 
     // Fast poll: check steering every 1s (lightweight — just fs.stat per agent)
     // and wakeup signals every 1s (control.json read)
-    const { checkSteering } = require('./timeout');
+    const { checkSteering } = require('../orchestration/timeout');
     const fastPollTimer = setInterval(() => {
       try { checkSteering(); } catch {}
       const ctrl = getControl();
@@ -1188,7 +1279,7 @@ const commands = {
     // a stderr line if a flush fails so a refactor mistake (typo, missing
     // export) doesn't go silent.
     function drainBuffers() {
-      try { require('./llm').flushMetricsBuffer(); }
+      try { require('../agents/llm').flushMetricsBuffer(); }
       catch (err) { console.error(`[shutdown] flushMetricsBuffer failed: ${err.message}`); }
       try { shared.flushLogs(); }
       catch (err) { console.error(`[shutdown] flushLogs failed: ${err.message}`); }
@@ -1262,7 +1353,7 @@ const commands = {
           const procInfo = e.activeProcesses.get(id);
           if (!procInfo?._pooled) continue;
           try {
-            procInfo.proc.kill();
+            shared.terminateProcess('engine.cli.shutdown-pooled', procInfo.proc);
             if (typeof procInfo.proc.waitForClose === 'function') {
               closing.push(procInfo.proc.waitForClose());
             }
@@ -1282,7 +1373,12 @@ const commands = {
             DISPATCH_RESULT.ERROR,
             'Pooled dispatch cancelled after graceful shutdown timeout',
             '',
-            { failureClass: FAILURE_CLASS.TIMEOUT, retryable: true },
+            {
+              failureClass: FAILURE_CLASS.ENGINE_RESTART,
+              retryable: true,
+              retryBudget: 'infrastructure',
+              countAgentRetryFailure: false,
+            },
           );
         }
         finishShutdown(`Shutdown timeout (${timeout / 1000}s) — cancelled ${ids.length} pooled agent(s) for retry.`, 1);
@@ -1343,7 +1439,7 @@ const commands = {
     // Write stop-intent BEFORE killing so the external supervisor (engine/
     // supervisor.js) sees the flag on its next tick and stands down instead
     // of respawning. Cleared by `minions start`/`restart` AND by every
-    // successful engine boot (engine/cli.js#start) — so a direct
+    // successful engine boot (engine/operations/cli.js#start) — so a direct
     // `node engine.js start` after this stop still clears the flag.
     if (!shared.writeStopIntent('engine.js stop')) {
       e.log('warn', 'Failed to write stop-intent');
@@ -1393,7 +1489,7 @@ const commands = {
     const dispatch = getDispatch();
     const agents = config.agents || {};
 
-    const { getProjects } = require('./shared');
+    const { getProjects } = require('../core/shared');
     const projects = getProjects(config);
 
     // Version info
@@ -1646,7 +1742,7 @@ const commands = {
     }
 
     const config = getConfig();
-    const { getProjects, resolveProjectSource, uid } = require('./shared');
+    const { getProjects, resolveProjectSource, uid } = require('../core/shared');
     const projects = getProjects(config);
     const target = opts.project ? resolveProjectSource(opts.project, projects, { allowCentral: false }) : null;
     if (target?.error) {
@@ -1670,7 +1766,7 @@ const commands = {
       }
       requestedId = opts.id.trim();
       const liveItems = readWorkItems(scope);
-      const archivedItems = require('./work-items-store').readArchivedWorkItemsForScope(scope);
+      const archivedItems = require('../planning/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 scope "${scope}" or its archive`);
         process.exit(1);
@@ -1737,7 +1833,7 @@ const commands = {
     }
 
     const config = getConfig();
-    const { getProjects, resolveProjectSource } = require('./shared');
+    const { getProjects, resolveProjectSource } = require('../core/shared');
     const projects = getProjects(config);
     const target = projectName ? resolveProjectSource(projectName, projects, { allowCentral: false }) : null;
     if (target?.error) {
@@ -1833,7 +1929,7 @@ const commands = {
   sources() {
     const e = engine();
     const config = getConfig();
-    const shared = require('./shared');
+    const shared = require('../core/shared');
     const projects = shared.getProjects(config);
 
     console.log('\n=== Work Sources ===\n');
@@ -1897,12 +1993,13 @@ const commands = {
     const e = engine();
     console.log('\n=== Kill All Active Work ===\n');
     const config = getConfig();
-    const shared = require('./shared');
+    const shared = require('../core/shared');
 
     // Kill processes via PID files (expensive — outside dispatch lock).
     // PID files live in engine/tmp/ — both legacy flat layout
     // (`pid-<id>.pid`) and per-dispatch dirs (`dispatch-<id>-XXX/pid-<id>.pid`)
     // post-P-f6-tmp-toctou. shared.forEachPidFile visits both.
+    const processSnapshot = shared.listAllProcesses();
     shared.forEachPidFile((pidPath, fileName, layout) => {
       const raw = safeRead(pidPath).trim();
       // Guard against falsy/zero/NaN PIDs. Empty pid files would resolve to
@@ -1910,14 +2007,25 @@ const commands = {
       // calling process group — which would kill the engine itself.
       let pidNum = NaN;
       try { pidNum = shared.validatePid(raw); } catch { /* invalid — skip */ }
-      if (pidNum > 0) {
+      let pidFileMtimeMs = 0;
+      try { pidFileMtimeMs = fs.statSync(pidPath).mtimeMs; } catch {}
+      const terminated = pidNum > 0 && shared.terminateProcess('engine.cli.kill-command', {
+        pid: pidNum,
+      }, {
+        recordedAtMs: pidFileMtimeMs,
+        processes: processSnapshot,
+        skewMs: 2000,
+      });
+      if (terminated) {
         // killImmediate force-kills the whole process tree (bare process.kill
         // defaults to a non-recursing SIGTERM that is Windows-broken and
         // leaks child processes — CLAUDE.md Footgun #4).
-        try { shared.killImmediate({ pid: pidNum }); console.log(`Killed process ${pidNum} (${fileName})`); }
+        try {
+          console.log(`Killed process ${pidNum} (${fileName})`);
+        }
         catch { console.log(`Process ${pidNum} already dead`); }
       } else {
-        console.log(`Skipping ${fileName}: invalid or empty PID`);
+        console.log(`Skipping ${fileName}: invalid, stale, or non-agent PID`);
       }
       if (layout === 'dispatch-dir') {
         try { shared.removeDispatchTmpDir(path.dirname(pidPath)); } catch { /* may not exist */ }
@@ -1977,7 +2085,7 @@ const commands = {
 
   'mcp-sync'() {
     // P-90a37c52 — repurposed as a harness diagnostic printer. Same source
-    // as `minions doctor --harness` (engine/preflight.js → runHarnessDoctor)
+    // as `minions doctor --harness` (engine/agents/preflight.js → runHarnessDoctor)
     // but stays exit 0 regardless of the diagnostic's hardError signal, so
     // callers that scripted around the legacy `mcp-sync` (which was a pure
     // print + exit 0) don't have their automation flipped. For an exit
@@ -1986,12 +2094,12 @@ const commands = {
     // Stays a no-op: no writes to ~/.claude.json, no state mutation. The
     // legacy "Sync MCP servers from ~/.claude.json — no sync needed."
     // message is replaced by the structured per-runtime propagation survey.
-    const { runHarnessDoctor } = require('./preflight');
+    const { runHarnessDoctor } = require('../agents/preflight');
     runHarnessDoctor(MINIONS_DIR);
   },
 
   doctor(...doctorArgs) {
-    const { doctor, runHarnessDoctor } = require('./preflight');
+    const { doctor, runHarnessDoctor } = require('../agents/preflight');
     if (doctorArgs.includes('--harness')) {
       // Read-only runtime harness inventory. See
       // docs/harness-propagation.md and the parallel branch in bin/minions.js.
@@ -2012,7 +2120,7 @@ const commands = {
       if (!cliName || cliName.startsWith('--')) {
         console.error('Usage: minions config set-cli <runtime> [--model <model>]');
         let registered = [];
-        try { registered = require('./runtimes').listRuntimes(); } catch {}
+        try { registered = require('../runtimes').listRuntimes(); } catch {}
         if (registered.length > 0) console.error(`Registered runtimes: ${registered.join(', ')}`);
         process.exit(2);
       }
@@ -2074,7 +2182,7 @@ const commands = {
     console.log('');
   },
 
-  // `minions pr <subcommand> ...` — wraps engine/gh-comment.js so playbook-
+  // `minions pr <subcommand> ...` — wraps engine/providers/gh-comment.js so playbook-
   // driven shells have a single command that automatically prepends the hidden
   // minions marker (so engine classifiers can identify agent-authored PR
   // comments by structure, not body shape).
@@ -2178,7 +2286,7 @@ const commands = {
         process.exit(2);
       }
       const orgBase = flags['org-base'] || `https://dev.azure.com/${adoOrg}`;
-      const adoComment = require('./ado-comment');
+      const adoComment = require('../ado/comment');
       adoComment.postAdoPrComment({
         orgBase, project, repositoryId, prNumber, body, agentId, kind, workItemId,
         model: executionModel.model,
@@ -2195,7 +2303,7 @@ const commands = {
     }
 
     // ── GitHub: <repo> <prNumber> ──
-    const ghComment = require('./gh-comment');
+    const ghComment = require('../providers/gh-comment');
     // GitHub conversation (issue) comments have no "resolved" concept — only
     // inline review threads can be resolved, and that needs a GraphQL
     // resolveReviewThread round-trip the agent runs itself (see shared-rules.md
@@ -2237,18 +2345,19 @@ const commands = {
   // Subcommands:
   //   status   Print enabled flag + last-seen Constellation agent timestamp.
   //   health   Probe the versioned local snapshot endpoint and print the same
-  //            metadata summary the Constellation bridge consumes.
+  //            metadata summary the Constellation bridge consumes, preceded by
+  //            the Constellation companion presence/compatibility report.
   //   enable   Atomically set engine.constellationBridge.enabled = true.
   //   disable  Atomically set engine.constellationBridge.enabled = false.
   bridge(subcmd, ...rest) {
-    const bridge = require('./bridge');
+    const bridge = require('../api/bridge');
     const BRIDGE_USAGE = 'Usage: minions bridge <status|health|enable|disable>';
 
     if (!subcmd || subcmd === 'help' || subcmd === '--help' || subcmd === '-h') {
       console.log(BRIDGE_USAGE);
       console.log('');
       console.log('  status   Show enabled flag + last-seen Constellation agent timestamp');
-      console.log('  health   Probe the local versioned Constellation snapshot');
+      console.log('  health   Probe the local versioned Constellation snapshot + report companion presence');
       console.log('  enable   Set engine.constellationBridge.enabled = true');
       console.log('  disable  Set engine.constellationBridge.enabled = false');
       return;
@@ -2289,49 +2398,30 @@ const commands = {
     }
 
     if (subcmd === 'health') {
-      const http = require('http');
-      const req = http.get(
-        { hostname: '127.0.0.1', port: 7331, path: '/api/constellation/v1/snapshot', timeout: 5000 },
-        (res) => {
-          let body = '';
-          res.setEncoding('utf8');
-          res.on('data', (chunk) => { body += chunk; });
-          res.on('end', () => {
-            if (res.statusCode !== 200) {
-              console.error(`error: dashboard returned HTTP ${res.statusCode}`);
-              process.exit(1);
-            }
-            let parsed;
-            try { parsed = JSON.parse(body); }
-            catch (e) {
-              console.error(`error: dashboard response was not JSON: ${e.message}`);
-              process.exit(1);
-            }
-            const projection = bridge.projectSnapshotHealthForBridge(parsed);
-            if (!projection) {
-              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('  snapshot (same metadata the Constellation bridge mirrors):');
-            for (const [k, v] of Object.entries(projection)) {
-              console.log(`    ${k}: ${v === null ? '(unknown)' : v}`);
-            }
-          });
-        }
-      );
-      req.on('timeout', () => {
-        req.destroy(new Error('connect timeout'));
-      });
-      req.on('error', (err) => {
-        if (err.code === 'ECONNREFUSED') {
-          console.error('error: dashboard not running on :7331 — start it with `minions dash`');
-        } else {
-          console.error(`error: ${err.message}`);
-        }
-        process.exit(1);
-      });
-      return;
+      // Companion first: it is the one part of `bridge health` that still says
+      // something useful when the dashboard is down. Bounded by construction
+      // (marker read + optional loopback probe with an explicit timeout) and
+      // never fatal — an absent or incompatible companion does not change the
+      // exit code, which stays a pure dashboard-reachability signal.
+      const companion = require('../api/companion');
+      let companionConfig = null;
+      try { companionConfig = getConfig(); } catch { /* config problems are the dashboard probe's business */ }
+      return Promise.resolve()
+        .then(() => companion.probeCompanion({
+          config: companionConfig,
+          markerPath: bridge.CONSTELLATION_BRIDGE_MARKER_PATH,
+        }))
+        .catch(() => null)
+        .then((companionResult) => {
+          for (const line of companion.formatCompanionLines(companionResult)) console.log(line);
+          _bridgeDashboardHealthProbe();
+        })
+        .catch((err) => {
+          // Preserves the pre-existing contract: any failure reaching the top of
+          // `bridge health` is an error + exit 1, never a silent rejection.
+          console.error(`error: ${(err && err.message) || err}`);
+          process.exit(1);
+        });
     }
 
     console.error(`Unknown bridge subcommand: ${subcmd}`);
@@ -2340,6 +2430,72 @@ const commands = {
   }
 };
 
+/**
+ * Probe the versioned Constellation snapshot endpoint and print its metadata
+ * summary. Extracted from `bridge health` so the companion report can be
+ * printed first without nesting the dashboard probe inside a promise body.
+ * Unchanged behavior: exit 1 on any dashboard/protocol failure.
+ */
+function _bridgeDashboardHealthProbe() {
+  const bridge = require('../api/bridge');
+  const http = require('http');
+  const req = http.get(
+    { hostname: '127.0.0.1', port: 7331, path: '/api/constellation/v1/snapshot', timeout: 5000 },
+    (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        // The snapshot endpoint is gated on engine.constellationBridge.enabled,
+        // so a 404 carrying the `bridge-disabled` code is the operator's own
+        // flag, not a broken dashboard. Name the flag and the fix instead of
+        // surfacing a bare status code. Any other non-200 keeps the generic
+        // transport-level message.
+        if (res.statusCode === 404) {
+          let gate;
+          try { gate = JSON.parse(body); } catch { gate = null; }
+          if (gate && gate.code === 'bridge-disabled') {
+            console.error('error: Constellation bridge is disabled — enable it with `minions bridge enable`');
+            console.error('  config: engine.constellationBridge.enabled = false');
+            process.exit(1);
+          }
+        }
+        if (res.statusCode !== 200) {
+          console.error(`error: dashboard returned HTTP ${res.statusCode}`);
+          process.exit(1);
+        }
+        let parsed;
+        try { parsed = JSON.parse(body); }
+        catch (e) {
+          console.error(`error: dashboard response was not JSON: ${e.message}`);
+          process.exit(1);
+        }
+        const projection = bridge.projectSnapshotHealthForBridge(parsed);
+        if (!projection) {
+          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('  snapshot (same metadata the Constellation bridge mirrors):');
+        for (const [k, v] of Object.entries(projection)) {
+          console.log(`    ${k}: ${v === null ? '(unknown)' : v}`);
+        }
+      });
+    }
+  );
+  req.on('timeout', () => {
+    req.destroy(new Error('connect timeout'));
+  });
+  req.on('error', (err) => {
+    if (err.code === 'ECONNREFUSED') {
+      console.error('error: dashboard not running on :7331 — start it with `minions dash`');
+    } else {
+      console.error(`error: ${err.message}`);
+    }
+    process.exit(1);
+  });
+}
+
 module.exports = {
   handleCommand,
   // exported for downstream indexing (dashboard CC preamble)
@@ -2357,6 +2513,8 @@ module.exports = {
   _summarizeActiveDispatchPids: summarizeActiveDispatchPids,
   _dispatchSafeId: dispatchSafeId,
   _readDispatchPid: readDispatchPid,
+  _evaluateReattachEvidence: evaluateReattachEvidence,
+  _shouldMarkConfirmedDeadAtRestart: shouldMarkConfirmedDeadAtRestart,
   _normalizeSessionBranch: normalizeSessionBranch,
   _dispatchSessionBranch: dispatchSessionBranch,
   _resolveCommentExecutionModel: resolveCommentExecutionModel, // exported for testing