@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/timeout.js

@@ -23,7 +23,6 @@ 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, config) {
   if (item?.worktreePath) return item.worktreePath;
@@ -51,11 +50,52 @@ function preserveDispatchBranch(item, config) {
   });
 }
 
+function resolveDispatchProject(item, config) {
+  const persistedProject = item?.meta?.project || {};
+  return getProjects(config).find(project => project.name === persistedProject.name) || persistedProject;
+}
+
+function getWorktreeProcessAnchorReason(item, managedSpawnSpawnedCount = 0) {
+  if (!item?.worktreePath) return null;
+  const decision = require('./worktree-gc').shouldGcDispatchWorktree({
+    worktreePath: item.worktreePath,
+    agentId: item.agent,
+    managedSpawnSpawnedCount,
+    isPoolMember: () => false,
+  });
+  return decision.reason === 'keep-processes-anchored' || decision.reason === 'managed-spawn-anchored'
+    ? decision.reason
+    : null;
+}
+
+function gcRecoveredDispatchWorktree(item, project, config) {
+  if (!item?.worktreePath || !project?.localPath) return;
+  const worktreeRoot = path.resolve(
+    project.localPath,
+    config.engine?.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot,
+  );
+  require('./worktree-gc').gcDispatchWorktreeIfOrphan({
+    worktreePath: item.worktreePath,
+    gitRoot: project.localPath,
+    worktreeRoot,
+    agentId: item.agent,
+    excludeDispatchId: item.id,
+    log,
+  });
+}
+
 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;
