@yemi33/minions 0.1.2383 → 0.1.2384

package/engine/shared.js

@@ -920,6 +920,9 @@ function safeJsonNoRestore(p, defaultValue = null) {
  * avoid temp file name collisions.
  */
 let _tmpCounter = 0;
+const SAFE_WRITE_RENAME_ATTEMPTS = 20;
+const SAFE_WRITE_RENAME_RETRY_BASE_MS = 50;
+const SAFE_WRITE_RENAME_RETRY_MAX_MS = 250;
 
 function safeWrite(p, data) {
   const dir = path.dirname(p);
@@ -929,13 +932,16 @@ function safeWrite(p, data) {
   try {
     fs.writeFileSync(tmp, content);
     // Atomic rename — retry on Windows EPERM (file locking)
-    for (let attempt = 0; attempt < 5; attempt++) {
+    for (let attempt = 0; attempt < SAFE_WRITE_RENAME_ATTEMPTS; attempt++) {
       try {
         fs.renameSync(tmp, p);
         return;
       } catch (e) {
-        if (e.code === 'EPERM' && attempt < 4) {
-          const delay = 50 * (attempt + 1); // 50, 100, 150, 200ms
+        if (e.code === 'EPERM' && attempt < SAFE_WRITE_RENAME_ATTEMPTS - 1) {
+          const delay = Math.min(
+            SAFE_WRITE_RENAME_RETRY_BASE_MS * (attempt + 1),
+            SAFE_WRITE_RENAME_RETRY_MAX_MS
+          );
           sleepMs(delay);
           continue;
         }
@@ -946,7 +952,7 @@ function safeWrite(p, data) {
     }
     // All rename attempts exhausted without throw — should not happen, but clean up
     try { fs.unlinkSync(tmp); } catch { /* cleanup */ }
-    throw new Error(`[safeWrite] All 5 rename attempts failed for ${p}`);
+    throw new Error(`[safeWrite] All ${SAFE_WRITE_RENAME_ATTEMPTS} rename attempts failed for ${p}`);
   } catch (err) {
     // Clean up tmp if it still exists, then re-throw — never silently swallow
     try { fs.unlinkSync(tmp); } catch { /* cleanup */ }
@@ -1406,6 +1412,104 @@ function pruneCrashDiagnosticsReports(config) {
   return removed;
 }
 
+const FILE_LOCK_RELEASE_ATTEMPTS = 5;
+const FILE_LOCK_RELEASE_RETRY_DELAY_MS = 25;
+const FILE_LOCK_RETRY_MAX_DELAY_MS = 250;
+
+function _releaseFileLock(lockPath, fd) {
+  try { fs.closeSync(fd); } catch { /* continue to path cleanup */ }
+
+  const attempts = process.platform === 'win32' ? FILE_LOCK_RELEASE_ATTEMPTS : 1;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      fs.unlinkSync(lockPath);
+      return true;
+    } catch (err) {
+      if (err && err.code === 'ENOENT') return true;
+      const retryable = process.platform === 'win32'
+        && err && (err.code === 'EPERM' || err.code === 'EBUSY' || err.code === 'EACCES');
+      if (!retryable || attempt === attempts - 1) {
+        console.warn(`[withFileLock] Failed to release ${lockPath}: ${err?.message || err}`);
+        return false;
+      }
+      sleepMs(FILE_LOCK_RELEASE_RETRY_DELAY_MS * (attempt + 1));
+    }
+  }
+  return false;
+}
+
+function _isTransientFileLockPathError(err) {
+  return !!err && (err.code === 'ENOENT'
+    || (process.platform === 'win32' && err.code === 'EPERM'));
+}
+
+function _readFileLockState(lockPath) {
+  try {
+    const stat = fs.statSync(lockPath);
+    const raw = fs.readFileSync(lockPath, 'utf8');
+    let holderPid = null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) holderPid = parsed.pid;
+    } catch { /* legacy/empty/corrupt lock */ }
+    return { raw, holderPid, mtimeAge: Date.now() - stat.mtimeMs };
+  } catch (err) {
+    if (_isTransientFileLockPathError(err)) return null;
+    throw err;
+  }
+}
+
+function _readFileLockIdentity(lockPath) {
+  try {
+    return fs.readFileSync(lockPath, 'utf8');
+  } catch (err) {
+    if (_isTransientFileLockPathError(err)) return null;
+    throw err;
+  }
+}
+
+function _tryReapFileLock(lockPath) {
+  const claimPath = `${lockPath}.reap`;
+  let claimFd;
+  try {
+    claimFd = fs.openSync(claimPath, 'wx');
+    try {
+      fs.writeSync(claimFd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+    } catch { /* claim existence provides serialization */ }
+  } catch (err) {
+    const contended = err && (err.code === 'EEXIST'
+      || (process.platform === 'win32' && err.code === 'EPERM'));
+    if (contended) return false;
+    throw err;
+  }
+
+  try {
+    const observed = _readFileLockState(lockPath);
+    if (!observed) return false;
+    const shouldReap = observed.holderPid !== null
+      ? !processUtils.isPidAlive(observed.holderPid) || observed.mtimeAge > LOCK_STALE_MS * 5
+      : observed.mtimeAge > LOCK_STALE_MS;
+    if (!shouldReap) return false;
+
+    // A holder can release and a successor can acquire between the PID probe
+    // and deletion. The reap claim excludes competing reapers; this identity
+    // check prevents the winner from deleting that successor's lock.
+    const currentRaw = _readFileLockIdentity(lockPath);
+    if (currentRaw === null) return false;
+    if (currentRaw !== observed.raw) return false;
+
+    try {
+      fs.unlinkSync(lockPath);
+      return true;
+    } catch (err) {
+      if (_isTransientFileLockPathError(err)) return false;
+      throw err;
+    }
+  } finally {
+    _releaseFileLock(claimPath, claimFd);
+  }
+}
+
 function withFileLock(lockPath, fn, {
   timeoutMs = 5000,
   retryDelayMs = 25,
@@ -1420,9 +1524,13 @@ function withFileLock(lockPath, fn, {
       const backoff = retryBackoffMs * Math.pow(2, attempt - 1);
       sleepMs(backoff);
     }
-    const start = Date.now();
     let fd = null;
-    while (Date.now() - start < timeoutMs) {
+    const pollDelayMs = Math.max(1, Number(retryDelayMs) || 1);
+    const waitBudgetMs = Math.max(0, Number(timeoutMs) || 0);
+    let waitedMs = 0;
+    let contentionCount = 0;
+    let lastOwnerIdentity;
+    while (true) {
       try {
         const dir = path.dirname(lockPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -1432,7 +1540,11 @@ function withFileLock(lockPath, fn, {
         // the lock's existence (not its contents) provides mutual exclusion, so
         // a write failure here must NOT abort acquisition.
         try {
-          fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+          fs.writeSync(fd, JSON.stringify({
+            pid: process.pid,
+            ts: Date.now(),
+            owner: crypto.randomBytes(8).toString('hex'),
+          }));
         } catch { /* payload is advisory; lock semantics unaffected */ }
         break;
       } catch (err) {
@@ -1447,47 +1559,27 @@ function withFileLock(lockPath, fn, {
         const isLockRaceErr = err.code === 'EEXIST' ||
           (process.platform === 'win32' && err.code === 'EPERM');
         if (!isLockRaceErr) throw err;
-        // 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;
-          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 */ }
-
-          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
+        const ownerIdentity = _readFileLockIdentity(lockPath);
+        if (ownerIdentity !== null && ownerIdentity !== lastOwnerIdentity) {
+          if (lastOwnerIdentity !== undefined) {
+            waitedMs = 0;
+            contentionCount = 0;
           }
-        } catch (staleErr) {
-          // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed.
-          // EPERM on Windows: file is in 'pending delete' state — statSync itself
-          // can fail; fall through to the normal retry sleep (W-mpd6lm1g000x195e).
-          const tolerable = staleErr.code === 'ENOENT' ||
-            (process.platform === 'win32' && staleErr.code === 'EPERM');
-          if (!tolerable) throw staleErr;
+          lastOwnerIdentity = ownerIdentity;
         }
-        sleepMs(retryDelayMs);
+        if (_tryReapFileLock(lockPath)) continue;
+        // Count active retry sleeps rather than wall time. Host suspension must
+        // not consume the whole budget without another acquisition attempt.
+        if (waitedMs >= waitBudgetMs) break;
+        const backoffMs = Math.min(
+          pollDelayMs * Math.pow(2, Math.min(contentionCount, 4)),
+          FILE_LOCK_RETRY_MAX_DELAY_MS
+        );
+        const jitterMs = contentionCount === 0 ? 0 : Math.floor(Math.random() * pollDelayMs);
+        const delayMs = Math.min(waitBudgetMs - waitedMs, backoffMs + jitterMs);
+        sleepMs(delayMs);
+        waitedMs += delayMs;
+        contentionCount += 1;
       }
     }
     if (fd === null) {
@@ -1503,16 +1595,14 @@ function withFileLock(lockPath, fn, {
       // completes, silently breaking mutual exclusion. Clean up our own fd /
       // lock first, then throw so the caller cannot ignore the failure.
       if (result && typeof result.then === 'function') {
-        try { fs.closeSync(fd); } catch { /* cleanup */ }
-        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
+        _releaseFileLock(lockPath, fd);
         fd = null; // suppress double-cleanup in `finally`
         throw new Error('withFileLock: fn must be synchronous; got Promise. Use synchronous operations only.');
       }
       return result;
     } finally {
       if (fd !== null) {
-        try { fs.closeSync(fd); } catch { /* cleanup */ }
-        try { fs.unlinkSync(lockPath); } catch { /* cleanup */ }
+        _releaseFileLock(lockPath, fd);
       }
     }
   }
@@ -2602,6 +2692,62 @@ function isLiveCheckoutProject(project) {
   return resolveCheckoutMode(project) === CHECKOUT_MODES.LIVE;
 }
 
+// Persisted dispatch records must carry explicit checkout-mode provenance before
+// restart/orphan recovery may operate on project.localPath. Legacy live records
+// are accepted only while the current configured project still resolves live for
+// that work-item type. Any explicit worktree marker or current worktree config
+// fails closed.
+function isLiveCheckoutDispatchRecord(item, config) {
+  if (!item || typeof item !== 'object') return false;
+  const hasCheckoutMarker = Object.prototype.hasOwnProperty.call(item, 'checkoutMode');
+  const hasLegacyMarker = Object.prototype.hasOwnProperty.call(item, 'liveMode');
+  let explicitlyLive = false;
+  if (hasCheckoutMarker) {
+    if (item.checkoutMode !== CHECKOUT_MODES.LIVE) return false;
+    explicitlyLive = true;
+  } else if (hasLegacyMarker) {
+    if (item.liveMode !== true) return false;
+    explicitlyLive = true;
+  }
+
+  if (config !== undefined && config !== null) {
+    let projects;
+    try { projects = getProjects(config); } catch { return false; }
+    const projectRef = item.meta?.project;
+    const resolved = resolveProjectSource(projectRef, projects, { allowCentral: false }).project;
+    if (!resolved || resolveCheckoutMode(resolved, item.type) !== CHECKOUT_MODES.LIVE) return false;
+    if (!projectRef?.localPath || !resolved.localPath
+        || !sameResolvedPath(projectRef.localPath, resolved.localPath)) return false;
+    return explicitlyLive || !!item.originalRef;
+  }
+
+  return explicitlyLive;
+}
+
+function isDispatchExecutionPathSafe(item, config) {
+  if (!item || typeof item !== 'object') return false;
+  let projects;
+  try { projects = getProjects(config); } catch { return false; }
+
+  if (item.worktreePath) {
+    try {
+      assertWorktreeOutsideProjects(item.worktreePath, projects);
+      return isValidGitWorktree(item.worktreePath).ok;
+    } catch {
+      return false;
+    }
+  }
+  if (isLiveCheckoutDispatchRecord(item, config)) return true;
+  if (item.meta?.project) return false;
+  if (!item.executionCwd) return false;
+  try {
+    assertWorktreeOutsideProjects(item.executionCwd, projects);
+    return fs.existsSync(item.executionCwd);
+  } catch {
+    return false;
+  }
+}
+
 // W-mqvejug6000eeb20 — resolve the effective live-checkout auto-reset decision.
 // Precedence: an explicit per-project boolean (`project.liveCheckoutAutoReset`)
 // wins; otherwise the fleet-wide `engine.liveCheckoutAutoReset` applies;
@@ -5483,6 +5629,11 @@ function isWorktreeRootInfraEntry(name) {
   return typeof name === 'string' && name.length > 0 && name.charCodeAt(0) === 46; // '.'
 }
 
+function _pathForComparison(filePath) {
+  const resolved = realPathForComparison(String(filePath));
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
 /**
  * True when `childPath` is strictly nested within `parentPath` (descendant,
  * NOT the same path). Cross-platform via `path.relative`; resilient to mixed
@@ -5491,8 +5642,8 @@ function isWorktreeRootInfraEntry(name) {
  */
 function isPathInside(childPath, parentPath) {
   if (!childPath || !parentPath) return false;
-  const childAbs = path.resolve(String(childPath));
-  const parentAbs = path.resolve(String(parentPath));
+  const childAbs = _pathForComparison(childPath);
+  const parentAbs = _pathForComparison(parentPath);
   const rel = path.relative(parentAbs, childAbs);
   if (rel === '') return false;
   if (rel.startsWith('..')) return false;
@@ -5512,12 +5663,17 @@ function isPathInside(childPath, parentPath) {
  */
 function isPathInsideOrEqual(childPath, parentPath) {
   if (!childPath || !parentPath) return false;
-  const childAbs = path.resolve(String(childPath));
-  const parentAbs = path.resolve(String(parentPath));
+  const childAbs = _pathForComparison(childPath);
+  const parentAbs = _pathForComparison(parentPath);
   if (childAbs === parentAbs) return true;
   return isPathInside(childAbs, parentAbs);
 }
 
+function pathsOverlap(firstPath, secondPath) {
+  return isPathInsideOrEqual(firstPath, secondPath)
+    || isPathInsideOrEqual(secondPath, firstPath);
+}
+
 /**
  * Parse `git worktree list --porcelain` output. Pure — callers run the
  * subprocess (sync `execSilent` or async `execAsync`) and feed stdout in.
@@ -5572,6 +5728,22 @@ function assertWorktreeOutsideProject(worktreePath, projectRoot) {
   throw err;
 }
 
+function assertWorktreeOutsideProjects(worktreePath, projectsOrConfig) {
+  const projects = Array.isArray(projectsOrConfig)
+    ? projectsOrConfig
+    : getProjects(projectsOrConfig);
+  for (const project of projects) {
+    if (!project?.localPath) continue;
+    if (!pathsOverlap(worktreePath, project.localPath)) continue;
+    const err = new Error(
+      `Refusing worktree path "${worktreePath}" — it overlaps configured operator checkout "${project.localPath}".`
+    );
+    err.code = 'WORKTREE_NESTED_IN_PROJECT';
+    err.protectedProject = project.name || '';
+    throw err;
+  }
+}
+
 /**
  * Resolve the project root directory used as the parent for git worktree paths
  * during dispatch. Centralizes the fallback that engine spawnAgent used to do
@@ -5712,9 +5884,11 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * @param {string} type — work type (e.g. 'fix', 'explore', 'meeting')
  * @param {string} minionsDir — MINIONS_DIR fallback anchor (ignored in live mode)
  * @param {{ workdir?: string|null }} [options] — optional per-WI overrides
- * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean, workdir?: string|null }}
+ * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean, readOnlyWorktree?: boolean, workdir?: string|null }}
  *   - For live mode (any type): { cwd: <abs localPath[/workdir]>, worktreeRootDir: null, liveMode: true }
- *   - For isolated read-only types: { cwd: <project dir[/workdir] or MINIONS_DIR>, worktreeRootDir: null }
+ *   - For project-bound isolated read-only types:
+ *     { cwd: null, worktreeRootDir: <project root>, readOnlyWorktree: true, workdir }
+ *   - For project-less read-only types: { cwd: <MINIONS_DIR[/workdir]>, worktreeRootDir: null }
  *   - For isolated code-mutating types: { cwd: null, worktreeRootDir: <project root>, workdir: <subpath|null> }
  *     (caller defaults cwd to worktreeRootDir before worktree creation,
  *      then runs shared.applyWorkdir(worktreePath, result.workdir) to land
@@ -5757,14 +5931,21 @@ function resolveSpawnPaths(project, type, minionsDir, options) {
 
   const isReadOnly = READ_ONLY_ROOT_TASK_TYPES.has(type);
   if (isReadOnly) {
-    let base = null;
-    if (project?.localPath) base = path.resolve(String(project.localPath));
-    else if (minionsDir) base = path.resolve(String(minionsDir));
-    else {
+    if (project?.localPath) {
+      if (workdir) _applyWorkdirOrThrow(path.resolve(String(project.localPath)), workdir);
+      return {
+        cwd: null,
+        worktreeRootDir: resolveProjectRootDir(project.localPath, minionsDir),
+        readOnlyWorktree: true,
+        workdir,
+      };
+    }
+    if (!minionsDir) {
       const err = new Error('Cannot resolve cwd for read-only spawn: no project.localPath and no MINIONS_DIR provided.');
       err.code = 'WORKTREE_ROOTDIR_MISSING_BASE';
       throw err;
     }
+    const base = path.resolve(String(minionsDir));
     const roCwd = _applyWorkdirOrThrow(base, workdir);
     return { cwd: roCwd, worktreeRootDir: null };
   }
@@ -5878,7 +6059,7 @@ function applyWorkdir(base, workdir) {
   const baseAbs = path.resolve(String(base));
   const joined = path.resolve(baseAbs, workdir);
   // Containment guard: resolved cwd must equal base or live strictly inside.
-  if (joined !== baseAbs && !joined.startsWith(baseAbs + path.sep)) {
+  if (!isPathInsideOrEqual(joined, baseAbs)) {
     return {
       cwd: baseAbs,
       error: 'workdir resolved outside base (containment escape): "' + workdir + '" → "' + joined + '" not inside "' + baseAbs + '"',
@@ -8065,6 +8246,14 @@ function _writeWorktreeSkipLiveInboxNote(worktreePath, callerTag, blockingInfo)
 function removeWorktree(wtPath, gitRoot, worktreeRoot, opts = {}) {
   const resolved = path.resolve(wtPath);
   const resolvedRoot = path.resolve(worktreeRoot) + path.sep;
+  let protectedProjects;
+  try {
+    protectedProjects = Array.isArray(opts.projects) ? opts.projects : getProjects(opts.config);
+    assertWorktreeOutsideProjects(resolved, protectedProjects);
+  } catch (err) {
+    log('warn', `removeWorktree: refusing to remove ${wtPath} — path is inside configured operator checkout${err?.protectedProject ? ` ${err.protectedProject}` : ''}`);
+    return false;
+  }
   if (!resolved.startsWith(resolvedRoot)) {
     log('warn', `removeWorktree: refusing to remove ${wtPath} — not under ${worktreeRoot}`);
     return false;
@@ -8679,14 +8868,18 @@ module.exports = {
   WORKTREE_SCRATCH_DIR_NAME,
   isPathInside,
   isPathInsideOrEqual,
+  pathsOverlap,
   parseWorktreePorcelain,
   assertWorktreeOutsideProject,
+  assertWorktreeOutsideProjects,
   resolveProjectRootDir,
   resolveAgentTempBaseDir,
   resolveSpawnPaths,
   validateWorkItemWorkdir,
   applyWorkdir,
   READ_ONLY_ROOT_TASK_TYPES,
+  isLiveCheckoutDispatchRecord,
+  isDispatchExecutionPathSafe,
   isLiveCommandCenterPath,
   describeCcProtectedPaths,
   renderCcSystemPrompt,

package/engine/spawn-agent.js

@@ -626,9 +626,12 @@ function main() {
             // meta.keep_processes_skip_workdir_check is true) bypasses the
             // requireGitWorkdir check so legitimate non-git keep_processes
             // use cases (e.g., a daemon under /tmp) still anchor.
-            const reapOpts = process.env.MINIONS_KEEP_PROCESSES_SKIP_WORKDIR_CHECK === '1'
-              ? { requireGitWorkdir: false }
-              : {};
+            const reapOpts = {
+              requireGitWorkdir: process.env.MINIONS_KEEP_PROCESSES_SKIP_WORKDIR_CHECK !== '1',
+            };
+            if (process.env.MINIONS_KEEP_PROCESSES_ALLOWED_CWD_ROOT) {
+              reapOpts.allowedCwdRoot = process.env.MINIONS_KEEP_PROCESSES_ALLOWED_CWD_ROOT;
+            }
             const plan = keepProcessSweep.computeReapPlan(toKillPids, agentId, reapOpts);
             toKillPids = plan.toKill;
             kept = plan.kept;

package/engine/timeout.js

@@ -25,14 +25,16 @@ let _engine = null;
 function engine() { if (!_engine) _engine = require('../engine'); return _engine; }
 const _pendingBranchPreservations = new Set();
 
-function resolveDispatchBranchPath(item) {
+function resolveDispatchBranchPath(item, config) {
   if (item?.worktreePath) return item.worktreePath;
-  if (item?.originalRef && item.meta?.project?.localPath) return item.meta.project.localPath;
+  if (shared.isLiveCheckoutDispatchRecord(item, config) && item.meta?.project?.localPath) {
+    return item.meta.project.localPath;
+  }
   return null;
 }
 
 function preserveDispatchBranch(item, config) {
-  const branchPath = resolveDispatchBranchPath(item);
+  const branchPath = resolveDispatchBranchPath(item, config);
   if (!branchPath || !item.meta?.branch) {
     return Promise.resolve({ pushed: false, reason: 'invalid-worktree' });
   }
@@ -55,17 +57,18 @@ async function _finalizeDeadDispatch(item, reason, failureClass, config, deps =
     require('./live-checkout').maybeRestoreLiveCheckoutFromRecord;
   const complete = deps.complete || dispatch().completeDispatch;
 
-  if (resolveDispatchBranchPath(item) && item.meta?.branch) {
+  if (resolveDispatchBranchPath(item, config) && 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) {
+  if (shared.isLiveCheckoutDispatchRecord(item, config)) {
     try {
       await restoreLiveCheckout({
         item,
+        config,
         isTerminalFailure: true,
         resultLabel: 'orphaned',
         log: (lvl, msg) => log(lvl, msg),
@@ -719,7 +722,7 @@ function checkTimeouts(config) {
   const legacyAnnotationClears = new Set();
 
   function completeFromOutput(item, liveLogPath, processExitCode, detectedLogText, hasProcess, preservationDone = false, expectedProcInfo = activeProcesses.get(item.id)) {
-    if (!preservationDone && resolveDispatchBranchPath(item) && item.meta?.branch) {
+    if (!preservationDone && resolveDispatchBranchPath(item, config) && item.meta?.branch) {
       if (_pendingBranchPreservations.has(item.id)) return;
       _pendingBranchPreservations.add(item.id);
       preserveDispatchBranch(item, config)
@@ -776,12 +779,13 @@ function checkTimeouts(config) {
     // 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. originalRef's presence is the live-mode signal; the helper no-ops
-    // for non-live records. Fire-and-forget + best-effort.
-    if (item.originalRef && item.meta?.branch && item.meta?.project?.localPath) {
+    // branch. Explicit dispatch provenance plus current config are the live-mode
+    // signal; worktree-mode records fail closed.
+    if (shared.isLiveCheckoutDispatchRecord(item, config)) {
       try {
         require('./live-checkout').maybeRestoreLiveCheckoutFromRecord({
           item,
+          config,
           isTerminalFailure: _completedAsError,
           resultLabel: _completedAsError ? 'error' : 'success',
           log: (lvl, msg) => log(lvl, msg),
@@ -1033,7 +1037,7 @@ function checkTimeouts(config) {
     // #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 (resolveDispatchBranchPath(item, config) && item.meta?.branch) {
       if (_pendingBranchPreservations.has(item.id)) continue;
       _pendingBranchPreservations.add(item.id);
       _finalizeDeadDispatch(item, reason, failureClass, config, { complete: completeDispatch })