@yemi33/minions 0.1.2381 → 0.1.2382

package/engine/restart-health.js

@@ -32,6 +32,14 @@ function readEngineControl(minionsHome) {
   }
 }
 
+function readSupervisorPid(minionsHome) {
+  try {
+    return normalizePid(fs.readFileSync(path.join(minionsHome, 'engine', 'supervisor.pid'), 'utf8').trim());
+  } catch {
+    return null;
+  }
+}
+
 function normalizePid(pid) {
   const n = Number(pid);
   return Number.isInteger(n) && n > 0 ? n : null;
@@ -122,7 +130,10 @@ async function checkRestartHealth(options = {}) {
     dashboardUrl,
     dashboardPid,
     dashboardPort = 7331,
+    expectedEnginePid,
+    supervisorPid,
     readControl = readEngineControl,
+    readSupervisorPid: readSupPid = readSupervisorPid,
     isProcessAlive: isAlive = isProcessAlive,
     isPortListening: portCheck = isPortListening,
     httpGetJson: getJson = httpGetJson,
@@ -130,8 +141,10 @@ async function checkRestartHealth(options = {}) {
 
   const control = readControl(minionsHome);
   const pid = normalizePid(control && control.pid);
+  const expectedEngine = normalizePid(expectedEnginePid);
   const engineAlive = pid ? isAlive(pid) : false;
-  const engineOk = control && control.state === 'running' && engineAlive;
+  const engineOwned = expectedEngine == null || pid === expectedEngine;
+  const engineOk = control && control.state === 'running' && engineAlive && engineOwned;
 
   // Two strategies for the dashboard check:
   //   1) Process + port-listening (preferred from `minions restart` since
@@ -196,11 +209,54 @@ async function checkRestartHealth(options = {}) {
     dashboardSnapshot = { kind: 'http', url, ok: !!(dashboard && dashboard.ok), statusCode: dashboard && dashboard.statusCode, status: dashboardStatus };
   }
 
+  let supervisorOk = true;
+  let supervisorSnapshot = null;
+  if (supervisorPid != null) {
+    const expectedSupervisor = normalizePid(supervisorPid);
+    const recordedSupervisor = normalizePid(readSupPid(minionsHome));
+    const supervisorAlive = expectedSupervisor ? isAlive(expectedSupervisor) : false;
+    supervisorOk = !!(expectedSupervisor && supervisorAlive && recordedSupervisor === expectedSupervisor);
+    supervisorSnapshot = {
+      pid: expectedSupervisor,
+      alive: supervisorAlive,
+      recordedPid: recordedSupervisor,
+      owned: recordedSupervisor === expectedSupervisor,
+    };
+  }
+
+  let topologyOk = true;
+  let topologySnapshot = null;
+  if (engineOk && dashboardOk && supervisorOk && options.requireExactTopology) {
+    const listPids = options.listProcessPids;
+    const scripts = options.topologyScripts || {};
+    if (typeof listPids !== 'function') {
+      topologyOk = false;
+      topologySnapshot = { error: 'process enumerator unavailable' };
+    } else {
+      const expected = {
+        engine: expectedEngine,
+        dashboard: normalizePid(dashboardPid),
+        supervisor: normalizePid(supervisorPid),
+      };
+      const actual = {};
+      for (const kind of ['engine', 'dashboard', 'supervisor']) {
+        try {
+          actual[kind] = [...new Set((listPids(scripts[kind]) || []).map(normalizePid).filter(Boolean))];
+        } catch {
+          actual[kind] = [];
+        }
+      }
+      topologyOk = Object.keys(expected).every(kind =>
+        expected[kind] != null && actual[kind].length === 1 && actual[kind][0] === expected[kind]);
+      topologySnapshot = { expected, actual };
+    }
+  }
+
   const errors = [];
   if (!engineOk) {
     const state = control && control.state ? control.state : 'unknown';
     const pidLabel = pid || 'none';
-    errors.push(`Engine is not healthy (state=${state}, pid=${pidLabel}, alive=${engineAlive ? 'yes' : 'no'})`);
+    errors.push(`Engine is not healthy (state=${state}, pid=${pidLabel}, alive=${engineAlive ? 'yes' : 'no'}, owned=${engineOwned ? 'yes' : 'no'})`);
   }
   if (!dashboardOk) {
     const where = dashboardKind === 'http'
@@ -208,11 +264,19 @@ async function checkRestartHealth(options = {}) {
       : `dashboard pid=${normalizePid(dashboardPid) || 'none'} port=${dashboardPort}`;
     errors.push(`Dashboard failed health check at ${where} (${dashboardDetail})`);
   }
+  if (!supervisorOk) {
+    errors.push(`Supervisor is not healthy (pid=${supervisorSnapshot.pid || 'none'}, alive=${supervisorSnapshot.alive ? 'yes' : 'no'}, recordedPid=${supervisorSnapshot.recordedPid || 'none'}, owned=${supervisorSnapshot.owned ? 'yes' : 'no'})`);
+  }
+  if (!topologyOk) {
+    errors.push(`Minions process topology is not exclusive (${JSON.stringify(topologySnapshot)})`);
+  }
 
   return {
-    ok: engineOk && dashboardOk,
-    engine: { state: control && control.state, pid, alive: engineAlive },
+    ok: engineOk && dashboardOk && supervisorOk && topologyOk,
+    engine: { state: control && control.state, pid, alive: engineAlive, owned: engineOwned },
     dashboard: dashboardSnapshot,
+    supervisor: supervisorSnapshot,
+    topology: topologySnapshot,
     errors,
   };
 }
@@ -310,6 +374,7 @@ module.exports = {
     isProcessAlive,
     isPortListening,
     readEngineControl,
+    readSupervisorPid,
     normalizePid,
   },
 };

package/engine/runtimes/claude.js

@@ -838,6 +838,12 @@ const capabilities = {
   budgetCap: true,
   // Supports `--bare` (suppress CLAUDE.md auto-discovery)
   bareMode: true,
+  // The Claude Code CLI reads repo-authored CLAUDE.md files itself at startup
+  // (unless `--bare`). TRUE here tells the engine's CLAUDE.md-propagation layer
+  // (engine/claude-md-context.js, injected in engine/playbook.js) to SKIP this
+  // runtime — re-injecting CLAUDE.md content into the prompt would double it.
+  // Copilot/Codex set this false because they have no native CLAUDE.md auto-load.
+  claudeMdNativeDiscovery: true,
   // Supports `--fallback-model <id>`
   fallbackModel: true,
   // Engine controls session persistence (writes session.json on completion)

package/engine/runtimes/codex.js

@@ -840,6 +840,20 @@ function getModelCacheKey({ env = process.env, timeoutMs = 10000 } = {}) {
   }
 }
 
+function getModelCacheKey({ env = process.env, timeoutMs = 10000 } = {}) {
+  const resolved = resolveBinary({ env });
+  if (!resolved) return null;
+  try {
+    return _execFileCapture(resolved.bin, [...(resolved.leadingArgs || []), '--version'], {
+      env,
+      timeoutMs,
+      native: resolved.native,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 function createStreamConsumer(ctx) {
   let deltaText = '';
   let terminalText = '';
@@ -901,6 +915,10 @@ const capabilities = {
   budgetCap: false,
   bareMode: false,
   fallbackModel: false,
+  // Codex has no native CLAUDE.md auto-load — FALSE opts it into the engine's
+  // CLAUDE.md-propagation layer (engine/claude-md-context.js) so repo-authored
+  // CLAUDE.md guidance reaches the agent prompt.
+  claudeMdNativeDiscovery: false,
   sessionPersistenceControl: false,
   resumePromptCarryover: true,
   streamConsumer: true,

package/engine/runtimes/copilot.js

@@ -1273,6 +1273,13 @@ const capabilities = {
   budgetCap: false,
   // No --bare equivalent.
   bareMode: false,
+  // Copilot has NO native CLAUDE.md auto-load — it only reads its own AGENTS.md
+  // (native custom-instruction discovery owned by the CLI itself). FALSE
+  // here opts this runtime INTO the engine's CLAUDE.md-propagation layer
+  // (engine/claude-md-context.js) so repo-authored CLAUDE.md guidance is
+  // surfaced in the prompt. This is orthogonal to AGENTS.md discovery —
+  // CLAUDE.md carries no split-brain risk because Copilot never reads it itself.
+  claudeMdNativeDiscovery: false,
   // No --fallback-model
   fallbackModel: false,
   // Copilot manages session state internally in ~/.copilot/session-state/

package/engine/shared.js

@@ -1037,8 +1037,16 @@ function validateDispatchTmpDir(dirPath) {
 
 function removeDispatchTmpDir(dirPath) {
   if (!validateDispatchTmpDir(dirPath)) return false;
-  try { fs.rmSync(dirPath, { recursive: true, force: true }); return true; }
-  catch { return false; }
+  try {
+    _retryFsOp(
+      () => fs.rmSync(dirPath, { recursive: true, force: true }),
+      `removeDispatchTmpDir(${dirPath})`
+    );
+    return true;
+  } catch (e) {
+    log('warn', `removeDispatchTmpDir failed after retries: ${e.message}`, { path: dirPath, error: e.code });
+    return false;
+  }
 }
 
 // Read a file using O_NOFOLLOW where the platform supports it. On Windows
@@ -1439,48 +1447,37 @@ function withFileLock(lockPath, fn, {
         const isLockRaceErr = err.code === 'EEXIST' ||
           (process.platform === 'win32' && err.code === 'EPERM');
         if (!isLockRaceErr) throw err;
-        // P-b7d4e8f2 — Stale-lock check combines mtime age with PID liveness:
-        //   1. If mtime <= LOCK_STALE_MS  → never reap (recently active).
-        //   2. If JSON-parsable {pid, ts}:
-        //      - dead PID                 → reap.
-        //      - alive PID, mtime <= 5×   → don't reap (legitimate slow holder).
-        //      - alive PID, mtime > 5×    → reap (last-resort guard against
-        //                                    stuck holders that never released).
-        //   3. Legacy / empty / non-JSON lockfile → mtime-only path (reap).
+        // PID-owned locks are safe to reap as soon as their owner is dead.
+        // Alive owners retain the 5× stale window; legacy/partial lockfiles
+        // without a readable PID retain the mtime-only stale window.
         try {
           const stat = fs.statSync(lockPath);
           const mtimeAge = Date.now() - stat.mtimeMs;
-          if (mtimeAge > LOCK_STALE_MS) {
-            let holderPid = null;
-            try {
-              const raw = fs.readFileSync(lockPath, 'utf8');
-              const parsed = JSON.parse(raw);
-              if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) {
-                holderPid = parsed.pid;
-              }
-            } catch { /* legacy/empty/corrupt lock → fall through to mtime-only */ }
-
-            let shouldReap;
-            if (holderPid !== null) {
-              shouldReap = !processUtils.isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5;
-            } else {
-              // Legacy empty/non-JSON lockfile: trust mtime alone
-              shouldReap = true;
+          let holderPid = null;
+          try {
+            const raw = fs.readFileSync(lockPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) {
+              holderPid = parsed.pid;
             }
+          } catch { /* legacy/empty/corrupt lock → mtime-only fallback */ }
 
-            if (shouldReap) {
-              try {
-                fs.unlinkSync(lockPath);
-              } catch (unlinkErr) {
-                // ENOENT: another process deleted the lock between stat and unlink — safe to retry.
-                // EPERM on Windows: file is in 'pending delete' state from a concurrent
-                // reaper — the OS will finalize the delete shortly; retry will succeed.
-                const tolerable = unlinkErr.code === 'ENOENT' ||
-                  (process.platform === 'win32' && unlinkErr.code === 'EPERM');
-                if (!tolerable) throw unlinkErr;
-              }
-              continue; // lock just removed — retry immediately
+          const shouldReap = holderPid !== null
+            ? !processUtils.isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5
+            : mtimeAge > LOCK_STALE_MS;
+
+          if (shouldReap) {
+            try {
+              fs.unlinkSync(lockPath);
+            } catch (unlinkErr) {
+              // ENOENT: another process deleted the lock between stat and unlink — safe to retry.
+              // EPERM on Windows: file is in 'pending delete' state from a concurrent
+              // reaper — the OS will finalize the delete shortly; retry will succeed.
+              const tolerable = unlinkErr.code === 'ENOENT' ||
+                (process.platform === 'win32' && unlinkErr.code === 'EPERM');
+              if (!tolerable) throw unlinkErr;
             }
+            continue; // lock just removed — retry immediately
           }
         } catch (staleErr) {
           // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed.
@@ -3120,9 +3117,8 @@ const ENGINE_DEFAULTS = {
   // description the validator will never accept (see stage-output
   // substitution bug above) got re-evaluated forever, once per tick,
   // invisible to the dashboard. Once the SAME (unchanged) description is
-  // rejected this many consecutive times, the WI is flipped to `failed`
-  // with FAILURE_CLASS.PRE_DISPATCH_EVAL_STUCK instead of being silently
-  // re-queued into review again.
+  // rejected this many consecutive times, the WI stays pending but is marked
+  // exhausted so discovery pauses until an operator edits it.
   preDispatchEvalMaxRejections: 5,
   completionNonceRequired: false, // P-d2a8f6c1 (agent trust boundary F8): when true, a missing `nonce` field in the completion JSON hard-fails the dispatch with failure_class:'completion-nonce-mismatch'. Default false for one release so older agents/runtime caches that haven't picked up the prompt change degrade with a warning instead of breaking. Mismatched nonces hard-fail regardless of this flag. See docs/completion-reports.md → "Trust boundary".
   autoApplyReviewVote: false, // Master gate for platform vote mutations; local verdicts remain informational when false.
@@ -3255,6 +3251,7 @@ const ENGINE_DEFAULTS = {
   maxMeetingPromptBytes: 16 * 1024, // cap meeting findings/debate context injected into prompts
   maxMeetingHumanNotesBytes: 2 * 1024, // cap human note bullet lists injected into meeting prompts
   maxPipelineMeetingContextBytes: 16 * 1024, // cap aggregated meeting/dependency context for pipeline plan generation
+  maxPipelineStageHandoffBytes: 32 * 1024, // cap current-run note content exposed through {{stages.<id>.handoff}}
   notesArchiveMaxFiles: 2000, // keep notes/archive bounded during periodic cleanup
   // ── Worktree pool (W-mp73ya3e000me6c5) ─────────────────────────────────────
   // Per-project warm pool: completed worktrees are parked detached at
@@ -3324,7 +3321,7 @@ const ENGINE_DEFAULTS = {
       'node', 'bun', 'npm', 'npx', 'pnpm', 'yarn',
       'python', 'python3', 'pip', 'pip3',
       'docker', 'podman',
-      'adb', 'emulator',
+      'adb', 'emulator', 'maestro',
       'gradle', 'gradlew', 'mvn',
       'pwsh', 'powershell', 'bash', 'sh',
       'curl', 'wget',
@@ -3629,6 +3626,28 @@ function resolveAgentBareMode(agent, engine) {
   return false;
 }
 
+// W-mrdon0pe000l045a — resolve whether repo-authored CLAUDE.md instructions
+// should be propagated into the prompt for runtimes that don't auto-discover
+// CLAUDE.md natively (Copilot/Codex). Precedence mirrors
+// `resolveLiveCheckoutAutoReset`:
+//   1. per-project boolean `project.propagateClaudeMdForNonClaudeRuntimes`
+//   2. fleet-wide boolean `engine.propagateClaudeMdForNonClaudeRuntimes`
+//   3. hardcoded default TRUE (additive, on by default)
+// Only an explicit boolean counts as "set" at either level — undefined/null/
+// string are treated as unset so the next tier (or the TRUE default) decides.
+// This gate is orthogonal to each runtime's native AGENTS.md / repo-instruction
+// discovery by design (see ENGINE_DEFAULTS.propagateClaudeMdForNonClaudeRuntimes).
+// Pure, no I/O.
+function resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine) {
+  if (project && typeof project === 'object' && typeof project.propagateClaudeMdForNonClaudeRuntimes === 'boolean') {
+    return project.propagateClaudeMdForNonClaudeRuntimes;
+  }
+  if (engine && typeof engine === 'object' && typeof engine.propagateClaudeMdForNonClaudeRuntimes === 'boolean') {
+    return engine.propagateClaudeMdForNonClaudeRuntimes;
+  }
+  return true;
+}
+
 // ─── Legacy ccModel → defaultModel Migration ─────────────────────────────────
 //
 // Pre-P-3b8e5f1d, `engine.ccModel` was the single fleet-wide model knob (it
@@ -4500,7 +4519,7 @@ const FAILURE_CLASS = {
   OUTPUT_TRUNCATED: 'output-truncated',   // P-8e4c2a17: the agent streamed more stdout than the engine's hard capture cap (engine.js AGENT_OUTPUT_CAP_BYTES, 1MB) BEFORE the terminal `result` event arrived. The result (session id, completion block, final text) lives at the END of the stream, so it fell outside the captured window and parseOutput found nothing — the dispatch would otherwise fail as an opaque UNKNOWN and retry to death. Surfaced loudly with an actionable message; non-retryable (mechanical retry just reproduces the overflow — the agent must reduce output volume or the task must be split).
   VERIFY_MISSING_PR: 'verify-missing-pr', // Verify completed without an attached or tracked PR.
   PROJECT_NOT_FOUND: 'project_not_found', // W-mqv2wsy30002e090: a work item's `project` field names a project that is not configured (resolveConfiguredProject / formatUnknownProjectError → `Project "<name>" not found. Known projects: …`). Stamped at discovery time so the dashboard PR-column renderer surfaces the red failReason snippet like other non-retryable failures instead of burying it in the Agent column. Non-retryable — operator must fix the WI's project field or configure the project.
-  PRE_DISPATCH_EVAL_STUCK: 'pre-dispatch-eval-stuck', // W-mrcrh5hj0017d22f: pre-dispatch-eval rejected the SAME (unchanged) description ENGINE_DEFAULTS.preDispatchEvalMaxRejections times in a row without the WI status ever leaving pending — previously this burned an LLM validation call every discovery tick forever with nothing surfaced to the dashboard (constant-bug-bash's file-fixes stage wedged 16+ consecutive rejections, one/minute, until a human manually cancelled it). Engine now flips the WI to failed with this class so the stalled item is visible and stops silently re-evaluating; non-retryable until the description changes.
+  PRE_DISPATCH_EVAL_STUCK: 'pre-dispatch-eval-stuck', // Legacy persisted classification normalized by migration 025. New exhausted evaluations remain pending with _preDispatchEval.exhausted so they are not counted as agent execution failures.
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 
@@ -8491,7 +8510,7 @@ module.exports = {
   ENGINE_DEFAULTS,
   resolvePollFlag, // P-c4d8e1a3 — granular per-poller flag resolution
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentUseWorkerPool, resolveAgentAcpPoolSize, resolveAgentModel, resolveCcModel,
-  resolveAgentMaxBudget, resolveAgentBareMode,
+  resolveAgentMaxBudget, resolveAgentBareMode, resolvePropagateClaudeMdForNonClaudeRuntimes,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   runtimeConfigWarnings,
   projectWorkSourceWarnings,

package/engine/supervisor.js

@@ -104,6 +104,8 @@ const SUPERVISOR_STALE_ENGINE_HEARTBEAT_MS = Number(process.env.MINIONS_SUPERVIS
 // 3 strikes ≈ 90s of continuous unresponsiveness before we act.
 const DASH_HEALTH_TIMEOUT_MS = Number(process.env.MINIONS_SUPERVISOR_DASH_HEALTH_TIMEOUT_MS) || 5000;
 const DASH_HEALTH_MAX_FAILS = Number(process.env.MINIONS_SUPERVISOR_DASH_HEALTH_FAILS) || 3;
+const REAP_WAIT_TIMEOUT_MS = Number(process.env.MINIONS_SUPERVISOR_REAP_TIMEOUT_MS) || 10000;
+const REAP_WAIT_POLL_MS = Number(process.env.MINIONS_SUPERVISOR_REAP_POLL_MS) || 100;
 const isWin = process.platform === 'win32';
 
 function safeReadJson(p) {
@@ -126,11 +128,27 @@ function isStopIntentSet() {
   return fs.existsSync(STOP_INTENT_PATH_FN());
 }
 
-function isPidAlive(pid) {
-  if (!pid) return false;
+function _readPosixProcessState(pid) {
+  const result = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], {
+    encoding: 'utf8',
+    timeout: 3000,
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (result.error || result.status !== 0) return null;
+  return String(result.stdout || '').trim();
+}
+
+function isPidAlive(pid, {
+  platform = process.platform,
+  kill = process.kill,
+  readPosixProcessState = _readPosixProcessState,
+} = {}) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
   try {
-    if (isWin) {
-      const out = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
+    if (platform === 'win32') {
+      const out = execSync(`tasklist /FI "PID eq ${n}" /NH`, {
         encoding: 'utf8', timeout: 3000, windowsHide: true,
       });
       // Word-boundary + image-name match (mirrors engine/restart-health.js) so a
@@ -138,12 +156,16 @@ function isPidAlive(pid) {
       // alive. Fall back to an inline regex if shared.js isn't loadable.
       const shared = _sharedOrNull();
       if (shared && typeof shared.tasklistOutputShowsPid === 'function') {
-        return shared.tasklistOutputShowsPid(out, pid, { imageName: 'node' });
+        return shared.tasklistOutputShowsPid(out, n, { imageName: 'node' });
       }
-      return new RegExp(`\\b${pid}\\b`).test(out) && out.toLowerCase().includes('node');
+      return new RegExp(`\\b${n}\\b`).test(out) && out.toLowerCase().includes('node');
     }
-    process.kill(pid, 0);
-    return true;
+    kill(n, 0);
+    // kill(0) also succeeds for Unix zombies. They cannot execute or retain
+    // runtime resources, and a synchronous reap wait prevents Node from
+    // processing SIGCHLD, so treating them as live deadlocks every respawn.
+    const state = readPosixProcessState(n);
+    return state === null || (state !== '' && !state.startsWith('Z'));
   } catch { return false; }
 }
 
@@ -305,14 +327,43 @@ function _killHard(pid) {
   } catch { /* already gone */ }
 }
 
+function _sleepSync(ms) {
+  if (!(ms > 0)) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function waitForPidsToExit(pids, {
+  timeoutMs = REAP_WAIT_TIMEOUT_MS,
+  pollMs = REAP_WAIT_POLL_MS,
+  isAlive = isPidAlive,
+  sleep = _sleepSync,
+} = {}) {
+  const unique = [...new Set((pids || []).map(Number).filter(pid => Number.isInteger(pid) && pid > 0))];
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  let remaining = unique.filter(isAlive);
+  while (remaining.length > 0 && Date.now() < deadline) {
+    sleep(Math.min(pollMs, Math.max(1, deadline - Date.now())));
+    remaining = remaining.filter(isAlive);
+  }
+  return { ok: remaining.length === 0, remaining };
+}
+
 // Kill every stray process running `scriptPath`, except this supervisor.
-// Returns the number reaped. No-op when MINIONS_SUPERVISOR_REAP=0.
-function reapStrayProcesses(scriptPath, label) {
+// Returns the number reaped. Throws instead of spawning a replacement when any
+// old process survives the bounded wait — binding a fallback port or starting a
+// second engine is worse than retrying on the next supervisor tick.
+function reapStrayProcesses(scriptPath, label, options = {}) {
   if (!REAP_ENABLED) return 0;
-  const pids = listNodePidsMatching(scriptPath).filter(p => p !== process.pid);
+  const listPids = options.listPids || listNodePidsMatching;
+  const kill = options.kill || _killHard;
+  const pids = listPids(scriptPath).filter(p => p !== process.pid);
   if (!pids.length) return 0;
   console.log(`[supervisor] Reaping ${pids.length} stray ${label} process(es) before respawn: ${pids.join(', ')}`);
-  for (const pid of pids) _killHard(pid);
+  for (const pid of pids) kill(pid);
+  const waited = waitForPidsToExit(pids, options);
+  if (!waited.ok) {
+    throw new Error(`Refusing to respawn ${label}: stale PID(s) still alive after ${options.timeoutMs || REAP_WAIT_TIMEOUT_MS}ms: ${waited.remaining.join(', ')}`);
+  }
   return pids.length;
 }
 
@@ -372,11 +423,15 @@ function spawnEngine() {
   return proc.pid;
 }
 
-function spawnDashboard() {
+function spawnDashboard(requestedPort = _resolveDashPort()) {
   const out = openAppendFd('dashboard-stdio.log');
   const err = openAppendFd('dashboard-stdio.log');
-  const env = { ...process.env, MINIONS_NO_AUTO_OPEN: '1' };
-  const proc = spawn(process.execPath, [..._sqliteSpawnFlags(), path.join(MINIONS_DIR, 'dashboard.js')], {
+  const env = {
+    ...process.env,
+    MINIONS_NO_AUTO_OPEN: '1',
+    MINIONS_REQUIRE_DASHBOARD_PORT: '1',
+  };
+  const proc = spawn(process.execPath, [..._sqliteSpawnFlags(), path.join(MINIONS_DIR, 'dashboard.js'), String(requestedPort)], {
     cwd: MINIONS_DIR,
     stdio: ['ignore', out, err],
     detached: true,
@@ -533,7 +588,7 @@ async function checkDashboard(now) {
     // Critically, for the frozen-but-listening case the reap also KILLS the wedged
     // process still holding the port so spawnDashboard() can bind it.
     reapStrayProcesses(path.join(MINIONS_DIR, 'dashboard.js'), 'dashboard');
-    const newPid = spawnDashboard();
+    const newPid = spawnDashboard(dashPort);
     _lastDashboardRespawnAt = now;
     _dashHealthFailStreak = 0;
     console.log(`[supervisor] Dashboard respawned (new PID: ${newPid})`);
@@ -647,6 +702,7 @@ module.exports = {
     listeningPidsForPort,
     listNodePidsMatching,
     reapStrayProcesses,
+    waitForPidsToExit,
     _cmdRunsScript,
     openAppendFd,
     checkEngine,

package/engine/timeout.js

@@ -23,6 +23,60 @@ const MINIONS_DIR = shared.MINIONS_DIR;
 // 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; }
+const _pendingBranchPreservations = new Set();
+
+function resolveDispatchBranchPath(item) {
+  if (item?.worktreePath) return item.worktreePath;
+  if (item?.originalRef && item.meta?.project?.localPath) return item.meta.project.localPath;
+  return null;
+}
+
+function preserveDispatchBranch(item, config) {
+  const branchPath = resolveDispatchBranchPath(item);
+  if (!branchPath || !item.meta?.branch) {
+    return Promise.resolve({ pushed: false, reason: 'invalid-worktree' });
+  }
+  const persistedProject = item.meta?.project || {};
+  const project = getProjects(config).find(p => p.name === persistedProject.name) || persistedProject;
+  if (!project.localPath) return Promise.resolve({ pushed: false, reason: 'invalid-project' });
+  return engine().pushCleanAheadBranch({
+    rootDir: project.localPath,
+    worktreePath: branchPath,
+    branchName: item.meta.branch,
+    mainBranch: shared.resolveMainBranch(project.localPath, project.mainBranch),
+    project,
+    gitOpts: { env: shared.gitEnv() },
+  });
+}
+
+async function _finalizeDeadDispatch(item, reason, failureClass, config, deps = {}) {
+  const preserveBranch = deps.preserveBranch || preserveDispatchBranch;
+  const restoreLiveCheckout = deps.restoreLiveCheckout ||
+    require('./live-checkout').maybeRestoreLiveCheckoutFromRecord;
+  const complete = deps.complete || dispatch().completeDispatch;
+
+  if (resolveDispatchBranchPath(item) && item.meta?.branch) {
+    try {
+      await preserveBranch(item, config);
+    } catch (err) {
+      log('warn', `Orphan branch preservation failed for ${item.id}: ${err.message}`);
+    }
+  }
+  if (item.originalRef && item.meta?.branch && item.meta?.project?.localPath) {
+    try {
+      await restoreLiveCheckout({
+        item,
+        isTerminalFailure: true,
+        resultLabel: 'orphaned',
+        log: (lvl, msg) => log(lvl, msg),
+        writeInboxAlert: dispatch().writeInboxAlert,
+      });
+    } catch (err) {
+      log('warn', 'live-checkout restore (orphan): ' + err.message);
+    }
+  }
+  complete(item.id, DISPATCH_RESULT.ERROR, reason, '', failureClass ? { failureClass } : {});
+}
 
 // Lazy require for dispatch module (also circular via engine)
 let _dispatch = null;
@@ -664,7 +718,27 @@ function checkTimeouts(config) {
   const deadItems = [];
   const legacyAnnotationClears = new Set();
 
-  function completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess) {
+  function completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess, preservationDone = false, expectedProcInfo = activeProcesses.get(item.id)) {
+    if (!preservationDone && resolveDispatchBranchPath(item) && item.meta?.branch) {
+      if (_pendingBranchPreservations.has(item.id)) return;
+      _pendingBranchPreservations.add(item.id);
+      preserveDispatchBranch(item, config)
+        .catch(err => log('warn', `Output-completion branch preservation failed for ${item.id}: ${err.message}`))
+        .then(() => completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess, true, expectedProcInfo))
+        .finally(() => _pendingBranchPreservations.delete(item.id));
+      return;
+    }
+    if (!(getDispatch().active || []).some(active => active.id === item.id)) return;
+    if (hasProcess) {
+      const currentProcInfo = activeProcesses.get(item.id);
+      if (currentProcInfo !== expectedProcInfo ||
+          currentProcInfo?._steeringAt ||
+          currentProcInfo?._steeringMessage ||
+          currentProcInfo?._steeringNoSession) {
+        log('info', `${item.id}: output-detected completion yielded to the close/steering owner after branch preservation`);
+        return;
+      }
+    }
     const isSuccess = processExitCode === 0;
     log('info', `Agent ${item.agent} (${item.id}) completed via output detection (exit code ${processExitCode}, ${isSuccess ? 'success' : 'error'})`);
 
@@ -956,22 +1030,18 @@ function checkTimeouts(config) {
 
   // Clean up dead items
   for (const { item, reason, failureClass } of deadItems) {
-    completeDispatch(item.id, DISPATCH_RESULT.ERROR, reason, '', failureClass ? { failureClass } : {});
-    // PL-live-checkout-reliability-hardening — a live-mode dispatch declared an
-    // orphan (lost process handle, e.g. across an engine restart) leaves the
-    // operator checkout on the agent branch. Restore it from the persisted
-    // record (originalRef present ⇒ live mode). Always a terminal failure here.
-    if (item.originalRef && item.meta?.branch && item.meta?.project?.localPath) {
-      try {
-        require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
-          item,
-          isTerminalFailure: true,
-          resultLabel: 'orphaned',
-          log: (lvl, msg) => log(lvl, msg),
-          writeInboxAlert: dispatch().writeInboxAlert,
-        }).catch(() => {});
-      } catch (e) { log('warn', 'live-checkout restore (orphan): ' + e.message); }
+    // #853 — stale orphans have no process close event, so preserve their
+    // clean committed branch explicitly before completeDispatch makes the
+    // worktree eligible for teardown/quarantine.
+    if (resolveDispatchBranchPath(item) && item.meta?.branch) {
+      if (_pendingBranchPreservations.has(item.id)) continue;
+      _pendingBranchPreservations.add(item.id);
+      _finalizeDeadDispatch(item, reason, failureClass, config, { complete: completeDispatch })
+        .catch(err => log('warn', `Orphan cleanup failed for ${item.id}: ${err.message}`))
+        .finally(() => _pendingBranchPreservations.delete(item.id));
+      continue;
     }
+    completeDispatch(item.id, DISPATCH_RESULT.ERROR, reason, '', failureClass ? { failureClass } : {});
   }
 
   // Clear legacy blocking-tool annotations; process liveness no longer depends on tool parsing.
@@ -1055,4 +1125,5 @@ module.exports = {
   // exported for testing — steering clamp helpers and deferred checkpoint
   _clampSteeringDeferredMaxMs, _clampSteeringMaxKillRetries, _appendLiveOutputLine, deferSteeringUntilCheckpoint,
   killTrackedProcess, _escalatePlatformKill, // exported for testing — P-6e2a4c15 cancel-vs-kill
+  _finalizeDeadDispatch, // exported for testing
 };

package/engine/untrusted-fence.js

@@ -113,7 +113,8 @@ function buildSource(kind, parts) {
   }
 
   if (k === 'pinned-note' || k === 'team-notes' || k === 'agent-memory'
-   || k === 'wi-reference' || k === 'doc-content' || k === 'doc-selection') {
+   || k === 'wi-reference' || k === 'doc-content' || k === 'doc-selection'
+   || k === 'project-instructions') {
     return parts.path ? `${k}:${get('path')}` : k;
   }
   if (k === 'inbox') {