+  const deferredTerminal = item?._worktreeProtectionDeferred?.terminal || {};
+  const terminalReason = deferredTerminal.reason || reason;
+  const terminalResultSummary = deferredTerminal.resultSummary || '';
+  const terminalCompleteOpts = deferredTerminal.completeOpts
+    && typeof deferredTerminal.completeOpts === 'object'
+    ? deferredTerminal.completeOpts
+    : (failureClass ? { failureClass } : {});
 
   if (resolveDispatchBranchPath(item, config) && item.meta?.branch) {
     try {
@@ -64,6 +104,43 @@ async function _finalizeDeadDispatch(item, reason, failureClass, config, deps =
       log('warn', `Orphan branch preservation failed for ${item.id}: ${err.message}`);
     }
   }
+  const project = resolveDispatchProject(item, config);
+  const anchorReason = getWorktreeProcessAnchorReason(item);
+  let protection = {
+    allowRemoval: !anchorReason,
+    preserved: false,
+    reason: anchorReason || 'not-checked',
+  };
+  if (item.worktreePath && item.meta?.branch && project.localPath) {
+    protection = await engine()._preserveFailedDispatchWorktree({
+      effectiveResult: DISPATCH_RESULT.ERROR,
+      rootDir: project.localPath,
+      worktreePath: item.worktreePath,
+      branchName: item.meta.branch,
+      dispatchId: item.id,
+      mainBranch: shared.resolveMainBranch(project.localPath, project.mainBranch),
+      project,
+      gitOpts: { env: shared.gitEnv() },
+      failureReason: terminalReason,
+      retainWorktree: !!anchorReason,
+    });
+  }
+  if (protection.terminalizationSafe === false) {
+    try {
+      dispatch().deferDispatchForWorktreeProtection(item.id, protection, {
+        reason: terminalReason,
+        resultSummary: terminalResultSummary,
+        completeOpts: terminalCompleteOpts,
+      });
+    } catch (deferErr) {
+      log('error', `Orphan cleanup could not persist deferred worktree protection for ${item.id}: ${deferErr.message}`);
+    }
+    log('error', `Orphan cleanup deferred terminalization for ${item.id}: ${protection.reason}`);
+    return { deferred: true, protection };
+  }
+  if (protection.allowRemoval !== false) {
+    gcRecoveredDispatchWorktree(item, project, config);
+  }
   if (shared.isLiveCheckoutDispatchRecord(item, config)) {
     try {
       await restoreLiveCheckout({
@@ -78,7 +155,8 @@ async function _finalizeDeadDispatch(item, reason, failureClass, config, deps =
       log('warn', 'live-checkout restore (orphan): ' + err.message);
     }
   }
-  complete(item.id, DISPATCH_RESULT.ERROR, reason, '', failureClass ? { failureClass } : {});
+  complete(item.id, DISPATCH_RESULT.ERROR, terminalReason, terminalResultSummary, terminalCompleteOpts);
+  return { deferred: false, protection };
 }
 
 // Lazy require for dispatch module (also circular via engine)
@@ -636,6 +714,35 @@ function readFileTail(filePath, maxBytes) {
   }
 }
 
+// W-ms0vk9nv000z985b — read the live-output tail for a dispatch without
+// throwing when the log is missing/unreadable. Mirrors the 64KB window the
+// process-exit sentinel scan uses.
+function liveLogTailForItem(liveLogPath) {
+  try { return readFileTail(liveLogPath, 65536); } catch { return ''; }
+}
+
+// W-ms0vk9nv000z985b — is there durable, trusted evidence that this dispatch
+// already produced a completion report?
+//
+// Returns the parsed report only when it passes the SAME trust boundary the
+// normal close path applies: valid shape + recognized status, and a nonce that
+// matches the value minted for this spawn (carried across steering resumes).
+// A report with a missing/mismatched nonce is untrusted and returns null, so a
+// forged sidecar can never suppress a genuine timeout.
+function readAcceptedCompletionReport(item, procInfo) {
+  const expectedNonce = procInfo?._completionNonce || null;
+  if (!expectedNonce) return null;
+  try {
+    const report = require('./lifecycle').parseCompletionReportFile(item);
+    if (!report) return null;
+    if (typeof report.nonce !== 'string' || report.nonce !== expectedNonce) return null;
+    return report;
+  } catch (e) {
+    log('warn', `resume-stall completion-report probe failed for ${item?.id}: ${e.message}`);
+    return null;
+  }
+}
+
 function parseProcessExitCode(logText) {
   if (!logText) return null;
   const exitPattern = /(?:^|\n)\[process-exit\]\s+(?:code=)?(-?\d+|spawn-failed)(?=\s|$)/g;
@@ -683,15 +790,7 @@ function checkTimeouts(config) {
   const engineRestartGraceUntil = engine().engineRestartGraceUntil;
   const engineRestartGraceExempt = engine().engineRestartGraceExempt;
   const { completeDispatch } = dispatch();
-  // P-a7b2c1d9: fenced ```completion stdout parser (formerly destructured here)
-  // deliberately dropped from this destructure. The recovery path uses the
-  // sidecar (parseCompletionReportFile) as the sole structured-completion
-  // source. The stdout parser added no new signal on the timeout/exit-recovery
-  // path — only a disagreement risk between the sidecar and the stdout block.
-  // Removing this caller unblocks the completion-fallback-parsers deprecation
-  // sweep window in docs/deprecated.json (its `counter==0 ⇒ parser unused`
-  // claim is now logically sound).
-  const { runPostCompletionHooks, parseAgentOutput, parseCompletionReportFile, detectNonTerminalResultSummary } = require('./lifecycle');
+  const { runPostCompletionHooks } = require('./lifecycle');
 
   const timeout = config.engine?.agentTimeout || ENGINE_DEFAULTS.agentTimeout;
   const defaultStaleOrphanTimeout = config.engine?.heartbeatTimeout || ENGINE_DEFAULTS.heartbeatTimeout;
@@ -720,99 +819,249 @@ function checkTimeouts(config) {
   const dispatchData = getDispatch();
   const deadItems = [];
   const legacyAnnotationClears = new Set();
-
-  function completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess, preservationDone = false, expectedProcInfo = activeProcesses.get(item.id)) {
-    if (!preservationDone && resolveDispatchBranchPath(item, config) && 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;
+  const finalizationPromises = [];
+
+  function completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess, expectedProcInfo = activeProcesses.get(item.id)) {
+    if (hasProcess && (
+      expectedProcInfo?._steeringAt
+      || expectedProcInfo?._steeringMessage
+      || expectedProcInfo?._steeringNoSession
+    )) {
+      return null;
     }
-    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 finalizationOwner = 'timeout-output';
+    if (!shared.claimDispatchFinalization(item.id, finalizationOwner)) return;
+
+    const finalizationPromise = Promise.resolve().then(async () => {
+      if (resolveDispatchBranchPath(item, config) && item.meta?.branch) {
+        try {
+          await preserveDispatchBranch(item, config);
+        } catch (err) {
+          log('warn', `Output-completion branch preservation failed for ${item.id}: ${err.message}`);
+        }
       }
-    }
-    const isSuccess = processExitCode === 0;
-    log('info', `Agent ${item.agent} (${item.id}) completed via output detection (exit code ${processExitCode}, ${isSuccess ? 'success' : 'error'})`);
 
-    // Extract output text for the output.log — read full file for complete parsing
-    const outputLogPath = path.join(AGENTS_DIR, item.agent, 'output.log');
-    try {
-      const fullLog = safeRead(liveLogPath) || detectedLogText;
-      const { text } = shared.parseStreamJsonOutput(fullLog);
-      safeWrite(outputLogPath, `# Output for dispatch ${item.id}\n# Exit code: ${processExitCode}\n# Completed: ${ts()}\n# Detected via output scan\n\n## Result\n${text || '(no text)'}\n`);
-    } catch (e) { log('warn', 'parse output result: ' + e.message); }
-
-    const fullLogForHooks = safeRead(liveLogPath) || detectedLogText;
-    let completionDetection = null;
-    let outputResultSummary = '';
-    try {
-      const runtimeName = item.meta?.runtimeName || item.runtimeName || 'claude';
-      outputResultSummary = parseAgentOutput(fullLogForHooks, runtimeName).resultSummary || '';
-      const gateSummary = outputResultSummary || (!fullLogForHooks.includes('"type":') ? fullLogForHooks : '');
-      // P-a7b2c1d9: pass `null` for structuredCompletion. By the time
-      // checkTimeouts runs, the sidecar `completion.json` (parseCompletionReportFile)
-      // is the documented source of truth; the fenced ```completion stdout
-      // parser is intentionally bypassed here.
-      completionDetection = isSuccess
-        ? detectNonTerminalResultSummary(gateSummary, null, parseCompletionReportFile(item), { detectPhantom: true })
-        : null;
-    } catch (e) { log('warn', 'completion summary gate: ' + e.message); }
-
-    const _completedAsError = completionDetection || !isSuccess;
-    completeDispatch(item.id, completionDetection ? DISPATCH_RESULT.ERROR : (isSuccess ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR),
-      completionDetection ? completionDetection.reason : (isSuccess ? 'Completed (detected from output)' : `Exited with code ${processExitCode} (detected from output)`),
-      outputResultSummary,
-      completionDetection ? { processWorkItemFailure: false } : {});
-
-    // PL-live-checkout-reliability-hardening — restore the operator's checkout
-    // for a live-mode dispatch that finished AFTER an engine restart. This path
-    // (output-detected completion of a re-attached process) has no in-memory
-    // onAgentClose closure, so without this the tree is stranded on the agent
-    // branch. Explicit dispatch provenance plus current config are the live-mode
-    // signal; worktree-mode records fail closed.
-    if (shared.isLiveCheckoutDispatchRecord(item, config)) {
+      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 fullLogForHooks = safeRead(liveLogPath) || detectedLogText;
+      const outputLogPath = path.join(AGENTS_DIR, item.agent, 'output.log');
       try {
-        require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
-          item,
-          config,
-          isTerminalFailure: _completedAsError,
-          resultLabel: _completedAsError ? 'error' : 'success',
-          log: (lvl, msg) => log(lvl, msg),
-          writeInboxAlert: dispatch().writeInboxAlert,
-        }).catch(() => {});
-      } catch (e) { log('warn', 'live-checkout restore (output completion): ' + e.message); }
-    }
+        const { text } = shared.parseStreamJsonOutput(fullLogForHooks);
+        safeWrite(outputLogPath, `# Output for dispatch ${item.id}\n# Exit code: ${processExitCode}\n# Completed: ${ts()}\n# Detected via output scan\n\n## Result\n${text || '(no text)'}\n`);
+      } catch (e) { log('warn', 'parse output result: ' + e.message); }
+
+      const expectedNonce = expectedProcInfo?._completionNonce || null;
+      const completionNonceRequired = config?.engine?.completionNonceRequired ?? ENGINE_DEFAULTS.completionNonceRequired;
+      const type = item.type || item.workType || item.meta?.item?.type;
+      const wiMeta = item.meta?.item?.meta || {};
+      const keepProcessesRequested = !!item.meta?.keep_processes || !!wiMeta.keep_processes;
+      const managedSpawnRequested = !!item.meta?.managed_spawn || !!wiMeta.managed_spawn;
+      const preFinalizationFailure = keepProcessesRequested || managedSpawnRequested
+        ? {
+            reason: 'Output recovery cannot safely evaluate keep_processes/managed_spawn acceptance; retrying through the normal close path on the next attempt',
+          }
+        : null;
+      if (managedSpawnRequested) {
+        const staleManagedSidecar = path.join(AGENTS_DIR, item.agent, 'managed-spawn.json');
+        try { fs.unlinkSync(staleManagedSidecar); } catch (e) {
+          if (e.code !== 'ENOENT') log('warn', `Output recovery could not discard stale managed-spawn sidecar for ${item.id}: ${e.message}`);
+        }
+      }
+      const hookResult = await runPostCompletionHooks(
+        item,
+        item.agent,
+        processExitCode,
+        fullLogForHooks,
+        config,
+        {
+          detectPhantom: true,
+          expectedNonce,
+          completionNonceRequired,
+          completionReportRequired: !shared.READ_ONLY_ROOT_TASK_TYPES.has(type),
+          deferWorktreeRemoval: true,
+          preFinalizationFailure,
+        },
+      ) || {};
+
+      if (!(getDispatch().active || []).some(active => active.id === item.id)) return;
+      if (hasProcess && activeProcesses.get(item.id) !== expectedProcInfo) {
+        log('info', `${item.id}: output-detected completion yielded to the close owner after lifecycle validation`);
+        return;
+      }
 
-    // Run post-completion hooks via shared helper (async — fire and forget in timeout context).
-    // Pass the actual exit code so autoRecovery (PR-created-but-failed) still works correctly.
-    // detectPhantom: true mirrors the line 310 detectNonTerminalResultSummary call —
-    // when the timeout path completes a dispatch via the [process-exit] sentinel,
-    // we have no guarantee the runtime emitted a result event. Propagating
-    // detectPhantom downstream lets enforcePrAttachmentContract route phantom
-    // hard-fails through the _phantomRetryCount budget instead of bypassing
-    // the retry counter entirely (P-d9a3e6f4).
-    // P-d2a8f6c1: hand the per-spawn nonce to lifecycle for trust-boundary
-    // validation. Read it from activeProcesses before the hasProcess branch
-    // below deletes the entry.
-    const expectedNonce = activeProcesses.get(item.id)?._completionNonce || null;
-    const completionNonceRequired = config?.engine?.completionNonceRequired ?? ENGINE_DEFAULTS.completionNonceRequired;
-    runPostCompletionHooks(item, item.agent, processExitCode, fullLogForHooks, config, { detectPhantom: true, expectedNonce, completionNonceRequired }).catch(e => log('warn', 'post-completion hooks: ' + e.message));
-
-    if (hasProcess) {
-      killTrackedProcess(activeProcesses.get(item.id));
-      activeProcesses.delete(item.id);
-    }
+      const {
+        resultSummary = '',
+        autoRecovered = false,
+        trustedCompletionSuccess = false,
+        completionContractFailure = null,
+        completionReportFailure = null,
+        preFinalizationFailure: lifecyclePreFinalizationFailure = null,
+        structuredCompletion = null,
+        agentReportedFailure = false,
+        agentRetryable,
+        nonceMismatch = null,
+        benignNoop = false,
+      } = hookResult;
+      const hardContractFail = completionContractFailure?.severity === 'hard'
+        || completionContractFailure?.nonTerminal === true;
+      const nonceFail = nonceMismatch?.severity === 'hard';
+      const completionReportFail = !!completionReportFailure;
+      const preFinalizationFail = !!lifecyclePreFinalizationFailure;
+      const effectiveResult = shared.resolveTerminalDispatchResult({
+        code: processExitCode,
+        agentReportedFailure,
+        autoRecovered,
+        benignNoop,
+        trustedCompletionSuccess,
+        hardContractFail,
+        nonceFail,
+        completionReportFail,
+        managedSpawnAcceptanceFail: preFinalizationFail,
+      });
+
+      let reason = '';
+      if (nonceFail) {
+        reason = nonceMismatch.reason || 'completion nonce mismatch';
+      } else if (hardContractFail) {
+        reason = completionContractFailure.reason || 'completion contract failed';
+      } else if (completionReportFail) {
+        reason = completionReportFailure.reason;
+      } else if (preFinalizationFail) {
+        reason = lifecyclePreFinalizationFailure.reason;
+      } else if (agentReportedFailure) {
+        reason = String(
+          structuredCompletion?.summary
+          || structuredCompletion?.failure_class
+          || 'Agent reported failure',
+        ).slice(0, 300);
+      } else if (effectiveResult === DISPATCH_RESULT.ERROR) {
+        reason = `Exited with code ${processExitCode} (detected from output)`;
+      } else {
+        reason = 'Completed (detected from output)';
+      }
+
+      const completionOpts = {
+        ...(structuredCompletion?._path ? { completionReportPath: structuredCompletion._path } : {}),
+        ...(structuredCompletion ? { structuredCompletion } : {}),
+      };
+      let completeOpts = completionOpts;
+      if (nonceFail) {
+        completeOpts = { ...completionOpts, failureClass: nonceMismatch.failureClass, agentRetryable: false };
+      } else if (completionReportFail) {
+        completeOpts = {
+          ...completionOpts,
+          failureClass: completionReportFailure.failureClass,
+          agentRetryable: true,
+          ...(hardContractFail ? { processWorkItemFailure: false } : {}),
+        };
+      } else if (preFinalizationFail) {
+        completeOpts = {
+          ...completionOpts,
+          agentRetryable: true,
+          ...(hardContractFail ? { processWorkItemFailure: false } : {}),
+        };
+      } else if (hardContractFail) {
+        completeOpts = { ...completionOpts, processWorkItemFailure: false };
+      } else if (effectiveResult === DISPATCH_RESULT.ERROR) {
+        completeOpts = {
+          ...completionOpts,
+          ...(typeof agentRetryable === 'boolean' ? { agentRetryable } : {}),
+          ...(structuredCompletion?.failure_class ? { failureClass: structuredCompletion.failure_class } : {}),
+        };
+      }
+
+      const project = resolveDispatchProject(item, config);
+      const persistedAnchorReason = getWorktreeProcessAnchorReason(item);
+      const worktreeAnchored = !!persistedAnchorReason;
+      let failedWorktreeProtection = {
+        allowRemoval: !worktreeAnchored,
+        preserved: false,
+        reason: persistedAnchorReason || 'not-checked',
+      };
+
+      if (
+        effectiveResult === DISPATCH_RESULT.ERROR
+        && item.worktreePath
+        && item.meta?.branch
+        && project.localPath
+      ) {
+        failedWorktreeProtection = await engine()._preserveFailedDispatchWorktree({
+          effectiveResult,
+          rootDir: project.localPath,
+          worktreePath: item.worktreePath,
+          branchName: item.meta.branch,
+          dispatchId: item.id,
+          mainBranch: shared.resolveMainBranch(project.localPath, project.mainBranch),
+          project,
+          gitOpts: { env: shared.gitEnv() },
+          failureReason: reason,
+          retainWorktree: worktreeAnchored,
+        });
+      }
+
+      if (failedWorktreeProtection.terminalizationSafe === false) {
+        try {
+          dispatch().deferDispatchForWorktreeProtection(item.id, failedWorktreeProtection, {
+            reason,
+            resultSummary,
+            completeOpts,
+          });
+        } catch (deferErr) {
+          log('error', `Output-completion could not persist deferred worktree protection for ${item.id}: ${deferErr.message}`);
+        }
+        dispatch().updateAgentStatus(item.id, AGENT_STATUS.FAILED,
+          'Completion deferred until failed worktree has durable recovery protection');
+        log('error', `Output-completion deferred terminalization for ${item.id}: ${failedWorktreeProtection.reason}`);
+        return;
+      }
+
+      if (failedWorktreeProtection.allowRemoval !== false) {
+        gcRecoveredDispatchWorktree(item, project, config);
+      }
+
+      const workerState = shared.resolveTerminalWorkerState({
+        code: processExitCode,
+        effectiveResult,
+        errorReason: reason,
+      });
+      dispatch().updateAgentStatus(item.id, workerState.status, workerState.detail);
+      log('info', `Agent ${item.agent} (${item.id}) completed via output detection (exit code ${processExitCode}, ${effectiveResult})`);
+      completeDispatch(item.id, effectiveResult, reason, resultSummary, completeOpts);
+
+      if (shared.isLiveCheckoutDispatchRecord(item, config)) {
+        try {
+          await require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
+            item,
+            config,
+            isTerminalFailure: effectiveResult === DISPATCH_RESULT.ERROR,
+            resultLabel: effectiveResult,
+            log: (lvl, msg) => log(lvl, msg),
+            writeInboxAlert: dispatch().writeInboxAlert,
+          });
+        } catch (e) { log('warn', 'live-checkout restore (output completion): ' + e.message); }
+      }
+
+      if (hasProcess) {
+        killTrackedProcess(activeProcesses.get(item.id));
+        activeProcesses.delete(item.id);
+      }
+    }).catch(err => {
+      log('warn', `Output-completion finalization failed for ${item.id}: ${err.message}`);
+    }).finally(() => {
+      shared.releaseDispatchFinalization(item.id, finalizationOwner);
+    });
+    finalizationPromises.push(finalizationPromise);
+    return finalizationPromise;
   }
 
   for (const item of (dispatchData.active || [])) {
@@ -839,6 +1088,22 @@ function checkTimeouts(config) {
     const silentMs = Date.now() - lastActivity;
     const silentSec = Math.round(silentMs / 1000);
 
+    const deferredProtection = item._worktreeProtectionDeferred;
+    if (deferredProtection && !processAlive) {
+      const anchorReason = getWorktreeProcessAnchorReason(item);
+      const retryAt = Date.parse(deferredProtection.retryAfter || '');
+      if (anchorReason || (Number.isFinite(retryAt) && Date.now() < retryAt)) continue;
+      const terminal = deferredProtection.terminal || {};
+      log('warn', `Retrying deferred failed-worktree preservation for ${item.id} after process anchor release`);
+      deadItems.push({
+        item,
+        reason: terminal.reason || 'Failed worktree lacks durable recovery protection',
+        failureClass: terminal.completeOpts?.failureClass,
+      });
+      activeProcesses.delete(item.id);
+      continue;
+    }
+
     // Check if the agent actually completed by looking for the [process-exit] sentinel.
     //
     // The sentinel is written synchronously by spawn-agent.js's proc.on('close') handler
@@ -918,6 +1183,38 @@ function checkTimeouts(config) {
         const resumeSilentMs = Date.now() - resumeHeartbeatAt;
         if (resumeSilentMs > runtimeResumeHeartbeatTimeout) {
           const resumeSilentSec = Math.round(resumeSilentMs / 1000);
+          // W-ms0vk9nv000z985b — durable evidence beats a stale heartbeat.
+          //
+          // The resume watchdog exists for one hypothesis: the resumed runtime
+          // is wedged and never came back to life. A nonce-valid completion
+          // report on disk falsifies that hypothesis outright — the agent ran,
+          // finished its work (pushed commits, opened/updated the PR) and
+          // recorded the outcome. Marking that dispatch TIMEOUT is a FALSE
+          // failure: it discards a real success, re-queues finished work and
+          // (for fix dispatches) re-runs against an already-resolved PR.
+          //
+          // The nonce is minted per spawn and carried across steering resumes,
+          // so a matching report provably came from THIS dispatch. Terminalize
+          // from the report through the same completeFromOutput path the
+          // process-exit sentinel uses — full lifecycle validation, PR
+          // attachment, and worktree protection all still apply, so a report
+          // claiming failure still fails. Nothing here weakens the report
+          // contract; it only stops a watchdog from overwriting it.
+          const acceptedReport = readAcceptedCompletionReport(item, procInfo);
+          if (acceptedReport) {
+            log('warn', `Runtime resume produced no output heartbeat for ${resumeSilentSec}s for ${item.agent} (${item.id}), but an accepted completion report is present (status=${acceptedReport.status}) — terminalizing from the report instead of timing out`);
+            try { fs.appendFileSync(liveLogPath, `\n[runtime-resume-completion] Resume heartbeat stalled after ${resumeSilentSec}s, but a valid completion report was found. Completing from the report instead of failing as a timeout.\n`); } catch { /* optional */ }
+            procInfo._runtimeResumeAwaitingFirstOutput = false;
+            // hasProcess=false: activeProcesses is torn down immediately below,
+            // so the owner-yield re-checks inside completeFromOutput must not
+            // race against our own cleanup. procInfo is still passed as the
+            // expected proc info so the per-spawn nonce is available to the
+            // lifecycle hooks.
+            completeFromOutput(item, liveLogPath, 0, liveLogTailForItem(liveLogPath), false, procInfo);
+            activeProcesses.delete(item.id);
+            killTrackedProcess(procInfo, { graceMs: 5000 });
+            continue;
+          }
           const reason = `Runtime resume stalled — no output heartbeat for ${resumeSilentSec}s`;
           log('warn', `Runtime resume stalled: ${item.agent} (${item.id}) — no output heartbeat for ${resumeSilentSec}s; killing and retrying fresh`);
           dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, reason);
@@ -1034,18 +1331,12 @@ function checkTimeouts(config) {
 
   // Clean up dead items
   for (const { item, reason, failureClass } of deadItems) {
-    // #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, config) && 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 } : {});
+    const finalizationOwner = 'timeout-orphan';
+    if (!shared.claimDispatchFinalization(item.id, finalizationOwner)) continue;
+    const finalizationPromise = _finalizeDeadDispatch(item, reason, failureClass, config, { complete: completeDispatch })
+      .catch(err => log('warn', `Orphan cleanup failed for ${item.id}: ${err.message}`))
+      .finally(() => shared.releaseDispatchFinalization(item.id, finalizationOwner));
+    finalizationPromises.push(finalizationPromise);
   }
 
   // Clear legacy blocking-tool annotations; process liveness no longer depends on tool parsing.
@@ -1111,6 +1402,7 @@ function checkTimeouts(config) {
       return items;
     }, { defaultValue: [], skipWriteIfUnchanged: true });
   }
+  return Promise.allSettled(finalizationPromises);
 }
 
 // ─── Exports ─────────────────────────────────────────────────────────────────
@@ -1123,6 +1415,7 @@ module.exports = {
   isOsPidAliveForDispatch,
   parseProcessExitCode, terminalResultIndicatesError, parseTerminalResultFallbackExitCode, // exported for testing
   readFileTail, runtimeSupportsMidRunSessionId, // exported for testing
+  readAcceptedCompletionReport, liveLogTailForItem, // exported for testing (W-ms0vk9nv000z985b)
   // exported for testing
   rememberDeferredSteering, checkDeferredStranded, _runSteeringKillLadder, _collectDescendantPids,
   _resetSteeringStoreCacheForTest, _setSteeringStoreForTest,