claude-code-session-manager 0.60.0 → 0.62.0

package/src/main/scheduler.cjs

@@ -108,6 +108,7 @@ function resolveOriginSessionId(cwd, epicId) {
   return session && typeof session.claudeSessionId === 'string' ? session.claudeSessionId : null;
 }
 const sessionSlots = require('./lib/sessionSlots.cjs');
+const jobWorktree = require('./lib/jobWorktree.cjs');
 const queueStore = require('./lib/queueStore.cjs');
 const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
 const { migratePrds, consolidateFlatPrds } = require('./lib/prdMigration.cjs');
@@ -119,6 +120,9 @@ const { allProjectCwds } = require('../../scripts/lib/activeSessions.cjs');
 // an exemption it should have applied landed on disk, and nothing in the
 // run record showed that; this is the fix).
 const SCHEDULER_BOOTED_AT = new Date().toISOString();
+// Resolves against __dirname (this app's OWN source checkout) — unaffected by
+// PRD 994's job worktrees, which live under a job's PROJECT cwd, never under
+// this app's install directory.
 const SCHEDULER_CODE_SHA = (() => {
   try {
     return execFileSync('git', ['-C', __dirname, 'rev-parse', '--short', 'HEAD'], {
@@ -195,8 +199,14 @@ sequence. Do not stop before the commit lands; committing is part of the job.
 3. VERIFY — run the project's OWN check commands (typecheck / lint / tests — the
    project's CLAUDE.md names them; infer from the repo if not) and make them
    pass. Do not assume npm; use whatever the target project uses.
-4. COMMIT — stage and commit ALL changes with a clear conventional message:
-   \`git add -A && git commit -m "<type>(<scope>): <summary>"\`.
+4. COMMIT — the queue can run several jobs against this SAME working tree at
+   once. Do NOT stage the whole working tree in one blanket/wildcard git-add
+   sweep — that captures whatever a concurrent sibling job is mid-writing and
+   mis-attributes its work to this commit, corrupting both jobs' verdicts.
+   Stage only the exact paths YOU created or modified for this PRD, then
+   commit: \`git add <path> [<path>...] && git commit -m "<type>(<scope>): <summary>"\`.
+   Your own work must still never be left uncommitted — this only changes
+   which paths get staged, never whether you commit.
 5. VERDICT SENTINEL — as the LAST LINE of your final result text, emit exactly
    one of these two lines (no trailing text after it):
      SCHEDULER_VERDICT: PASS
@@ -512,7 +522,22 @@ function prdDirForCwd(cwd) {
   return resolvePrdWriteDir(cwd || DEFAULT_PROJECT_CWD);
 }
 
-/** Absolute path to `<job's project PRDs dir>/<job.slug>.md`. */
+/**
+ * Absolute path to `<job's project PRDs dir>/<job.slug>.md`. Resolves to
+ * `resolvePrdWriteDir(cwd)` — the RETIRED flat
+ * `<cwd>/session-manager-operations/scheduler/prds/` dir, which holds only
+ * zero-byte `.reserved-NNN` stubs and no PRD source for any Epic-scoped PRD
+ * (see resolveNotifyPrd's and resolveVerifyPrdPath's doc comments, PRD 985
+ * and 991). Do NOT reach for this in new code — use `findPrdDir(slug)` (via
+ * `resolveVerifyPrdPath`/`resolveNotifyPrd`, or directly for a fresh path)
+ * instead. The one legitimate remaining caller is executeJob's `prdPath`
+ * (~line 2235), which only falls back to this AFTER `findPrdDir` already
+ * came up empty — a real miss, not a resolution shortcut — matching this
+ * function's genuinely-legacy semantics rather than a bug. (PRD 991 also
+ * removed the two verify call sites and buildInvestigationPrompt's
+ * originalBody read from this list — all three now go through
+ * resolveVerifyPrdPath instead.)
+ */
 function prdPathForJob(job) {
   return path.join(prdDirForCwd(job && job.cwd), `${job && job.slug}.md`);
 }
@@ -1845,8 +1870,7 @@ function extractResultTextFromLog(logPath) {
  */
 async function resolveNotifyPrd(job, parsePrdRaw) {
   if (!job || !job.slug) return null;
-  const liveDir = await findPrdDir(job.slug).catch(() => null);
-  const livePath = liveDir ? safeSlugPathIn(liveDir, job.slug) : null;
+  const livePath = await resolveVerifyPrdPath(job);
   if (livePath) {
     const parsed = await parsePrdRaw(livePath).catch(() => null);
     if (parsed) return parsed;
@@ -1856,6 +1880,26 @@ async function resolveNotifyPrd(job, parsePrdRaw) {
   return await parsePrdRaw(archivedPath).catch(() => null);
 }
 
+/**
+ * resolveVerifyPrdPath(job) → Promise<string|null>
+ *
+ * Path-only sibling of resolveNotifyPrd's live-dir lookup (PRD 985/991):
+ * find `<slug>.md` via findPrdDir's full candidate search (legacy flat dir +
+ * every project's Epic-scoped dirs) and return its safe, containment-checked
+ * path. Used by verifyRun call sites, which need a path string to read the
+ * PRD body from — not a parsed object — so it stops short of the
+ * parse-then-fall-back-to-archived step resolveNotifyPrd layers on top.
+ * Deliberately does NOT fall back to `prdPathForJob` (the retired flat dir,
+ * see that function's own doc comment) — a null here means the caller
+ * should treat the PRD as unresolved, not read a path that is known to
+ * never contain the file.
+ */
+async function resolveVerifyPrdPath(job) {
+  if (!job || !job.slug) return null;
+  const liveDir = await findPrdDir(job.slug).catch(() => null);
+  return liveDir ? safeSlugPathIn(liveDir, job.slug) : null;
+}
+
 /**
  * notifyOriginatingTab(job) → void
  *
@@ -2134,27 +2178,62 @@ function classifyFailureOutcome({ exitCode, networkError, durationMs, transientR
  * Commit-guard verdict decision. Pure/no I/O so the false-positive defenses
  * can be unit-tested directly rather than only through a live spawnJob run.
  * Returns the flagged verifyResult replacement, or null if the guard should
- * not fire (any of the four defenses applies).
+ * not fire (any of the defenses below applies).
  *
- * The fourth defense (legitimateNoOp) exists because runVerify.cjs's own
- * pass_no_commit exemptions (COMPLETED_EQUIVALENT_VERDICTS members like
- * pass_no_commit_already_shipped) already independently proved a truthful
- * PASS-with-no-commit is correct; without this check the commit-guard
- * double-punishes that same honest no-op for dirt a concurrent interactive
- * session left behind (incidents: 655-needs-review-rca-feedback-hook,
- * 672-fix-feedback-session-manager, 2026-07-31).
+ * Runs for BOTH shapes of "no commit landed": (a) newlyDirty.length > 0 — the
+ * finish protocol's COMMIT step didn't run and left evidence behind — and
+ * (b) newlyDirty.length === 0 on a clean tree — the strongest possible silent
+ * no-op signal (exitCode 0, no commit, nothing even left dirty; PRD 972's
+ * shape). Before PRD 972-followup, case (b) bypassed the guard entirely
+ * because the call site only invoked commitGuardVerdict when the working
+ * tree was dirty — closed by widening that call site's condition, not by
+ * changing this function's four defenses below, which still apply to both
+ * shapes identically:
+ *   - siblingRunning: a concurrent job in the same cwd makes working-tree
+ *     evidence unreliable in both directions (extra dirt OR a clean tree
+ *     that isn't this job's doing).
+ *   - jobSelfCommitted: HEAD moved during the run, so the job's deliverable
+ *     landed even if dirt (from a concurrent actor) remains.
+ *   - legitimateNoOp (COMPLETED_EQUIVALENT_VERDICTS): runVerify.cjs's own
+ *     pass_no_commit exemptions (pass_no_commit_already_shipped, etc.)
+ *     already independently proved a truthful PASS-with-no-commit is
+ *     correct; without this check the commit-guard double-punishes that
+ *     same honest no-op (incidents: 655-needs-review-rca-feedback-hook,
+ *     672-fix-feedback-session-manager, 2026-07-31).
+ *   - isFixPlanJob (zero-edit case only): a fix-plan investigation
+ *     (slug ^\d+-fix-) legitimately concluding "the original work already
+ *     landed, nothing to change" makes no commit on an already-clean tree —
+ *     runVerify.cjs:896 exempts this same shape from ever raising
+ *     pass_no_commit in the first place (so its verdict stays 'clean', not a
+ *     COMPLETED_EQUIVALENT member — legitimateNoOp alone can't catch it),
+ *     which is why this is a distinct exemption. Only applies when
+ *     newlyDirty is empty: a fix-plan job that left real dirt behind is
+ *     still a genuine finish-protocol violation (incident:
+ *     523-fix-bounded-fix-plan-retry, 2026-07-12).
  */
-function commitGuardVerdict({ newlyDirty, siblingRunning, jobSelfCommitted, legitimateNoOp, verifyResult }) {
-  if (!newlyDirty || newlyDirty.length === 0) return null;
+function commitGuardVerdict({ newlyDirty, siblingRunning, jobSelfCommitted, legitimateNoOp, isFixPlanJob, verifyResult }) {
   if (siblingRunning || jobSelfCommitted || legitimateNoOp) return null;
-  const sample = newlyDirty.slice(0, 3).join(', ');
+  const dirty = newlyDirty || [];
+  if (dirty.length === 0 && isFixPlanJob) return null;
+
   const carried = [...(verifyResult?.annotations ?? [])];
   if (verifyResult && verifyResult.verdict !== 'clean') {
     carried.push({ verdict: verifyResult.verdict, reason: verifyResult.reason });
   }
+
+  if (dirty.length === 0) {
+    return {
+      verdict: 'silent_no_op',
+      reason: 'finish protocol incomplete: run exited 0, made no commit, and left the working tree exactly as it started — no evidence any work was done',
+      downgradeTo: 'needs_review',
+      annotations: carried.length ? carried : undefined,
+    };
+  }
+
+  const sample = dirty.slice(0, 3).join(', ');
   return {
     verdict: 'uncommitted_changes',
-    reason: `finish protocol incomplete: ${newlyDirty.length} uncommitted file(s) left in working tree (e.g. ${sample})`,
+    reason: `finish protocol incomplete: ${dirty.length} uncommitted file(s) left in working tree (e.g. ${sample})`,
     downgradeTo: 'needs_review',
     annotations: carried.length ? carried : undefined,
   };
@@ -2178,10 +2257,15 @@ function pickRunDir() {
  * Watchdogs are declared as an array; the result-tailer's exit-code mapping
  * (success+killedBySignal → 0) is scheduler-specific and lives in onExit.
  */
-async function executeJob(job, runDir, defaultCwd, onPid) {
+async function executeJob(job, runDir, defaultCwd, onPid, execCwd) {
   const logPath = path.join(runDir, `${job.slug}.log`);
   const metaPath = path.join(runDir, `${job.slug}.meta.json`);
+  // `cwd` stays the MAIN tree throughout — PRD lookup (findPrdDir/prdPathForJob)
+  // and every git call below key off this value, never the worktree. Only the
+  // spawned child's own process cwd (spawnCwd) may point at a job worktree —
+  // see jobWorktree.cjs's header comment for why the two must never merge.
   const cwd = job.cwd || defaultCwd;
+  const spawnCwd = execCwd || cwd;
   const startedAt = Date.now();
   const sessionId = randomUUID();
 
@@ -2190,11 +2274,13 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
   // of fd/safeLog/closeFd from the point it is called.
   const { fd, safeLog, closeFd } = openLog(logPath);
 
-  safeLog(`[scheduler] starting ${job.slug} at ${new Date().toISOString()}\n[scheduler] cwd=${cwd}\n\n`);
+  safeLog(`[scheduler] starting ${job.slug} at ${new Date().toISOString()}\n[scheduler] cwd=${cwd}` +
+    (spawnCwd !== cwd ? ` (running isolated in worktree ${spawnCwd})` : '') + '\n\n');
 
   // Dead-cwd guard: verify the target directory exists and is traversable
-  // before handing it to the child process.
-  try { fs.accessSync(cwd, fs.constants.X_OK); }
+  // before handing it to the child process. Checks spawnCwd (where the child
+  // ACTUALLY runs) — cwd is only used for PRD/git bookkeeping.
+  try { fs.accessSync(spawnCwd, fs.constants.X_OK); }
   catch {
     const errMsg = `cwd does not exist on this machine: ${cwd}`;
     safeLog(`[scheduler] ${errMsg}\n`);
@@ -2216,9 +2302,11 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
   let prdPath = resolvedDir ? path.join(resolvedDir, `${job.slug}.md`) : prdPathForJob(job);
   try {
     const parsed = await parsePrd(prdPath);
-    // Centrally enforce the review → security-review → verify → commit finish
-    // sequence on every job, regardless of what the PRD body says.
-    prompt = parsed.body + FINISH_PROTOCOL;
+    // The review → security-review → verify → commit finish sequence is
+    // folded in below via composeExecutorPrompt, after the Epic digest is
+    // resolved — never concatenated here, so it can't end up ahead of the
+    // digest in the composed prompt (PRD 992).
+    prompt = parsed.body;
   } catch (e) {
     // The project-scoped dir isn't the only place a PRD source can live — a
     // writer that hasn't migrated to prdLocations.cjs yet (or a not-yet-run
@@ -2230,7 +2318,7 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
       safeLog(`[scheduler] PRD not in project dir; found ${job.slug}.md in ${fallbackDir}\n`);
       try {
         const parsed = await parsePrd(fallbackPath);
-        prompt = parsed.body + FINISH_PROTOCOL;
+        prompt = parsed.body;
         prdPath = fallbackPath;
       } catch (e2) {
         // Found the dir a moment ago but the read still failed. Case A: the
@@ -2275,17 +2363,20 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
   const digestEpicId = job.epicId ?? job.sourcePromptId ?? null;
   const originSessionId = resolveOriginSessionId(cwd, digestEpicId);
   let contextDigestApplied = false;
+  let digestText = '';
   if (originSessionId) {
     try {
-      const digestText = await buildContextDigest({ cwd, epicId: digestEpicId });
-      if (digestText) {
-        prompt = composeExecutorPrompt({ prdBody: prompt, digestText });
-        contextDigestApplied = true;
-      }
+      digestText = await buildContextDigest({ cwd, epicId: digestEpicId });
+      if (digestText) contextDigestApplied = true;
     } catch (e) {
       safeLog(`[scheduler] context digest build failed (job still dispatches without it): ${e?.message ?? e}\n`);
+      digestText = '';
     }
   }
+  // Always route through composeExecutorPrompt (even with an empty digest)
+  // so the finish protocol is appended in the prompt's tail exactly once,
+  // after any digest fence rather than concatenated ahead of it.
+  prompt = composeExecutorPrompt({ prdBody: prompt, digestText, finishProtocol: FINISH_PROTOCOL });
 
   const promptCheck = validatePromptForSpawn(prompt, prdPath);
   if (!promptCheck.ok) {
@@ -2418,7 +2509,7 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
           '--session-id', sessionId,
         ],
         options: {
-          cwd,
+          cwd: spawnCwd,
           env: childEnv,
           // detached:true puts the child in its own process group so we can kill
           // the entire descendant tree (including any stray background bashes the
@@ -2683,7 +2774,8 @@ async function spawnInvestigation(failedJob, runDir) {
 
   let originalBody = '';
   try {
-    originalBody = (await parsePrd(prdPathForJob(failedJob))).body;
+    const originalPath = (await resolveVerifyPrdPath(failedJob)) ?? archivedPrdPathForJob(failedJob);
+    originalBody = (await parsePrd(originalPath)).body;
   } catch {
     originalBody = failedJob.bodyPreview || '(original PRD missing from disk)';
   }
@@ -2867,16 +2959,65 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
     const guardBaseline = await uncommittedChanges(guardCwd);
     const guardHeadBefore = await gitHead(guardCwd);
 
-    const res = await executeJob(job, runDir, defaultCwd, async (pid, sessionId, cwd) => {
-      await mutate((s) => {
-        const idx = s.jobs.findIndex((x) => x.slug === job.slug);
-        if (idx >= 0) {
-          s.jobs[idx].sessionId = sessionId;
-          s.jobs[idx].runtime = { pid, runId, startedAt: s.jobs[idx].startedAt, sessionId, cwd };
+    // Worktree isolation (PRD 994): give this job its own linked `git worktree`
+    // checkout so its edits/tests/commit never collide with a sibling job or
+    // an interactive session in the SAME repo. `worktree.ok` is false (with a
+    // logged reason) for a non-git cwd, a dirty base tree, the cap being hit,
+    // or SM_JOB_WORKTREE_DISABLE=1 — every case falls back to running in place,
+    // never a hard failure. See jobWorktree.cjs's header comment for why
+    // job.cwd (guardCwd) itself is NEVER repointed at the worktree dir.
+    const worktree = await jobWorktree.createJobWorktree({ cwd: guardCwd, slug: job.slug });
+    if (worktree.ok) {
+      console.log(`[scheduler] ${job.slug}: isolated in worktree ${worktree.dir} (branch ${worktree.branch})`);
+    } else {
+      console.log(`[scheduler] ${job.slug}: running in main tree (worktree not used: ${worktree.reason})`);
+    }
+
+    // Integrate the job's branch back into guardCwd's own HEAD, THEN tear the
+    // worktree checkout down — both must happen BEFORE any git read below
+    // (verify/commit-guard/sigterm check all read guardCwd), so a commit made
+    // inside the worktree is a real commit on the main tree by the time those
+    // checks run, exactly like an in-place commit would be. A leftover
+    // uncommitted file in the worktree would otherwise vanish unnoticed when
+    // the checkout is removed — captured here (worktreeLeftoverDirty) and
+    // folded into the commit-guard's dirty-file list further down.
+    //
+    // Wrapped in try/finally (not straight-line) so an unexpected throw from
+    // executeJob itself still runs integration+cleanup — otherwise a bug
+    // elsewhere in executeJob would leak the worktree checkout (and its
+    // activeWorktreeCount slot) for the rest of this process's life.
+    let res;
+    let worktreeLeftoverDirty = [];
+    let worktreeIntegrationFailure = null;
+    try {
+      res = await executeJob(job, runDir, defaultCwd, async (pid, sessionId, cwd) => {
+        await mutate((s) => {
+          const idx = s.jobs.findIndex((x) => x.slug === job.slug);
+          if (idx >= 0) {
+            s.jobs[idx].sessionId = sessionId;
+            s.jobs[idx].runtime = { pid, runId, startedAt: s.jobs[idx].startedAt, sessionId, cwd };
+          }
+        });
+        await broadcast({ flush: true });
+      }, worktree.ok ? worktree.dir : undefined);
+    } finally {
+      if (worktree.ok) {
+        worktreeLeftoverDirty = (await uncommittedChanges(worktree.dir)) || [];
+        const integration = await jobWorktree.integrateJobBranch({ cwd: guardCwd, branch: worktree.branch, slug: job.slug });
+        if (!integration.ok) {
+          worktreeIntegrationFailure = integration.reason;
+          console.error(`[scheduler] ${job.slug}: worktree branch integration FAILED (${integration.reason}) — branch ${worktree.branch} preserved in ${guardCwd} for manual recovery`);
+        } else if (integration.integrated) {
+          console.log(`[scheduler] ${job.slug}: worktree branch ${worktree.branch} integrated into ${guardCwd}${integration.mergeCommit ? ' (merge commit)' : ' (fast-forward)'}`);
         }
-      });
-      await broadcast({ flush: true });
-    });
+        await jobWorktree.cleanupJobWorktree({
+          cwd: guardCwd,
+          dir: worktree.dir,
+          branch: worktree.branch,
+          keepBranch: !integration.ok,
+        });
+      }
+    }
 
     if (res.rateLimited) {
       const resetIso = await refreshNextReset().catch(() => cachedNextReset);
@@ -2929,7 +3070,7 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
         jobLandedCommitThisRun = headAtExit;
       }
 
-      const prdPath = prdPathForJob(job);
+      const prdPath = (await resolveVerifyPrdPath(job)) ?? archivedPrdPathForJob(job);
       const stateForDeps = await readQueue();
       // priorLandedCommit: the commit a PREVIOUS run of this same slug landed,
       // if any — prefer the live jobs[] row (survives a resetJob, see
@@ -2962,29 +3103,17 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
       }
     }
 
-    // Commit guard: a clean exit that left NEW uncommitted changes means the
-    // finish protocol's COMMIT step did not run. Surface it as needs_review
-    // instead of letting it masquerade as 'completed' (the PRD 03/04
-    // left-uncommitted incident). Two false-positive defenses:
-    //   - baseline DELTA: only files dirtied during THIS run count, so
-    //     pre-existing user WIP is excluded; and
-    //   - sibling skip: if another job is concurrently writing the same repo,
-    //     working-tree dirt can't be attributed to this job, so skip the guard.
-    //   - self-commit skip: if HEAD moved during the run, the job committed its
-    //     deliverable; leftover dirt is presumptively a concurrent external edit
-    //     (e.g. an interactive session editing the same repo), not the job's
-    //     unsaved work — so skip rather than false-flag a completed job.
-    //   - legitimate-no-op skip: if the verifier already independently proved
-    //     this run's PASS-with-no-commit is truthful (verdict is one of
-    //     COMPLETED_EQUIVALENT_VERDICTS — pass_no_commit_target_verified,
-    //     _prior_run_verified, _already_shipped), the run itself did nothing
-    //     wrong; dirt left by a concurrent interactive session (e.g.
-    //     /process-feedback writing new PRD .md files into the same repo
-    //     while this job's own AC turned out to already be satisfied) is not
-    //     this job's unfinished work. Without this skip, runVerify.cjs's
-    //     exemption and this guard double-punish the same honest no-op from
-    //     two different code paths (incidents: 655-needs-review-rca-feedback-hook,
-    //     672-fix-feedback-session-manager, 2026-07-31).
+    // Commit guard: a clean exit that landed no commit means the finish
+    // protocol's COMMIT step did not run. Surface it as needs_review instead
+    // of letting it masquerade as 'completed' (the PRD 03/04 left-uncommitted
+    // incident, and PRD 972's zero-edit variant of the same failure). Runs
+    // for BOTH shapes — newly-dirty files left behind, AND an already-clean
+    // tree with no commit at all — since a clean exit that commits nothing
+    // and dirties nothing is the strongest possible silent-no-op signal, not
+    // proof the guard has nothing to check. commitGuardVerdict's own doc
+    // comment (above) covers all four false-positive defenses that apply to
+    // both shapes: baseline DELTA (below), sibling skip, self-commit skip,
+    // legitimate-no-op skip, and (zero-edit only) the fix-plan exemption.
     // Non-git cwds resolve to null and are skipped (the guard is best-effort).
     //
     // Runs even when a transcript-pattern verdict already fired: the commit-guard
@@ -2998,9 +3127,19 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
     const guardIsLegitimateNoOp = verifyResult && COMPLETED_EQUIVALENT_VERDICTS.has(verifyResult.verdict);
     if (res.exitCode === 0 && !res.rateLimited && !guardWillRefire && !guardIsLegitimateNoOp) {
       const after = await uncommittedChanges(guardCwd);
-      if (after && after.length > 0) {
+      // after === null means non-git cwd (or git errored) — best-effort skip,
+      // same as always; only a git-status result (even an empty one) counts
+      // as evidence for the zero-edit path.
+      if (after !== null) {
         const baseSet = new Set(guardBaseline || []);
-        const newlyDirty = after.filter((p) => !baseSet.has(p));
+        // worktreeLeftoverDirty was captured from a FRESH checkout (no baseline
+        // to diff against — every path in it is inherently new) right before
+        // the worktree was torn down, so it must be counted here or a job's
+        // uncommitted leftovers silently vanish with the worktree.
+        const newlyDirty = [...new Set([
+          ...after.filter((p) => !baseSet.has(p)),
+          ...worktreeLeftoverDirty,
+        ])];
         const guardState = await readQueue().catch(() => ({ jobs: [] }));
         const siblingRunning = (guardState.jobs || []).some(
           (j) => j.slug !== job.slug && j.status === 'running' && (j.cwd || defaultCwd) === guardCwd,
@@ -3012,15 +3151,31 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
           siblingRunning,
           jobSelfCommitted,
           legitimateNoOp: guardIsLegitimateNoOp,
+          isFixPlanJob: isFixPlanSlug(job.slug),
           verifyResult,
         });
         if (guardVerdict) {
           verifyResult = guardVerdict;
-          console.log(`[scheduler] commit-guard: ${job.slug} left ${newlyDirty.length} files uncommitted → needs_review`);
+          const what = newlyDirty.length > 0 ? `left ${newlyDirty.length} files uncommitted` : 'made no commit on an already-clean tree';
+          console.log(`[scheduler] commit-guard: ${job.slug} ${what} → needs_review`);
         }
       }
     }
 
+    // Worktree branch integration failure is a materially-checkable git-state
+    // signal exactly like the commit-guard above, and takes the same priority:
+    // a job whose commit could not be merged back into the main tree is NOT a
+    // success, whatever its exit code or verifier verdict said — the commit
+    // guard AC explicitly requires this failure be surfaced as an explicit job
+    // outcome, never silently dropped alongside the branch it's stranded on.
+    if (worktreeIntegrationFailure) {
+      verifyResult = {
+        verdict: 'worktree_integration_failed',
+        reason: `worktree branch integration failed: ${worktreeIntegrationFailure} — branch preserved for manual merge`,
+        downgradeTo: 'needs_review',
+      };
+    }
+
     // SIGTERM commit check: reuse the same commit-window scan the exit=0
     // guard uses above (one commit-detection path, not two) to see whether a
     // 143 (SIGTERM) run still landed a deliverable before it died. Scoped
@@ -3082,7 +3237,13 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
           s.jobs[i2].exitCode = res.exitCode;
           s.jobs[i2].error = effectiveStatus === 'needs_review'
             ? (verifyResult?.reason ?? sigtermOverrideReason ?? null)
-            : (res.error || null);
+            // A failed job (non-zero exit) never consults verifyResult above,
+            // but a worktree integration failure is still worth surfacing on
+            // the row so the stranded branch isn't silently invisible —
+            // concatenated (not `||`), so it's never dropped when res.error
+            // is ALSO set (e.g. a real exit failure whose branch also failed
+            // to integrate must show both, not just the first one).
+            : [res.error, worktreeIntegrationFailure ? verifyResult.reason : null].filter(Boolean).join('; ') || null;
           // Persist the commit THIS run landed (if HEAD advanced) so a later
           // re-fire of the same slug can prove its own no-op re-run is
           // truthful via the pass_no_commit_prior_run_verified exemption.
@@ -3222,7 +3383,14 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
       if (maybeTransient) {
         const afterFailure = await uncommittedChanges(guardCwd);
         const baseSet = new Set(guardBaseline || []);
-        const newlyDirty = (afterFailure || []).filter((p) => !baseSet.has(p));
+        // See the commit-guard block above: worktreeLeftoverDirty was captured
+        // (and the checkout already torn down) before this point, so it must
+        // be folded in here too or a transiently-killed job's leftover WIP
+        // silently disappears with its worktree.
+        const newlyDirty = [...new Set([
+          ...(afterFailure || []).filter((p) => !baseSet.has(p)),
+          ...worktreeLeftoverDirty,
+        ])];
         newlyDirtyCount = newlyDirty.length;
         dirtySample = newlyDirty.slice(0, 3).join(', ');
       }
@@ -3881,7 +4049,7 @@ async function reverifyNeedsReview() {
   const leftForReview = [];
   for (const job of candidates) {
     const runDir = path.join(RUNS_DIR, job.runId || resolveRunId(job));
-    const prdPath = prdPathForJob(job);
+    const prdPath = (await resolveVerifyPrdPath(job)) ?? archivedPrdPathForJob(job);
     // Derive committedDuringRun from the recorded run window. The live
     // commit-guard uses gitHead() (before/after HEAD diff); here the run is
     // already over so we query git log filtered to [startedAt, finishedAt+60s].
@@ -4418,6 +4586,20 @@ async function init() {
     // see partitionBootOrphans. Everything else (dead pid or no pid) is safe to
     // classify immediately below.
     const bootSnap = readQueueSync();
+
+    // Worktree boot reconciliation (PRD 994): a job worktree that survives an
+    // app crash/host reboot must not leak disk or a dangling branch forever —
+    // this sweeps every known project cwd (every cwd referenced by a queue
+    // row, plus the default project) and removes any of OUR worktrees still
+    // registered there. Best-effort: never blocks the rest of boot.
+    try {
+      const worktreeCwds = new Set(bootSnap.jobs.map((j) => j.cwd).filter(Boolean));
+      worktreeCwds.add(DEFAULT_PROJECT_CWD);
+      await jobWorktree.reconcileWorktreesOnBoot([...worktreeCwds]);
+    } catch (e) {
+      console.error('[scheduler] boot worktree reconciliation failed', e?.message);
+    }
+
     const { immediate: immediateSlugs, deferred: deferredSlugs } = partitionBootOrphans(bootSnap.jobs);
     const bootOutcomes = new Map();
     for (const j of bootSnap.jobs) {
@@ -4774,4 +4956,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, healRefusalReason, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, notifyNeedsReview, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult };
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, healRefusalReason, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, notifyNeedsReview, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, resolveVerifyPrdPath, resolveNotifyPrd, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult };