@yemi33/minions 0.1.2381 → 0.1.2383

package/engine/spawn-agent.js

@@ -32,12 +32,18 @@
  */
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const { runFile, cleanChildEnv, killGracefully, killImmediate, killByPidsImmediate, listProcessDescendants, ts, readFileNoFollow } = require('./shared');
-const { resolveRuntime } = require('./runtimes');
+const {
+  resolveRuntime,
+  RUNTIME_OPTIONS_FLAG,
+  RUNTIME_IMAGES_FILE_OPTION,
+  decodeRuntimeOptions,
+  prepareWorkspace: prepareRuntimeWorkspace,
+} = require('./runtimes');
 const { acquireAdoTokenSync, isLikelyAdoToken } = require('./ado-token');
 const keepProcessSweep = require('./keep-process-sweep');
+const MAX_RUNTIME_IMAGES_FILE_BYTES = 32 * 1024 * 1024;
 
 // ─── Pure helpers (exported for tests) ──────────────────────────────────────
 
@@ -76,17 +82,7 @@ function parseSpawnArgs(argv) {
       case '--disable-builtin-mcps':       opts.disableBuiltinMcps = true; break;
       case '--no-custom-instructions':     opts.suppressAgentsMd = true; break;
       case '--enable-reasoning-summaries': opts.reasoningSummaries = true; break;
-      case '--project-harness-dir': {
-        const v = peek();
-        if (typeof v === 'string' && v) projectHarnessDirs.push(v);
-        break;
-      }
-      // P-49e1c8b7 — hermetic harness opt-out. When set, computeAddDirs in
-      // main() returns [minionsDir] only (user-scope asset dirs from
-      // runtime.getUserAssetDirs AND any forwarded --project-harness-dir
-      // entries are dropped). Engine.js gates this flag via
-      // shared.resolveAgentHermeticHarness(agent, engine).
-      case '--hermetic-harness':           hermetic = true; break;
+      case RUNTIME_OPTIONS_FLAG:           Object.assign(opts, decodeRuntimeOptions(peek())); break;
       // LEGACY: dropped — the runtime adapter emits its own permission flag.
       // Pre-P-2a6d9c4f engine.js still passes `--permission-mode bypassPermissions`;
       // letting it through would duplicate the permission flag for Claude.
@@ -168,6 +164,41 @@ function injectAdoTokenEnvForRepoHost(env, opts) {
   return injectAdoTokenEnv(env, opts);
 }
 
+function hydrateRuntimeOptionFiles(opts, {
+  promptFile,
+  readFile = readFileNoFollow,
+  lstatSync = fs.lstatSync,
+  unlinkSync = fs.unlinkSync,
+} = {}) {
+  const imagesFile = opts?.[RUNTIME_IMAGES_FILE_OPTION];
+  if (!imagesFile) return opts;
+  if (typeof imagesFile !== 'string' || !promptFile) {
+    throw new Error('Invalid runtime images sidecar path');
+  }
+  const resolvedFile = path.resolve(imagesFile);
+  const optionsDir = path.resolve(path.dirname(promptFile));
+  if (path.dirname(resolvedFile) !== optionsDir) {
+    throw new Error('Runtime images sidecar must be beside the prompt file');
+  }
+  const stat = lstatSync(resolvedFile);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_RUNTIME_IMAGES_FILE_BYTES) {
+    throw new Error('Invalid runtime images sidecar file');
+  }
+  let images;
+  try {
+    images = JSON.parse(readFile(resolvedFile, 'utf8'));
+  } catch (err) {
+    throw new Error(`Invalid runtime images sidecar payload: ${err.message}`);
+  }
+  if (!Array.isArray(images)) {
+    throw new Error('Invalid runtime images sidecar payload: expected an array');
+  }
+  opts.images = images;
+  delete opts[RUNTIME_IMAGES_FILE_OPTION];
+  try { unlinkSync(resolvedFile); } catch {}
+  return opts;
+}
+
 function formatProcessExitSentinel(exitCode, signal) {
   return `\n[process-exit] code=${exitCode}${signal ? ` signal=${signal}` : ''}\n`;
 }
@@ -307,105 +338,16 @@ function createParentPipeForwarder(stream, outputPath, prefix = '') {
 }
 
 /**
- * P-7d31a06b — Pre-approve a worktree's `.mcp.json` servers in `~/.claude.json`
- * so Claude Code's first invocation in a fresh worktree cwd doesn't show the
- * project-scoped "trust this MCP server?" prompt (which `--dangerously-skip-permissions`
- * silently suppresses → the agent runs without the workspace MCPs).
- *
- * Writes to `projects[worktreePath].enabledMcpjsonServers` (the field Claude
- * Code actually reads — confirmed against the live `~/.claude.json` schema:
- * `enabledMcpjsonServers` / `disabledMcpjsonServers` are siblings of
- * `mcpServers`, indexed by absolute project path). Notes on the PRD wording
- * "mcpServers.approved": that's the intent label; `enabledMcpjsonServers` is
- * the on-disk reality.
- *
- * Pure-ish: all I/O (fs reads, mutator) is injected for tests. Best-effort —
- * callers MUST swallow errors and never block dispatch on this.
- *
- * Returns `{ wrote: boolean, reason: string, servers: string[] }`:
- *   - reason ∈ { 'ok', 'flag-off', 'not-claude', 'no-worktree',
- *                'no-workspace-mcp', 'invalid-workspace-mcp', 'no-servers' }
- *   - servers: keys discovered in the workspace `.mcp.json` (regardless of write)
- *
- * Args:
- *   runtimeName             — `runtime.name` from `resolveRuntime(...)`. Helper no-ops if !== 'claude'.
- *   worktreePath            — absolute path to the agent's cwd (the worktree). Used as both the file location
- *                             (`<worktreePath>/.mcp.json`) and the `projects[...]` key in `~/.claude.json`.
- *   homeDir                 — `os.homedir()`. Injected for test isolation; helper does NOT call os.homedir directly.
- *   engineConfig            — config.engine object; reads `claudePreApproveWorkspaceMcps` (default true via ENGINE_DEFAULTS).
- *   mutateJsonFileLocked    — injected file-locked mutator (engine/shared.js#mutateJsonFileLocked).
- *   existsSync, readFileSync — injectable fs primitives (default to node:fs).
+ * Backward-compatible wrapper for the old helper name. Runtime-owned workspace
+ * preparation now lives behind the adapter contract; the spawn wrapper does
+ * not know which harness needs which config file mutation.
  */
