claude-code-session-manager 0.119.1 → 0.121.0

package/src/main/scheduler.cjs

@@ -57,6 +57,7 @@ const billing = require('./usage.cjs');
 const { cleanChildEnv, pathWithUserBins } = require('./lib/process/cleanEnv.cjs');
 const { ensureTimeoutShim, withTimeoutShimOnPath } = require('./lib/process/timeoutShim.cjs');
 const supervisor = require('./supervisor.cjs');
+const { processGroupRssMb } = require('./lib/process/procGroupRss.cjs');
 const { resolveClaudeBin, claudeSpawnTarget, probeClaudeVersion } = require('./lib/claude/claudeBin.cjs');
 const { headlessPermissionArgs, ensureCliCapsProbed } = require('./lib/claude/claudeCliCaps.cjs');
 // Fire-and-forget priming — by the time the first job dispatches, the cached
@@ -81,6 +82,10 @@ const { stripAppOwnedChurn } = require('./lib/scheduler/jobDirtFilter.cjs');
 const { GATE_AUTHORITY_VERDICTS, decideGateAuthority } = require('./lib/scheduler/gateAuthority.cjs');
 const { decideBaselineAuthority } = require('./lib/scheduler/baselineGate.cjs');
 const { linkDependencyDirs } = require('./lib/git/worktreeDeps.cjs');
+const { checkMainDependencyHealth, repairMainDependencies } = require('./lib/git/depHealth.cjs');
+// cwd -> last main-checkout dependency repair attempt (ms); caps repair to once per cooldown.
+const mainDepsRepairAt = new Map();
+const MAIN_DEPS_REPAIR_COOLDOWN_MS = 10 * 60_000;
 const { resolveBindingRateLimitReset } = require('./lib/claude/rateLimitWindow.cjs');
 const { isResetFresh, bindingWindow, degradedBudget, meterFailureBudget } = require('./lib/claude/usageCircuit.cjs');
 const { computeQueueHealth } = require('./lib/scheduler/queueHealth.cjs');
@@ -146,6 +151,7 @@ const queueOps = require('./queueOps.cjs');
 const { listEpicPrdDirs, listArchivedPrdDirs, deriveProjectCwdFromPrdPath } = require('./lib/prd/prdLocations.cjs');
 const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epic/epicMint.cjs');
 const agentModelResolve = require('./lib/claude/agentModelResolve.cjs');
+const { buildPersonaToolScope, personaToolScopeArgs } = require('./lib/claude/personaToolScope.cjs');
 const { resolveEpicEffort, effortArgs } = require('./lib/claude/agentEffortResolve.cjs');
 const { transitionJob, STATUS_HISTORY_CAP, LEGAL_TRANSITIONS } = require('./lib/scheduler/scheduleJobTransitions.cjs');
 const { buildContextDigest, composeExecutorPrompt } = require('./lib/epic/epicContextDigest.cjs');
@@ -411,7 +417,9 @@ const HEARTBEAT_MAX_BYTES = 1024 * 1024;
 // DEFAULT_PROJECT_CWD imported from lib/scheduler/schedulerBatch.cjs (single source of truth).
 
 // Each headless claude -p job can shell out to tsc/vite/pytest and grow well
-// past 1 GB at peak; reserve 2.5 GB per running+pending slot. Raised from 1.5 GB
+// past 1 GB at peak; reserve 2.5 GB of PEAK headroom per running+pending slot.
+// A running job's already-resident memory is credited back (consumedMb in
+// memoryLimitedBatchSize) because MemAvailable is already net of it. Raised from 1.5 GB
 // after the 2026-06-16 OOM: 3 concurrent cross-project jobs + their build
 // subprocesses pushed a 24 GB host ~10 GB into swap and the OOM killer took
 // Electron — every pty got SIGHUP (code=0 signal=1).