-function preApproveWorkspaceMcps({
-  runtimeName,
-  worktreePath,
-  homeDir,
-  engineConfig,
-  mutateJsonFileLocked,
-  existsSync = fs.existsSync,
-  readFileSync = fs.readFileSync,
-} = {}) {
-  if (engineConfig && engineConfig.claudePreApproveWorkspaceMcps === false) {
-    return { wrote: false, reason: 'flag-off', servers: [] };
-  }
-  if (runtimeName !== 'claude') {
-    return { wrote: false, reason: 'not-claude', servers: [] };
-  }
-  if (!worktreePath || typeof worktreePath !== 'string') {
-    return { wrote: false, reason: 'no-worktree', servers: [] };
+function preApproveWorkspaceMcps({ runtimeName, ...context } = {}) {
+  const result = prepareRuntimeWorkspace(resolveRuntime(runtimeName), context);
+  if (result?.reason === 'unsupported-runtime') {
+    return { ...result, reason: 'not-claude' };
   }
-  const workspaceMcpPath = path.join(worktreePath, '.mcp.json');
-  if (!existsSync(workspaceMcpPath)) {
-    return { wrote: false, reason: 'no-workspace-mcp', servers: [] };
-  }
-  let workspaceMcp;
-  try {
-    workspaceMcp = JSON.parse(readFileSync(workspaceMcpPath, 'utf8'));
-  } catch {
-    return { wrote: false, reason: 'invalid-workspace-mcp', servers: [] };
-  }
-  const serversObj = workspaceMcp && typeof workspaceMcp === 'object' ? workspaceMcp.mcpServers : null;
-  const servers = serversObj && typeof serversObj === 'object' && !Array.isArray(serversObj)
-    ? Object.keys(serversObj).filter((k) => typeof k === 'string' && k.length > 0)
-    : [];
-  if (servers.length === 0) {
-    return { wrote: false, reason: 'no-servers', servers: [] };
-  }
-  if (!homeDir || typeof mutateJsonFileLocked !== 'function') {
-    return { wrote: false, reason: 'no-home-or-mutator', servers };
-  }
-  const claudeJsonPath = path.join(homeDir, '.claude.json');
-  let didWrite = false;
-  mutateJsonFileLocked(claudeJsonPath, (data) => {
-    const root = data && typeof data === 'object' ? data : {};
-    if (!root.projects || typeof root.projects !== 'object') root.projects = {};
-    const projectKey = worktreePath;
-    const proj = root.projects[projectKey] && typeof root.projects[projectKey] === 'object'
-      ? root.projects[projectKey]
-      : {};
-    // enabledMcpjsonServers is Claude's actual on-disk approval field
-    const enabled = Array.isArray(proj.enabledMcpjsonServers) ? proj.enabledMcpjsonServers.slice() : [];
-    const disabled = Array.isArray(proj.disabledMcpjsonServers) ? proj.disabledMcpjsonServers.slice() : [];
-    const enabledSet = new Set(enabled.filter((s) => typeof s === 'string'));
-    let mutated = false;
-    for (const name of servers) {
-      if (!enabledSet.has(name)) {
-        enabledSet.add(name);
-        mutated = true;
-      }
-    }
-    // If a server was previously explicitly disabled, lift the disabled mark when we
-    // re-approve it — otherwise Claude treats the disabled entry as authoritative.
-    const nextDisabled = disabled.filter((s) => typeof s === 'string' && !servers.includes(s));
-    if (nextDisabled.length !== disabled.length) mutated = true;
-    if (!mutated) return data;
-    proj.enabledMcpjsonServers = [...enabledSet];
-    proj.disabledMcpjsonServers = nextDisabled;
-    root.projects[projectKey] = proj;
-    didWrite = true;
-    return root;
-  }, { defaultValue: {}, skipWriteIfUnchanged: true });
-  return { wrote: didWrite, reason: 'ok', servers };
+  return result;
 }
 
 // ─── Main script execution ──────────────────────────────────────────────────
@@ -421,7 +363,13 @@ function _installHint(name, runtime) {
 }
 
 function main() {
-  const parsed = parseSpawnArgs(process.argv);
+  let parsed;
+  try {
+    parsed = parseSpawnArgs(process.argv);
+  } catch (err) {
+    console.error(`FATAL: ${err.message}`);
+    process.exit(78);
+  }
   if (!parsed) {
     console.error('Usage: node spawn-agent.js <prompt-file> <sysprompt-file> [--runtime <name>] [args...]');
     process.exit(1);
@@ -445,12 +393,18 @@ function main() {
   // (Windows non-junction reads don't follow symlinks the same way POSIX does).
   const promptText = readFileNoFollow(promptFile, 'utf8');
   const sysPromptText = readFileNoFollow(sysPromptFile, 'utf8');
+  try {
+    hydrateRuntimeOptionFiles(opts, { promptFile });
+  } catch (err) {
+    console.error(`FATAL: ${err.message}`);
+    process.exit(78);
+  }
 
   // Sys prompt tmp file — only when (a) NOT resuming and (b) the adapter
   // accepts a system prompt as a separate file. For runtimes that bake the
   // system prompt into the user prompt (e.g. Copilot), sysPromptText is
   // already merged inside `runtime.buildPrompt(prompt, sys)`.
-  const isResume = opts.sessionId != null;
+  const isResume = typeof opts.sessionId === 'string' && opts.sessionId.trim() !== '';
   const sysTmpPath = sysPromptFile + '.tmp';
   const wantsSystemPromptFile = typeof runtime.usesSystemPromptFile === 'function'
     ? runtime.usesSystemPromptFile({ isResume, opts })
@@ -714,6 +668,18 @@ function main() {
   });
 }
 
-module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, preApproveWorkspaceMcps, createParentPipeForwarder, assertStaleHeadOk };
+module.exports = {
+  parseSpawnArgs,
+  buildSpawnInvocation,
+  normalizeRuntimeExit,
+  shouldInjectAdoTokenEnv,
+  injectAdoTokenEnv,
+  injectAdoTokenEnvForRepoHost,
+  writeProcessExitSentinel,
+  preApproveWorkspaceMcps,
+  createParentPipeForwarder,
+  assertStaleHeadOk,
+  hydrateRuntimeOptionFiles, // exported for testing
+};
 
 if (require.main === module) main();

package/engine/spawn-phase-watchdog.js

@@ -36,6 +36,7 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
+const { resolveRuntime, isSpawnStartupEvent } = require('./runtimes');
 const { ENGINE_DEFAULTS, FAILURE_CLASS } = shared;
 const AGENTS_DIR = queries.AGENTS_DIR;
 const log = (level, msg) => shared.log ? shared.log(level, msg) : console.log(`[${level}] ${msg}`);
@@ -43,24 +44,6 @@ const log = (level, msg) => shared.log ? shared.log(level, msg) : console.log(`[
 // Lazy require to break circular dep with dispatch.js (which lazy-requires engine.js).
 function dispatch() { return require('./dispatch'); }
 
-// ── Per-runtime startup-only event filters ──────────────────────────────────
-//
-// Anything NOT in these sets is treated as "real task activity" and the
-// watchdog stands down. These match the runtimes/*.js KNOWN_EVENT_TYPES
-// startup section — keep in sync.
-
-const COPILOT_STARTUP_TYPES = new Set([
-  'session.mcp_server_status_changed',
-  'session.mcp_servers_loaded',
-  'session.skills_loaded',
-  'session.tools_updated',
-  'session.info',
-]);
-
-// Claude stream-json prints {"type":"system","subtype":"init|hook_started|hook_response"}
-// during startup before any assistant/user/tool_use/result events fire.
-const CLAUDE_STARTUP_SUBTYPES = new Set(['init', 'hook_started', 'hook_response']);
-
 // Header line that engine.js writes at spawn: "[<iso>] pid: <n>"
 const HEADER_LINE_RE = /^\[[^\]]+\]\s+(?:pid:|spawn-failed)/;
 
@@ -79,6 +62,12 @@ const HEADER_LINE_RE = /^\[[^\]]+\]\s+(?:pid:|spawn-failed)/;
  */
 function hasRealTaskActivity(tailText, runtimeName) {
   if (!tailText) return false;
+  let runtime;
+  try {
+    runtime = resolveRuntime(runtimeName);
+  } catch {
+    return true;
+  }
   const lines = String(tailText).split(/\r?\n/);
   for (const rawLine of lines) {
     const line = rawLine.trim();
@@ -100,23 +89,7 @@ function hasRealTaskActivity(tailText, runtimeName) {
       // Object with no `type` — unusual; treat as activity to stay safe.
       return true;
     }
-    if (runtimeName === 'copilot') {
-      if (COPILOT_STARTUP_TYPES.has(type)) continue;
-      // Anything else from Copilot is real (assistant.*, tool.*, result,
-      // session.task_complete, user.message, function).
-      return true;
-    }
-    if (runtimeName === 'claude' || !runtimeName) {
-      // Claude stream-json: only {type:'system', subtype:'init|hook_*'} is startup.
-      if (type === 'system') {
-        const sub = typeof evt.subtype === 'string' ? evt.subtype : '';
-        if (CLAUDE_STARTUP_SUBTYPES.has(sub)) continue;
-        // Other `system` subtypes (e.g. errors, banners) — treat as activity.
-        return true;
-      }
-      return true;
-    }
-    // Unknown runtime — be conservative.
+    if (isSpawnStartupEvent(runtime, evt)) continue;
     return true;
   }
   return false;
@@ -266,6 +239,4 @@ function _defaultTailReader(filePath) {
 module.exports = {
   checkSpawnPhaseStalls,
   hasRealTaskActivity, // exported for testing
-  COPILOT_STARTUP_TYPES, // exported for testing
-  CLAUDE_STARTUP_SUBTYPES, // exported for testing
 };

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') {