@@ -478,10 +486,13 @@ function getAvailableMemMb() {
  * drop available memory below MIN_FREE_MB_PER_JOB per active slot.
  * Exported for unit tests.
  */
-function memoryLimitedBatchSize(availableMb, minPerJob, runningCount, batchLen) {
+function memoryLimitedBatchSize(availableMb, minPerJob, runningCount, batchLen, consumedMb = 0) {
   if (availableMb === Infinity) return batchLen;
+  // Credit is bounded by the running jobs' own reservations: never negative,
+  // never more permissive than a 0-running machine.
+  const credit = Math.min(Math.max(Number(consumedMb) || 0, 0), minPerJob * runningCount);
   let allowed = batchLen;
-  while (allowed > 0 && availableMb < minPerJob * (runningCount + allowed)) {
+  while (allowed > 0 && availableMb < minPerJob * (runningCount + allowed) - credit) {
     allowed--;
   }
   return allowed;
@@ -522,6 +533,26 @@ function biasJobOomScore(pid) {
 // source and a search fallback. Live PRDs resolve per-job to
 // `<job.cwd>/session-manager-operations/scheduler/prds/` via prdLocations.cjs.
 
+/**
+ * Last-line guard before any 'prd-missing' retire: bust the project-cwd cache
+ * and re-check every job-scoped dir plus findPrdDirForJob for
+ * `<dir>/<slug>.md`. Returns the first existing absolute path, or null. A
+ * stale allProjectCwds scan must never retire a PRD whose file exists.
+ */
+async function recheckPrdSourceForJob(job) {
+  const slug = job && job.slug;
+  if (typeof slug !== 'string' || !slug || path.basename(slug) !== slug) return null;
+  try { require('./lib/activeSessions.cjs').bustProjectCwdCache(); } catch { /* best-effort */ }
+  const dirs = [...(await prdPaths.jobScopedPrdDirs(job))];
+  const found = await prdPaths.findPrdDirForJob(job);
+  if (found) dirs.push(found);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, `${slug}.md`);
+    try { await fsp.access(candidate); return candidate; } catch { /* not here */ }
+  }
+  return null;
+}
+
 /**
  * Build the non-failure result + run meta for a queued job whose PRD source
  * is gone. Shared by both PRD-read failure exits in executeJob so the
@@ -2665,7 +2696,12 @@ async function clearPause(source) {
  */
 function resetJobFields(job, errorMsg, opts = {}) {
   if ((job.status === 'completed' || job.status === 'skipped') && opts.force !== true) return false;
+  // Durable cancel (2026-10-19 git-viewer incident): a human-cancelled row is
+  // revived only by an explicit human reset, never by an automated pass.
+  if (reviewLadder.isCancelledJob(job) && opts.source !== 'remote:resetJob' && opts.source !== 'ipc:schedule:reset-job') return false;
   if (!transitionJob(job, 'pending', { reason: errorMsg ?? 'reset to pending', source: opts.source ?? 'resetJobFields' })) return false;
+  delete job.cancelledAt;
+  delete job.cancelledRunId;
   job.runId = null;
   job.startedAt = null;
   job.finishedAt = null;
@@ -3093,6 +3129,13 @@ async function notifyOriginatingTab(job, {
         + (failures.length ? `. Pre-existing failures: ${shown}${more}` : '')
         + '. Check Scheduler for details.';
     }
+    if (job.status === 'skipped' && Array.isArray(job.blockedDependents) && job.blockedDependents.length > 0) {
+      const deps = job.blockedDependents;
+      const shown = deps.slice(0, 10).join(', ');
+      const more = deps.length > 10 ? ` (+${deps.length - 10} more)` : '';
+      message = `PRD ${job.slug} was skipped: its PRD source could not be found on disk. Blocked dependents: ${shown}${more}.`
+        + ' If the PRD file exists, run scheduler_reset_job with force:true; if it was intentionally removed, archive it with scheduler_archive_prd.';
+    }
 
     // The EPIC this check-in belongs to. Deliberately does NOT consider
     // `sourceTabId` — that is a Terminal tab id, not an Epic id, and
@@ -4142,16 +4185,21 @@ const HEADLESS_DISALLOWED_TOOLS = Object.freeze([
  * persona body, resolved by agentModelResolve.cjs's resolvePrdPersonaForSpawn),
  * is passed as `--append-system-prompt` so the executor IS that persona at
  * launch rather than being asked in prose to adopt one.
+ * `toolScope` (buildPersonaToolScope of the persona's `tools:` list; null =
+ * unscoped) adds `--agents/--agent` so the persona's tool list is enforced —
+ * `--allowedTools` is a no-op under --dangerously-skip-permissions. It is
+ * inserted BEFORE that flag, never between `--disallowedTools` and its value.
  * `--disallowedTools` takes a variadic list, so another flag must always
  * follow it to end that list — `--output-format` does, right after. Never
  * put `--disallowedTools` last or right before the prompt.
  */
-function buildClaudeSpawnArgs({ prompt, model, effort, sessionId, resume, systemPrompt }) {
+function buildClaudeSpawnArgs({ prompt, model, effort, sessionId, resume, systemPrompt, toolScope }) {
   return [
     '-p', prompt,
     '--model', model,
     ...effortArgs(effort),
     ...(systemPrompt ? ['--append-system-prompt', systemPrompt] : []),
+    ...personaToolScopeArgs(toolScope),
     '--dangerously-skip-permissions',
     ...headlessPermissionArgs(),
     '--disallowedTools', HEADLESS_DISALLOWED_TOOLS.join(','),
@@ -4289,6 +4337,26 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
   // then an ancestor-folder Epic walk above job.cwd) first, so the common
   // case — a live Epic-scoped PRD — is a first-try hit instead of probing
   // the retired flat dir and only then falling back.
+  // Shared by both 'prd-missing' exits: resolves to null (truly missing), the
+  // string 'resolved' (file found + parsed; prompt/prdPath/parsedPrdMeta set),
+  // or a ready-to-return { exitCode: -1, error } result.
+  const recheckBeforeMissingSkip = async () => {
+    const found = await recheckPrdSourceForJob(job);
+    if (!found) return null;
+    try {
+      const parsed = await parsePrd(found);
+      prompt = parsed.body;
+      prdPath = found;
+      parsedPrdMeta = parsed;
+    } catch (err) {
+      const error = `PRD exists at ${found} but could not be read: ${err?.message}`;
+      safeLog(`[scheduler] ${error}\n`);
+      closeFd();
+      return { exitCode: -1, durationMs: 0, error, sessionId };
+    }
+    safeLog(`[scheduler] PRD resolved on re-check at ${found}\n`);
+    return 'resolved';
+  };
   const resolvedDir = await prdPaths.findPrdDirForJob(job);
   prdPath = resolvedDir ? path.join(resolvedDir, `${job.slug}.md`) : prdPaths.prdPathForJob(job);
   try {
@@ -4324,11 +4392,14 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
           return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-archived');
         }
         if (e2 && e2.code === 'ENOENT') {
-          return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing');
+          const rc = await recheckBeforeMissingSkip();
+          if (rc && rc !== 'resolved') return rc;
+          if (!rc) return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing');
+        } else {
+          safeLog(`[scheduler] failed to read PRD: ${e2?.message}\n`);
+          closeFd();
+          return { exitCode: -1, durationMs: 0, error: e2?.message };
         }
-        safeLog(`[scheduler] failed to read PRD: ${e2?.message}\n`);
-        closeFd();
-        return { exitCode: -1, durationMs: 0, error: e2?.message };
       }
     } else {
       // No candidate dir has the slug at all. Case A: it was archived —
@@ -4341,11 +4412,14 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
         return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-archived');
       }
       if (e && e.code === 'ENOENT') {
-        return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing');
+        const rc = await recheckBeforeMissingSkip();
+        if (rc && rc !== 'resolved') return rc;
+        if (!rc) return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing');
+      } else {
+        safeLog(`[scheduler] failed to read PRD: ${e?.message}\n`);
+        closeFd();
+        return { exitCode: -1, durationMs: 0, error: e?.message };
       }
-      safeLog(`[scheduler] failed to read PRD: ${e?.message}\n`);
-      closeFd();
-      return { exitCode: -1, durationMs: 0, error: e?.message };
     }
   }
   } // end resumeTarget ? preamble : normal-PRD-read
@@ -4437,7 +4511,8 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
   // and is logged once by resolvePrdPersonaForSpawn itself.
   const personaResolution = await agentModelResolve.resolvePrdPersonaForSpawn({ cwd, agentType: job.agentType });
   const personaEffort = resolveEpicEffort({ cwd, agentType: job.agentType }).effort;
-  safeLog(`[scheduler] agentType=${job.agentType || '(none)'} persona=${personaResolution.personaPath || '(fallback — no persona applied)'} model=${personaResolution.model}${personaEffort ? ` effort=${personaEffort}` : ''}\n`);
+  const personaToolScope = buildPersonaToolScope(personaResolution.tools, { disallowed: HEADLESS_DISALLOWED_TOOLS });
+  safeLog(`[scheduler] agentType=${job.agentType || '(none)'} persona=${personaResolution.personaPath || '(fallback — no persona applied)'} model=${personaResolution.model}${personaEffort ? ` effort=${personaEffort}` : ''} ${personaToolScope ? `tools=${personaToolScope.tools.length} scoped` : 'tools=unscoped'}\n`);
 
   // Authoritative guarantee that buildClaudeSpawnArgs (a pure sync helper,
   // called below via withChildAndLog) sees a resolved --permission-prompts
@@ -4646,6 +4721,7 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
       sessionId,
       resume: !!resumeTarget,
       systemPrompt: personaResolution.systemPrompt,
+      toolScope: personaToolScope,
     });
     const jobSpawn = claudeSpawnTarget('job', job.slug, claudeBin, jobArgs);
 
@@ -4836,7 +4912,7 @@ function isPromotableOriginal(status) {
  */
 function healTargetForFix(fixSlug, jobs) {
   const originalSlug = fixSlug.replace(/^(\d+)-fix-/, '$1-');
-  return jobs.find((x) => x.slug === originalSlug && isPromotableOriginal(x.status)) || null;
+  return jobs.find((x) => x.slug === originalSlug && isPromotableOriginal(x.status) && !reviewLadder.isCancelledJob(x)) || null;
 }
 
 /**
@@ -5179,8 +5255,8 @@ async function spawnInvestigation(failedJob, runDir, { deadChild = null } = {})
   await mutate((s) => {
     const j = s.jobs.find((x) => x.slug === failedJob.slug);
     if (!j) return;
-    const statusEligible = j.status === 'needs_review' || j.status === 'failed';
-    const transitioned = transitionJob(j, 'investigating', { reason: 'spawning investigation probe', source: 'spawnInvestigation:start' });
+    const statusEligible = (j.status === 'needs_review' || j.status === 'failed') && !reviewLadder.isCancelledJob(j);
+    const transitioned = statusEligible && transitionJob(j, 'investigating', { reason: 'spawning investigation probe', source: 'spawnInvestigation:start' });
     liveCheck = { ok: statusEligible && transitioned, status: j.status };
   });
   if (!liveCheck.ok) {
@@ -5530,10 +5606,11 @@ function reportSchedulerError(message, slug, e) {
  *   worktreeIntegrationFailure: string|null, worktreeIntegrationDetail: object|null,
  *   mergeAutoResolved: string|null, mergeAutoResolvedPaths: string[]|null}>}
  */
-async function finalizeJobWorktree({ job, runDir, worktree, guardCwd, carriedPaths, deps = {} }) {
+async function finalizeJobWorktree({ job, runId = null, runDir, worktree, guardCwd, carriedPaths, deps = {} }) {
   const jw = deps.jobWorktree || jobWorktree;
   const uncommitted = deps.uncommittedChanges || gitTreeGuard.uncommittedChanges;
   const report = deps.reportSchedulerError || reportSchedulerError;
+  const runCancelled = deps.isRunCancelled || isRunCancelled;
   let worktreeLeftoverDirty = [];
   let salvagePatch = null;
   let worktreeIntegrationFailure = null;
@@ -5556,6 +5633,12 @@ async function finalizeJobWorktree({ job, runDir, worktree, guardCwd, carriedPat
         console.log(`[scheduler] ${job.slug}: salvaged ${salvage.bytes} byte(s) of uncommitted worktree diff to ${salvagePath}`);
       }
     }
+    if (await runCancelled(job.slug, runId)) {
+      // Cancelled mid-run: keep the commit on the job branch only.
+      appendAuditEvent('job_cancel_integration_skipped', { slug: job.slug, runId, branch: worktree.branch });
+      await jw.cleanupJobWorktree({ cwd: guardCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
+      return { worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths, integratedSha: null, cancelled: true };
+    }
     const integration = await jw.integrateJobBranch({ cwd: guardCwd, branch: worktree.branch, slug: job.slug, carriedPaths, baseBranch: worktree.baseBranch });
     if (integration.ok && integration.reason === 'carried-wip-only') {
       console.log(`[scheduler] ${job.slug}: worktree branch ${worktree.branch} touched only carried base WIP paths — skipping merge (carried-wip-only)`);
@@ -5587,7 +5670,25 @@ async function finalizeJobWorktree({ job, runDir, worktree, guardCwd, carriedPat
       await jw.cleanupJobWorktree({ cwd: guardCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
     } catch { /* already reported above */ }
   }
-  return { worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths, integratedSha };
+  return { worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths, integratedSha, cancelled: false };
+}
+
+/**
+ * True when the queue row for `slug` carries a durable cancel stamp for this
+ * exact run (`cancelledAt` + matching `cancelledRunId`). Incident 2026-10-19
+ * (git-viewer): a cancelled running PRD's commit still landed on main because
+ * finalizeJobWorktree integrated unconditionally. A read error returns false so
+ * a flaky read never strands every normal run's work. Known residual: a cancel
+ * arriving after integrateJobBranch already completed cannot un-land the commit.
+ */
+async function isRunCancelled(slug, runId) {
+  try {
+    const state = await readQueue();
+    const row = state.jobs.find((j) => j.slug === slug);
+    return !!(row && row.cancelledAt && (row.cancelledRunId ?? null) === (runId ?? null));
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -6016,7 +6117,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
     } finally {
       if (worktree.ok) {
         ({ worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths, integratedSha } =
-          await finalizeJobWorktree({ job, runDir, worktree, guardCwd, carriedPaths }));
+          await finalizeJobWorktree({ job, runId, runDir, worktree, guardCwd, carriedPaths }));
       } else {
         // In-place run (non-git cwd, cap reached, env-disabled, or a carry-over
         // failure) — there is no throwaway checkout to diff, so salvage only
@@ -6139,6 +6240,8 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
     // 20 never-executed sigma PRDs read as shipped (2026-08-30 incident).
     if (res.skipped) {
       const targetStatus = res.skipped === 'prd-missing' ? 'skipped' : 'completed';
+      /** @type {string[]} */
+      let blockedDependents = [];
       await mutate((s) => {
         const idx = s.jobs.findIndex((x) => x.slug === job.slug);
         if (idx >= 0) {
@@ -6147,9 +6250,25 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
           s.jobs[idx].exitCode = 0;
           s.jobs[idx].error = null;
           delete s.jobs[idx].runtime;
+          if (res.skipped === 'prd-missing') {
+            // Dependents wait on this slug forever once it is skipped; record
+            // them so the Epic can be told what is blocked.
+            blockedDependents = s.jobs
+              .filter((x) => x.slug !== job.slug
+                && x.cwd === job.cwd
+                && Array.isArray(x.dependsOn) && x.dependsOn.includes(job.slug)
+                && (x.status == null || x.status === 'pending' || x.status === 'needs_review'))
+              .map((x) => x.slug);
+            s.jobs[idx].blockedDependents = blockedDependents;
+          }
         }
       });
       await broadcast({ flush: true });
+      if (res.skipped === 'prd-missing' && blockedDependents.length > 0) {
+        notifyOriginatingTab({ ...job, status: 'skipped', blockedDependents }).catch((e) => {
+          console.error('[scheduler] notifyOriginatingTab error', job.slug, e);
+        });
+      }
       return;
     }
 
@@ -7342,22 +7461,34 @@ async function tickBody(gen, { bypassLoadGate }) {
     const jobBudgetMb = availableForJobs(availableMb, RESERVED_HOST_MB);
     // The slot pool already bounded `batch` (it was passed as freeSlots to
     // pickNextBatch above), so only the memory gate can narrow it further.
+    // Credit each running job's already-resident RSS (capped at its reservation)
+    // — MemAvailable is already net of it. Unknown pid / 0 MB read = no credit.
+    let consumedMb = 0;
+    if (availableMb !== Infinity) {
+      for (const j of state.jobs) {
+        if (!runningSet.has(j.slug)) continue;
+        const pid = j.runtime?.pid ?? j.pid;
+        if (!Number.isInteger(pid) || pid <= 0) continue;
+        consumedMb += Math.min(processGroupRssMb(pid), MIN_FREE_MB_PER_JOB);
+      }
+      consumedMb = Math.min(consumedMb, MIN_FREE_MB_PER_JOB * runningSet.size);
+    }
     const allowed = memoryLimitedBatchSize(
-      jobBudgetMb, MIN_FREE_MB_PER_JOB, runningSet.size, batch.length,
+      jobBudgetMb, MIN_FREE_MB_PER_JOB, runningSet.size, batch.length, consumedMb,
     );
     if (allowed === 0) {
-      const threshold = RESERVED_HOST_MB + MIN_FREE_MB_PER_JOB * (runningSet.size + 1);
-      console.log(`[scheduler] memory gate: available=${availableMb} MB < threshold=${threshold} MB (host reserve ${RESERVED_HOST_MB} + ${MIN_FREE_MB_PER_JOB}/job × ${runningSet.size + 1}) — deferring ${batch.length} job(s)`);
-      lastMemGate = { availableMb, threshold, deferred: true, at: new Date().toISOString() };
+      const threshold = RESERVED_HOST_MB + MIN_FREE_MB_PER_JOB * (runningSet.size + 1) - consumedMb;
+      console.log(`[scheduler] memory gate: available=${availableMb} MB < threshold=${threshold} MB (host reserve ${RESERVED_HOST_MB} + ${MIN_FREE_MB_PER_JOB}/job × ${runningSet.size + 1} - consumed=${consumedMb} MB) — deferring ${batch.length} job(s)`);
+      lastMemGate = { availableMb, threshold, consumedMb, deferred: true, at: new Date().toISOString() };
       return recordTick(
-        { fired: false, reason: 'memory-deferred', deferredCount: batch.length, availableMb, threshold },
-        { detail: `memory gate: ${availableMb} MB free, need ${threshold} MB`, holds },
+        { fired: false, reason: 'memory-deferred', deferredCount: batch.length, availableMb, threshold, consumedMb },
+        { detail: `memory gate: ${availableMb} MB free, need ${threshold} MB (consumed=${consumedMb} MB credited)`, holds },
       );
     }
     const gatedBatch = batch.slice(0, allowed);
     if (gatedBatch.length < batch.length) {
-      console.log(`[scheduler] memory gate: available=${availableMb} MB — clamped batch ${batch.length} → ${gatedBatch.length} (host reserve ${RESERVED_HOST_MB} + ${MIN_FREE_MB_PER_JOB}/job)`);
-      lastMemGate = { availableMb, threshold: RESERVED_HOST_MB + MIN_FREE_MB_PER_JOB * (runningSet.size + gatedBatch.length), deferred: false, clamped: true, at: new Date().toISOString() };
+      console.log(`[scheduler] memory gate: available=${availableMb} MB — clamped batch ${batch.length} → ${gatedBatch.length} (host reserve ${RESERVED_HOST_MB} + ${MIN_FREE_MB_PER_JOB}/job, consumed=${consumedMb} MB)`);
+      lastMemGate = { availableMb, threshold: RESERVED_HOST_MB + MIN_FREE_MB_PER_JOB * (runningSet.size + gatedBatch.length) - consumedMb, consumedMb, deferred: false, clamped: true, at: new Date().toISOString() };
     } else {
       // Ungated full batch: clear stale gate snapshot so status doesn't show
       // a stale deferral from a previous tick.
@@ -8499,7 +8630,7 @@ function selectHistoryJobs(jobs, limit, historyEntries = []) {
  * guard-parked row was never "exhausted auto-fix" and must never claim to be.
  */
 function applyNeedsReviewAutoResolve(j, jobsInProject = []) {
-  if (!j || j.status !== 'needs_review' || !reviewLadder.isEligibleForNeedsReviewAutoResolve(j, jobsInProject)) return null;
+  if (!j || j.status !== 'needs_review' || reviewLadder.isCancelledJob(j) || !reviewLadder.isEligibleForNeedsReviewAutoResolve(j, jobsInProject)) return null;
   if ((j.exhaustedResolveAttempts ?? 0) > reviewLadder.NEEDS_REVIEW_RESOLVE_CAP) return null;
   const originIsGuardParked = !reviewLadder.isExhaustedAutoFix(j) && reviewLadder.isGuardParkedWithoutAutoFix(j);
 
@@ -8744,12 +8875,31 @@ async function runGateShadow(job) {
   const dirtBefore = await gateTreeDirt(job.cwd);
   const gate = resolveGate(prdText);
   let outcome;
+  let mainDeps = null;
+  let repaired = false;
   if (gate.source === 'none') outcome = { status: 'unavailable', reason: 'gate-opt-out', results: [] };
   else if (!gate.sequence.length) outcome = { status: 'unavailable', reason: 'no-parseable-gate', results: [] };
   else {
-    const r = await runGateSequence(gate.sequence, { cwd: job.cwd });
-    if (r.status === 'busy') return null;
-    outcome = r;
+    let health = checkMainDependencyHealth(job.cwd);
+    if (!health.ok) {
+      const last = mainDepsRepairAt.get(job.cwd) ?? 0;
+      if (Date.now() - last >= MAIN_DEPS_REPAIR_COOLDOWN_MS) {
+        mainDepsRepairAt.set(job.cwd, Date.now());
+        const rep = await repairMainDependencies(job.cwd);
+        repaired = rep.ok;
+        console.warn(`[scheduler] main deps broken in ${job.cwd}: ${health.reason} — repair ${rep.ok ? 'ok' : 'failed'}`);
+        health = checkMainDependencyHealth(job.cwd);
+      }
+      mainDeps = { ok: health.ok, reason: health.reason ?? null, missing: health.missing ?? [], repaired };
+    }
+    if (!health.ok) {
+      const names = health.missing && health.missing.length ? `: ${health.missing.join(', ')}` : '';
+      outcome = { status: 'unavailable', reason: `main-deps-broken: ${health.reason}${names}`, results: [] };
+    } else {
+      const r = await runGateSequence(gate.sequence, { cwd: job.cwd });
+      if (r.status === 'busy') return null;
+      outcome = r;
+    }
   }
   const headAfter = await gitTreeGuard.gitHead(job.cwd);
   const dirtAfter = await gateTreeDirt(job.cwd);
@@ -8761,7 +8911,7 @@ async function runGateShadow(job) {
   // about done-ness, so it must stay eligible for retry once the PRD gains a
   // real gate. `busy` never reaches here (returns early above).
   const definitive = headStable && cleanOk && (outcome.status === 'green' || outcome.status === 'red');
-  const gateShadow = { ...outcome, head: headBefore, source: gate.source, ranAt: new Date().toISOString(), definitive };
+  const gateShadow = { ...outcome, head: headBefore, source: gate.source, ranAt: new Date().toISOString(), definitive, ...(mainDeps ? { mainDeps } : {}) };
 
   // Gate authority: a green re-run may complete the row outright, but only
   // for transcript-noise verdicts with a landed commit — every other park
@@ -9930,7 +10080,7 @@ function rescheduleIntervalTick() {
     mutate(async (ms) => {
       for (const target of autoResetTargets) {
         const j = ms.jobs.find((x) => x.slug === target.slug);
-        if (!j || j.status !== 'failed' || (j.failedAutoResetAttempts ?? 0) >= reviewLadder.FAILED_AUTORESET_CAP) continue; // race guard
+        if (!j || j.status !== 'failed' || reviewLadder.isCancelledJob(j) || (j.failedAutoResetAttempts ?? 0) >= reviewLadder.FAILED_AUTORESET_CAP) continue; // race guard
         const attempt = (j.failedAutoResetAttempts ?? 0) + 1;
         j.failedAutoResetAttempts = attempt;
         const reason = `auto-reset after ${Math.round(reviewLadder.FAILED_AUTORESET_MS / 60_000)}m failed (attempt ${attempt}/${reviewLadder.FAILED_AUTORESET_CAP})`;
@@ -10823,9 +10973,6 @@ const remote = {
     }
     const wasRunning = job.status === 'running';
     const pid = job.runtime?.pid;
-    if (wasRunning && pid) {
-      killOrphanClaudePid(pid);
-    }
     // Evidence-before-failure guard, scoped to an actually-running job being
     // killed here (a 'pending' cancel has no live process, so nothing new
     // could have landed since its last stamp — and 'needs_review' is not
@@ -10845,19 +10992,49 @@ const remote = {
     const cancelReason = confirmedLandedCommit
       ? `cancelled via admin API, but landedCommit ${confirmedLandedCommit} resolves — verify before treating as done`
       : 'cancelled via admin API';
+    const cancelledAt = new Date().toISOString();
     await mutate((s) => {
       const idx = s.jobs.findIndex((j) => j.slug === slug);
       if (idx < 0) return;
       const j = s.jobs[idx];
       transitionJob(j, targetStatus, { reason: cancelReason, source: 'remote:cancelJob' });
       j.error = cancelReason;
+      j.cancelledAt = cancelledAt;
+      if (wasRunning) j.cancelledRunId = job.runId ?? null;
       j.finishedAt = new Date().toISOString();
       j.exitCode = j.exitCode ?? null;
       if (confirmedLandedCommit) j.verifierVerdict = 'cancelled_with_landed_commit';
       delete j.runtime;
     });
+    // Stamped before SIGTERM so finalizeJobWorktree (run on executor exit) sees it.
+    if (wasRunning && pid) killOrphanClaudePid(pid);
     await broadcast({ flush: true });
-    return { ok: true, slug, status: targetStatus, wasRunning, cwd: job.cwd ?? null };
+    const result = { ok: true, slug, status: targetStatus, wasRunning, cwd: job.cwd ?? null, cancelledAt };
+    if (wasRunning) {
+      // Whatever the executor committed before SIGTERM stays on its job
+      // branch (never integrated); tell the caller where. Known residual: a
+      // cancel arriving after integration already finished reports
+      // landed:false with jobBranch:null (branch deleted after the merge).
+      let jobBranch = null;
+      let jobBranchSha = null;
+      try {
+        const branch = jobWorktree.branchNameFor(slug);
+        const stdout = await execGitAt(
+          resolveProjectRoot(job.cwd || DEFAULT_PROJECT_CWD),
+          ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`],
+          { timeout: 10_000 },
+        );
+        const sha = String(stdout || '').trim();
+        if (sha) { jobBranch = branch; jobBranchSha = sha; }
+      } catch { /* branch absent or git errored → nulls */ }
+      Object.assign(result, {
+        landed: confirmedLandedCommit != null,
+        landedCommit: confirmedLandedCommit ?? null,
+        jobBranch,
+        jobBranchSha,
+      });
+    }
+    return result;
   },
 
   // Exposes the module-level allocateParallelGroup (PRD 548) to callers that

package/src/main/templates/PRD_AUTHORING.md

@@ -1,4 +1,4 @@
-<!-- PRD_AUTHORING.md v6 -->
+<!-- PRD_AUTHORING.md v7 -->
 # PRD Authoring Guide — Scheduler Safety Rules
 
 Rule: every PRD you queue follows the rules below.
@@ -125,7 +125,7 @@ A short Epic-context digest is prepended automatically for orientation only —
 
 The executor can't ask you anything: no `ScheduleWakeup`, Cron, Monitor, `AskUserQuestion`, plan mode, or worktree tools; background tasks are off (a `timeout` command is always on PATH — the app installs a shim on macOS). It must never stop to ask a question — it makes the safest reasonable call and reports it, so write the PRD so that call is obvious.
 
-Worktree reach: every PRD runs in an isolated git worktree holding tracked files plus symlinked `node_modules`/`.venv`/`venv` only. A step that needs gitignored runtime state (databases, `downloads/`, browser profiles, logs) or a live side effect must address the main checkout by absolute path (e.g. `$HOME/Projects/<repo>/...`), be artifact-only (a deliverable artifact + `artifactPaths`, no tracked edits), and `dependsOn` the PRD that lands its tracked edits. Host crontab installs stay human-only (see §15).
+Worktree reach: every PRD runs in an isolated git worktree holding tracked files plus `.venv`/`venv` (and `node_modules` for non-pnpm projects) symlinked from the main checkout; pnpm projects (pnpm-lock.yaml) get a worktree-local `node_modules` installed offline from the store. Why: a pnpm install through the symlink purged the main checkout's node_modules (Bilko-Game-Academy 2026-10-18). A step that needs gitignored runtime state (databases, `downloads/`, browser profiles, logs) or a live side effect must address the main checkout by absolute path (e.g. `$HOME/Projects/<repo>/...`), be artifact-only (a deliverable artifact + `artifactPaths`, no tracked edits), and `dependsOn` the PRD that lands its tracked edits. Host crontab installs stay human-only (see §15).
 Why: burrow PRD 1516 halted because its relative `.venv` python against `downloads/fb-tracker.db`, `scripts/install-cron.sh` and `pipeline-cron.sh --now` resolved inside the worktree (no runtime state; install-cron would bake a temporary worktree path into crontab), while sibling 1494 succeeded the same day using an absolute main-checkout path and artifact-only output. `scheduler_create_prd` warns on relative gitignored paths.
 
 ---