claude-code-session-manager 0.79.0 → 0.81.0

package/src/main/lib/rcaReport.cjs

@@ -52,6 +52,7 @@ const VERDICT_LABELS = {
   pass_no_commit_already_shipped: 'PASS with no commit — deliverables already shipped',
   pass_no_commit_prior_run_verified: 'PASS with no commit — prior run of this slug already landed the work',
   silent_no_op: 'no commit, clean tree — no evidence of work',
+  blocked_by_foreign_wip_streak: 'blocked by a sibling job\'s foreign WIP 3x in a row',
 };
 
 function humanVerdict(verdict) {
@@ -69,14 +70,18 @@ const FAILURE_CLASSES = {
   UNCOMMITTED: 'uncommitted-changes',
   TRANSCRIPT_ERRORS: 'transcript-errors',
   ABANDONED_BACKGROUND_TASK: 'abandoned-background-task',
+  BLOCKED_BY_FOREIGN_WIP: 'blocked-by-foreign-wip',
   UNKNOWN: 'unknown',
 };
 
 // ─── Recovery actions — one per failure class, machine-readable ────────────
 // Closed set the scheduler routes on: 'archive' (stale re-run, do not
-// re-queue), 'resume-and-commit' (PRD 1111's --resume dispatch owns this),
-// 'verify-and-close' (the work likely landed, just missing its sentinel),
-// 'investigate' (the only class that still buys a fix-plan investigation).
+// re-queue — also the closest fit for BLOCKED_BY_FOREIGN_WIP: there is
+// nothing to investigate, and re-queuing is already owned by
+// reconcile()'s requeueForeignWipBlockedJobs, not this action), 'resume-and-commit'
+// (PRD 1111's --resume dispatch owns this), 'verify-and-close' (the work
+// likely landed, just missing its sentinel), 'investigate' (the only class
+// that still buys a fix-plan investigation).
 const RECOVERY_ACTIONS = {
   [FAILURE_CLASSES.ALREADY_SHIPPED]: 'archive',
   [FAILURE_CLASSES.SELF_QUEUE]: 'investigate',
@@ -96,6 +101,7 @@ const RECOVERY_ACTIONS = {
   // carries the "check for salvaged work, commit before re-implementing"
   // guidance into that cold-read investigation.
   [FAILURE_CLASSES.ABANDONED_BACKGROUND_TASK]: 'investigate',
+  [FAILURE_CLASSES.BLOCKED_BY_FOREIGN_WIP]: 'archive',
   [FAILURE_CLASSES.UNKNOWN]: 'investigate',
 };
 
@@ -121,6 +127,8 @@ const PREVENTION_HINTS = {
     'Recover or annotate every error within ~10 lines (e.g. `# expected/handled: <why>`) instead of leaving a bare Traceback near the end of the transcript.',
   [FAILURE_CLASSES.ABANDONED_BACKGROUND_TASK]:
     'A headless run cannot receive a background-task completion notification — never let a long Bash command auto-background past its foreground timeout and then wait for it. Run long commands with an explicit bound (`timeout <N> <cmd>`) so they finish in the foreground, or poll their output file directly instead of waiting on Monitor/notification.',
+  [FAILURE_CLASSES.BLOCKED_BY_FOREIGN_WIP]:
+    'This job correctly reported `SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP` against a sibling job\'s in-flight, uncommitted files three times in a row — auto-requeue is exhausted (reconcile() only clears this once the blocked paths go clean). This is not a defect in this PRD\'s own work: check on the sibling job/human that owns the still-dirty path(s) named on the job row, and either wait for them to commit or manually reset this job to `pending` once the tree is clear. Do not author a fix-plan PRD against it.',
   [FAILURE_CLASSES.UNKNOWN]:
     'Re-run the acceptance criteria gate locally against the failure log to pin down the specific break before re-queuing.',
 };
@@ -159,6 +167,13 @@ const POST_AC_OVERRUN_MIN_TAIL_FRACTION = 0.3;
 function classifyFailure({ verdict, logTail }) {
   const lines = (logTail || '').split('\n');
 
+  // Checked before every other rule: an unambiguous, materially-checked
+  // verdict (the scheduler itself validated the executor's claimed paths
+  // against the job's disclosed foreign-WIP manifest before ever landing
+  // this verdict — see validateForeignWipBlockClaim in scheduler.cjs) needs
+  // no log-tail heuristics to classify.
+  if (verdict === 'blocked_by_foreign_wip_streak') return FAILURE_CLASSES.BLOCKED_BY_FOREIGN_WIP;
+
   // Checked first, before SELF_QUEUE/STUCK_LOOP: a correct executor that finds
   // its acceptance criteria already satisfied by a prior commit makes no
   // change and truthfully prints a PASS sentinel, so the run lands

package/src/main/lib/reaperHelpers.cjs

@@ -8,6 +8,7 @@
  */
 
 const fs = require('node:fs');
+const path = require('node:path');
 const { readTail } = require('./fileTail.cjs');
 const { detectRateLimitInLog } = require('./rateLimitDetect.cjs');
 
@@ -34,6 +35,90 @@ function claudePidAlive(pid) {
   }
 }
 
+/**
+ * findLiveProcessForJob(job, { worktreeDir }) → pid | null
+ *
+ * Positive liveness scan for a 'running' row whose `runtime.pid` is missing —
+ * the case a missing pid must NOT be read as "the process is gone" (2026-09-06
+ * incident: 234-uranus-eight-tails-ox marked failed/never_ran while PID
+ * 2174739 was a live `claude -p` still writing to that job's own worktree).
+ *
+ * Linux-`/proc` only. Scans every numeric `/proc/<pid>` entry and matches
+ * either: `/proc/<pid>/cwd` resolves to `worktreeDir` (or a path nested under
+ * it), or `/proc/<pid>/cmdline` contains both `claude` and the job's slug
+ * (fallback for a worktree-disabled/in-place run, where there is no dedicated
+ * worktreeDir to match against). Returns the first matching pid, or null if
+ * none is found.
+ *
+ * Safe fallback by construction: on any platform without `/proc` (macOS,
+ * Windows) `fs.readdirSync('/proc')` throws and this returns null immediately
+ * — i.e. exactly today's behaviour (fail toward terminalizing), never a hang
+ * or a thrown error propagating to the caller.
+ */
+function findLiveProcessForJob(job, { worktreeDir } = {}) {
+  const slug = job?.slug;
+  let entries;
+  try {
+    entries = fs.readdirSync('/proc');
+  } catch {
+    return null;
+  }
+  for (const name of entries) {
+    if (!/^\d+$/.test(name)) continue;
+    const pid = Number(name);
+    if (!pid || pid <= 1) continue;
+    if (worktreeDir) {
+      try {
+        const cwdLink = fs.readlinkSync(`/proc/${pid}/cwd`);
+        if (cwdLink === worktreeDir || cwdLink.startsWith(worktreeDir + path.sep)) return pid;
+      } catch {
+        // Process exited mid-scan, or permission denied — try the argv
+        // fallback below before giving up on this pid.
+      }
+    }
+    if (slug) {
+      try {
+        const cmd = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
+        if (/\bclaude\b/.test(cmd) && cmd.includes(slug)) return pid;
+      } catch {
+        // Same as above — process gone or unreadable, keep scanning.
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * True when `logPath` exists and has non-zero content — the literal "did the
+ * run dir produce any log output" check that gates whether a pidless reap may
+ * assert `gateOutcome: 'never_ran'`. A run whose log has real bytes in it DID
+ * run, regardless of whether classifyRunOutcome found a clean result event in
+ * it — asserting never_ran in that case would be a false claim (see
+ * resolvePidlessGateOutcome below).
+ */
+function logHasOutput(logPath) {
+  if (!logPath) return false;
+  try {
+    return fs.statSync(logPath).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Gate-outcome for a pidless reap, once no live process was found for it.
+ * `never_ran` is asserted ONLY when the run dir produced no log output at
+ * all — mapOutcomeToGateOutcome's own 'no_result' → 'never_ran' mapping is
+ * otherwise too broad here: a log with real content but no clean result event
+ * (e.g. killed mid-turn) proves the job DID run, so that case is reported as
+ * 'failed' instead of the false 'never_ran'.
+ */
+function resolvePidlessGateOutcome(outcome, hasOutput) {
+  if (!hasOutput) return 'never_ran';
+  const mapped = mapOutcomeToGateOutcome(outcome);
+  return mapped === 'never_ran' ? 'failed' : mapped;
+}
+
 /**
  * Classify the terminal outcome of a completed run by reading the last 64 KB
  * of its log file and scanning for the LAST `{"type":"result"}` JSONL event.
@@ -129,10 +214,21 @@ const ORPHAN_REQUEUE_CAP = 5;
  * A pidless row whose `startedAt` is missing or unparseable is neither
  * reaped nor skipped silently — age can't be proven, so it is surfaced in
  * `warnings` instead (the caller logs it) and left alone.
+ *
+ * `findLiveProcess` (optional, `(job) → pid | null`) is consulted for a
+ * pidless row ONLY once its age clears `grace` — i.e. right before it would
+ * otherwise be terminalized. A pid it finds means the process is actually
+ * alive despite the missing runtime.pid record: the row is diverted into
+ * `recovered` (never `reapable`) so the caller can re-stamp the pid and leave
+ * the row `running`, instead of terminalizing a job that is still doing real
+ * work (2026-09-06 incident — see findLiveProcessForJob's header). Omitting
+ * `findLiveProcess` (existing callers/tests) preserves prior behaviour
+ * exactly: every pidless row past grace reaps, none are ever recovered.
  */
-function selectReapableJobs(jobs, now, { pidAlive, grace } = {}) {
+function selectReapableJobs(jobs, now, { pidAlive, grace, findLiveProcess } = {}) {
   const reapable = [];
   const warnings = [];
+  const recovered = [];
   for (const j of jobs ?? []) {
     if (j.status !== 'running') continue;
     const pid = j.runtime?.pid;
@@ -148,6 +244,11 @@ function selectReapableJobs(jobs, now, { pidAlive, grace } = {}) {
     }
     const ageMs = now - startedAt;
     if (ageMs < grace) continue; // spawn may still be mid-flight
+    const livePid = typeof findLiveProcess === 'function' ? findLiveProcess(j) : null;
+    if (livePid) {
+      recovered.push({ slug: j.slug, pid: livePid });
+      continue;
+    }
     reapable.push({
       slug: j.slug,
       pid: null,
@@ -155,7 +256,72 @@ function selectReapableJobs(jobs, now, { pidAlive, grace } = {}) {
       reason: `reaped: no runtime.pid recorded after ${Math.round(grace / 60_000)}m — spawn never completed`,
     });
   }
-  return { reapable, warnings };
+  return { reapable, warnings, recovered };
+}
+
+/**
+ * isAlreadySatisfiedOnMain(commits) → { sha, verdict, reason } | null
+ *
+ * Pure decision layer for the finish-protocol commit-guard's second,
+ * independently-evidenced route to 'completed' (PRD 1136). The commit-guard
+ * in scheduler.cjs parks a clean exit / no-commit / clean-tree run as
+ * `needs_review` ("finish protocol incomplete") because that shape is
+ * normally the strongest signal that nothing happened — but it is also
+ * exactly the shape a run produces when its PRD's work was ALREADY merged to
+ * main before the run dispatched (2026-09-06: 1133-reaper-must-verify-
+ * integration-before-completed and 1134-land-stranded-sm-job-branches, both
+ * false-negatived this way and then auto-fix-minted a redundant `-fix-`
+ * child against a codebase where the change was already present).
+ *
+ * Takes the already-git-queried list of commit SHAs (newest first, caller's
+ * job — see scheduler.cjs's findSatisfyingCommitOnMain) that are reachable
+ * from `main`, newer than the job's `queuedAt`, and touch the PRD's own
+ * declared paths. Returns the winning verdict naming the satisfying sha, or
+ * `null` when there is no such commit — the caller must then leave the
+ * existing 'finish protocol incomplete' → needs_review verdict untouched.
+ * This function never widens what counts as evidence; it only decides what
+ * to do once the caller's git query has already proven a satisfying commit
+ * exists, so it can never turn a genuine no-op into a false 'completed'.
+ */
+function isAlreadySatisfiedOnMain(commits) {
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+  const sha = commits[0];
+  return {
+    sha,
+    verdict: 'already_satisfied_on_main',
+    reason: `already satisfied by ${sha} — a commit on main newer than this run's queuedAt already touches this PRD's declared paths`,
+  };
+}
+
+/**
+ * resolveCommitGuardOutcome(guardVerdict, satisfyingCommits) → verdict | null
+ *
+ * The full finalize-time decision this PRD adds: takes commitGuardVerdict's
+ * own output (scheduler.cjs) plus the already-git-queried satisfying-commit
+ * list (scheduler.cjs's findSatisfyingCommitOnMain) and decides which verdict
+ * actually wins. Only ever touches the 'silent_no_op' shape — a guardVerdict
+ * of null (no violation) or 'uncommitted_changes' (real dirt left behind)
+ * passes through completely untouched, so this can never weaken the
+ * uncommitted-changes guarantee PRD 1133 introduced. Pure — no I/O, no git —
+ * so the whole finalize decision is directly unit-testable without spawning
+ * a real job.
+ */
+function resolveCommitGuardOutcome(guardVerdict, satisfyingCommits) {
+  if (!guardVerdict || guardVerdict.verdict !== 'silent_no_op') return guardVerdict ?? null;
+  const satisfied = isAlreadySatisfiedOnMain(satisfyingCommits);
+  if (!satisfied) return guardVerdict;
+  return { verdict: satisfied.verdict, reason: satisfied.reason, satisfyingSha: satisfied.sha };
 }
 
-module.exports = { claudePidAlive, classifyRunOutcome, mapOutcomeToGateOutcome, ORPHAN_REQUEUE_CAP, selectReapableJobs };
+module.exports = {
+  claudePidAlive,
+  classifyRunOutcome,
+  mapOutcomeToGateOutcome,
+  ORPHAN_REQUEUE_CAP,
+  selectReapableJobs,
+  findLiveProcessForJob,
+  logHasOutput,
+  resolvePidlessGateOutcome,
+  isAlreadySatisfiedOnMain,
+  resolveCommitGuardOutcome,
+};

package/src/main/lib/scheduleJobTransitions.cjs

@@ -41,13 +41,26 @@ const STATUS_HISTORY_CAP = 20;
  * Explicit from->to edges. Every real assignment site in scheduler.cjs maps
  * onto one of these (verified against the 16 sites this module replaces):
  *  - pending->running (dispatch), pending->completed (archived-PRD skip,
- *    manual archive of an already-shipped PRD), pending->failed (admin
- *    cancelJob on a not-yet-started job)
+ *    manual archive of an already-shipped PRD; also source
+ *    'spawnJob:dispatch-sidecar-reconcile' — a pending row about to
+ *    dispatch whose newest run-sidecar already shows a completed-equivalent
+ *    outcome finished at/after this row's own last pending transition is
+ *    finalized from that sidecar instead of spawning a redundant re-run;
+ *    2026-09-06 incident: a silently-dropped finalize left a slug 'pending'
+ *    forever and the dispatcher re-fired it three times), pending->failed
+ *    (admin cancelJob on a not-yet-started job)
  *  - running->completed|failed|needs_review (normal run outcomes, reaper),
  *    running->skipped (spawnJob:skip-archived's 'prd-missing' case — no
  *    executor ever ran; kept distinct from 'completed' so unrun work can't
  *    read as shipped), running->pending (halt/rate-limit reset,
- *    transient-failure retry)
+ *    transient-failure retry). Also reached with verdict
+ *    'reaped_without_integration' (source 'reapDeadRunningJobs', PRD 1133): a
+ *    reaped job whose result event looked successful but whose work cannot
+ *    be shown to have landed — a worktree branch still holding unmerged
+ *    commits, or an in-place run whose HEAD never advanced during the run
+ *    window — is parked here instead of 'completed', naming the branch (or
+ *    the lack of any commit) so the stranded work is never silently treated
+ *    as shipped.
  *  - investigating->failed|needs_review (restore prior status once the
  *    investigation probe exits), investigating->completed (defensive: the
  *    restored prior status could in principle be 'completed' if a caller
@@ -61,7 +74,17 @@ const STATUS_HISTORY_CAP = 20;
  *    declared paths is surfaced to a human as needs_review, never silently
  *    auto-completed)
  *  - needs_review->investigating, needs_review->pending, needs_review->completed
- *    (heal on reverify, or auto-promote) — same shape as `failed`
+ *    (heal on reverify, or auto-promote) — same shape as `failed`. Also
+ *    reached by source 'scheduler:mechanicalRecovery' (PRD 1130): a job
+ *    parked with a mechanically-resolvable verdict (starting with exactly
+ *    'worktree_integration_failed') gets one bounded, model-free re-attempt
+ *    of its worktree branch integration; success lands here exactly like any
+ *    other completion.
+ *  - needs_review->running (resume-first recovery, PRD 1111: a job parked
+ *    needs_review with verdict 'uncommitted_changes' gets one bounded
+ *    `claude -p --resume` dispatch through spawnJob before any fix-plan
+ *    investigation is authored — spawnJob's own dispatch mutate transitions
+ *    straight to 'running', same as any pending job)
  *  - completed->pending (force-only reset, gated separately by
  *    resetJobFields' own guard — this table only says the edge is
  *    structurally legal, not that every caller may take it unconditionally)
@@ -85,7 +108,7 @@ const LEGAL_TRANSITIONS = {
   running: ['completed', 'failed', 'needs_review', 'skipped', 'pending'],
   investigating: ['failed', 'needs_review', 'completed', 'pending', 'skipped'],
   failed: ['investigating', 'pending', 'completed', 'needs_review'],
-  needs_review: ['investigating', 'pending', 'completed', 'skipped'],
+  needs_review: ['investigating', 'pending', 'completed', 'skipped', 'running'],
   completed: ['pending'],
   skipped: ['pending'],
   quarantined: ['pending', 'skipped'],

package/src/main/lib/schedulerBatch.cjs

@@ -15,37 +15,98 @@
 const path = require('node:path');
 const os = require('node:os');
 const { projectJobCap, quietMachineWaitMs } = require('./schedulerConfig.cjs');
+const { bareSlug } = require('./depSlugResolve.cjs');
 
 const DEFAULT_PROJECT_CWD = path.join(os.homedir(), 'Projects', 'session-manager');
 
+/**
+ * Sentinel passed as `satisfiedSlugs` when the caller's history/archive
+ * lookup itself failed this tick (PRD 1122's fail-open-on-read-failure
+ * clause) — every dep with no live row is treated as satisfied, exactly
+ * today's pre-1122 behaviour, rather than holding the whole queue hostage to
+ * a transient fs error. Never returned BY this module — only ever supplied
+ * by a caller (scheduler.cjs's computeDepHistorySatisfaction) that caught an
+ * I/O error building the real Set.
+ */
+const DEP_HISTORY_FAIL_OPEN = Symbol('dep-history-fail-open');
+
 /**
  * The dep slug (if any) blocking `job` from running, per PRD 832's
- * dependsOn semantics — a dep is blocking while a queue row for it exists
- * in a non-completed state; a slug with no row is treated as already done
- * (completed rows are retired to history shards). Resolves a dep by exact
- * slug first, then by bare-name match (a human-authored `dependsOn:` can't
- * know the `NN-` prefix the allocator will hand a sibling PRD — see
- * pickForProject's own comment on this for the incident it fixes).
+ * dependsOn semantics, refined by PRD 1122: a dep is blocking while a queue
+ * row for it exists in a non-completed state. A dep slug with NO live row is
+ * NOT automatically treated as done — it is checked against `satisfiedSlugs`
+ * (built ONCE per tick by the caller from scheduler `state/history.jsonl`
+ * and/or `prds-archived/`, per PRD 1122's once-per-tick requirement; pass
+ * `DEP_HISTORY_FAIL_OPEN` to fall back to the old blanket-satisfied
+ * behaviour when that lookup itself failed). A dep absent from BOTH live
+ * rows and `satisfiedSlugs` blocks — pickForProject surfaces this as a
+ * distinct 'unresolved' hold rather than silently dispatching the dependent
+ * (see PRD 1122: a typo'd or double-prefixed dependsOn entry used to be
+ * indistinguishable from a dep that genuinely finished and aged out to
+ * history).
+ *
+ * Resolves a dep by exact slug first, then by bare-name match (a
+ * human-authored `dependsOn:` can't know the `NN-` prefix the allocator will
+ * hand a sibling PRD — see pickForProject's own comment on this for the
+ * incident it fixes) — the SAME rule applies when matching against
+ * `satisfiedSlugs`, so a bare-named dep resolves against a prefixed history
+ * slug the same way it would against a live row.
+ *
  * Shared by pickForProject (per-project gating) and pickNextBatch's
  * quiet-machine dispatch check (PRD 1107), so the two can never disagree
  * about whether a job is eligible.
  */
-function findBlockingDep(job, projectJobs) {
+/**
+ * De-duplicate dependsOn-cycle reports (PRD 1123). Two jobs sitting in the
+ * same 2-node cycle each independently discover it while walking upward from
+ * their own row, so without this the same cycle would surface once per
+ * member instead of once per distinct cycle.
+ */
+function dedupeCycles(cycles) {
+  const seen = new Set();
+  const out = [];
+  for (const members of cycles) {
+    const uniq = [...new Set(members)].sort();
+    const key = uniq.join('|');
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(uniq);
+  }
+  return out;
+}
+
+function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
   const rowBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
   const rowsByBareSlug = new Map();
   for (const j of projectJobs) {
-    const bare = String(j.slug ?? '').replace(/^\d+-/, '');
+    const bare = bareSlug(j.slug);
     if (!rowsByBareSlug.has(bare)) rowsByBareSlug.set(bare, []);
     rowsByBareSlug.get(bare).push(j);
   }
   const rowsForDep = (slug) => {
     const exact = rowBySlug.get(slug);
     if (exact) return [exact];
-    return rowsByBareSlug.get(String(slug ?? '').replace(/^\d+-/, '')) ?? [];
+    return rowsByBareSlug.get(bareSlug(slug)) ?? [];
   };
-  return (job.dependsOn ?? []).find((slug) => (
-    rowsForDep(slug).some((dep) => dep.status !== 'completed')
-  ));
+  // Bare-name fallback applies here too: a satisfiedSlugs entry is almost
+  // always the FULL NN-prefixed slug (a history.jsonl row or an archived
+  // `<slug>.md` filename), but a human-authored dependsOn: writes the bare
+  // name — same asymmetry findBlockingDep already resolves for live rows.
+  let satisfiedBareSlugs = null;
+  const isKnownSatisfied = (slug) => {
+    if (satisfiedSlugs === DEP_HISTORY_FAIL_OPEN) return true;
+    if (satisfiedSlugs.has(slug)) return true;
+    if (satisfiedBareSlugs === null) {
+      satisfiedBareSlugs = new Set();
+      for (const s of satisfiedSlugs) satisfiedBareSlugs.add(bareSlug(s));
+    }
+    return satisfiedBareSlugs.has(bareSlug(slug));
+  };
+  return (job.dependsOn ?? []).find((slug) => {
+    const rows = rowsForDep(slug);
+    if (rows.length > 0) return rows.some((dep) => dep.status !== 'completed');
+    return !isKnownSatisfied(slug);
+  });
 }
 
 /**
@@ -78,18 +139,28 @@ function findBlockingDep(job, projectJobs) {
  *   runningSet that belong to this project.
  * @param {number} slots - Maximum jobs to return (global remaining slots;
  *   caller enforces the global cap across projects).
+ * @param {Map<string,string>} [heldSlugs] - Launch-gate holds, see below.
+ * @param {Set<string>|symbol} [satisfiedSlugs] - Dep slugs with no live queue
+ *   row that are nonetheless known-satisfied (found in scheduler
+ *   `state/history.jsonl` and/or `prds-archived/`), built ONCE per tick by
+ *   the caller (PRD 1122) — or `DEP_HISTORY_FAIL_OPEN` when that lookup
+ *   itself failed this tick. Defaults to an empty Set (fail CLOSED: a dep
+ *   with no live row and nothing in this set is genuinely unresolved).
  * @returns {{ batch: object[], reason: string | null }} Jobs to spawn for this
  *   project this tick, plus (when batch is empty because a gate held it) the
  *   human-readable reason text that would otherwise only reach console.log.
  */
-function pickForProject(projectJobs, runningSlugsInProject, slots, heldSlugs = new Map()) {
+function pickForProject(projectJobs, runningSlugsInProject, slots, heldSlugs = new Map(), satisfiedSlugs = new Set()) {
   const projectCwd = (projectJobs.find((j) => j.cwd) || {}).cwd || DEFAULT_PROJECT_CWD;
 
-  // Explicit dependsOn eligibility (PRD 832). A dep slug is BLOCKING while a
-  // queue row for it exists in a non-completed state; a slug with no row is
-  // treated as already done (completed rows are retired to history shards,
-  // so absence is the normal end-state of a finished dep). A FAILED dep
-  // holds the dependent with an explicit reason, mirroring the failure gate.
+  // Explicit dependsOn eligibility (PRD 832, refined by PRD 1122). A dep slug
+  // is BLOCKING while a queue row for it exists in a non-completed state. A
+  // slug with NO row is only treated as done when `satisfiedSlugs` (this
+  // tick's precomputed history/archive lookup — see findBlockingDep's own
+  // doc) says so; otherwise it HOLDS as 'unresolved' — see PRD 1122: a typo
+  // or a double-prefixed slug used to be silently indistinguishable from a
+  // dep that genuinely finished and aged out to history. A FAILED dep holds
+  // the dependent with an explicit reason, mirroring the failure gate.
   // Legacy jobs without dependsOn keep the shared-NN group semantics below
   // unchanged (lowest-number-first waves), so an in-flight mixed queue keeps
   // its order without migration.
@@ -111,7 +182,32 @@ function pickForProject(projectJobs, runningSlugsInProject, slots, heldSlugs = n
     const bare = String(slug ?? '').replace(/^\d+-/, '');
     return projectJobs.filter((j) => String(j.slug ?? '').replace(/^\d+-/, '') === bare);
   };
-  const blockingDep = (j) => findBlockingDep(j, projectJobs);
+  const blockingDep = (j) => findBlockingDep(j, projectJobs, satisfiedSlugs);
+  const depStatusOf = (rows) => (rows.length === 0 ? 'unresolved' : (rows.find((d) => d.status !== 'completed')?.status ?? 'unknown'));
+
+  // Root-blocker walk (PRD 1123): follows dependsOn upward from a held job
+  // until it reaches a row with no blocking dep of its own — the ACTUAL
+  // cause of a stalled chain, not just the immediate link the held job
+  // names (which is very often just another `pending` row, not the reason
+  // the chain isn't moving). Bounded by `visited`, which doubles as the
+  // cycle guard: a dependsOn cycle can never grow `visited` past
+  // `projectJobs.length` without revisiting a node, so this always
+  // terminates instead of recursing forever.
+  function findRootBlocker(startJob) {
+    const visited = new Set([startJob.slug]);
+    let current = startJob;
+    for (let hops = 0; hops <= projectJobs.length; hops += 1) {
+      const dep = blockingDep(current);
+      if (!dep) return { rootSlug: current.slug, rootStatus: current.status, cycle: false };
+      const rows = rowsForDep(dep);
+      if (rows.length === 0) return { rootSlug: dep, rootStatus: 'unresolved', cycle: false };
+      const nextRow = rows.find((r) => r.status !== 'completed') ?? rows[0];
+      if (visited.has(nextRow.slug)) return { cycle: true, members: [...visited, nextRow.slug] };
+      visited.add(nextRow.slug);
+      current = nextRow;
+    }
+    return { cycle: true, members: [...visited] }; // unreachable given the bound above; never hang.
+  }
 
   // quietMachine jobs (PRD 1107) never dispatch through the ordinary
   // per-project picker — pickNextBatch's dedicated quiet-machine check
@@ -141,6 +237,20 @@ function pickForProject(projectJobs, runningSlugsInProject, slots, heldSlugs = n
   // the generic `holds` bucket — resetting won't help here (the source file
   // is gone), so the guidance differs from the failed-dep case.
   const heldBySkippedDep = [];
+  // A dep with NO live row anywhere and no completion record either (PRD
+  // 1122) — a typo'd or double-prefixed dependsOn entry, indistinguishable
+  // at write time from a dep that finished and aged out, until now.
+  const heldByUnresolvedDep = [];
+  // Deeper root causes the shallow (immediate-dep) buckets above can't see —
+  // PRD 1123. A job's own immediate dep is very often just another `pending`
+  // row; the ROOT is the transitive ancestor that isn't blocked by anything
+  // itself. Keyed by that root's slug so the reason names ONE row and the
+  // count of everything transitively held behind it, rather than restating
+  // "held by a pending dep" once per link in the chain (which is exactly how
+  // a stalled needs_review row several hops down used to read as generic
+  // starvation instead of a named, actionable blocker).
+  const heldByRoot = new Map(); // rootSlug -> { rootStatus, slugs: Set<string> }
+  const cycles = [];
   // Per-job hold records, surfaced to the UI so a `pending` row can say WHICH
   // dep is holding it instead of leaving the reason in console.log.
   const holds = [...launchHolds];
@@ -148,16 +258,34 @@ function pickForProject(projectJobs, runningSlugsInProject, slots, heldSlugs = n
     const dep = blockingDep(j);
     if (!dep) { pending.push(j); continue; }
     const depRows = rowsForDep(dep);
+    const root = findRootBlocker(j);
+    if (root.cycle) {
+      cycles.push(root.members);
+      holds.push({ slug: j.slug, dep, depStatus: depStatusOf(depRows), rootSlug: null, rootStatus: 'cycle' });
+      continue;
+    }
+    if (depRows.length === 0) {
+      heldByUnresolvedDep.push({ job: j, dep });
+      holds.push({ slug: j.slug, dep, depStatus: 'unresolved', rootSlug: root.rootSlug, rootStatus: root.rootStatus });
+      continue;
+    }
     const failed = depRows.some((d) => d.status === 'failed');
     const skipped = depRows.some((d) => d.status === 'skipped');
     if (failed) heldByFailedDep.push({ job: j, dep });
     else if (skipped) heldBySkippedDep.push({ job: j, dep });
+    else if (['failed', 'skipped', 'needs_review', 'unresolved'].includes(root.rootStatus)) {
+      if (!heldByRoot.has(root.rootSlug)) heldByRoot.set(root.rootSlug, { rootStatus: root.rootStatus, slugs: new Set() });
+      heldByRoot.get(root.rootSlug).slugs.add(j.slug);
+    }
     holds.push({
       slug: j.slug,
       dep,
-      depStatus: depRows.find((d) => d.status !== 'completed')?.status ?? 'unknown',
+      depStatus: depStatusOf(depRows),
+      rootSlug: root.rootSlug,
+      rootStatus: root.rootStatus,
     });
-    // running/pending/needs_review dep — simply not eligible this tick.
+    // running/pending dep with a running/pending root — simply not eligible
+    // this tick; expected to clear on its own, not a stall worth naming.
   }
   if (pending.length === 0) {
     const reasons = [];
@@ -169,6 +297,25 @@ function pickForProject(projectJobs, runningSlugsInProject, slots, heldSlugs = n
       const detail = heldBySkippedDep.map(({ job, dep }) => `${job.slug} <- ${dep}`).join(', ');
       reasons.push(`holding ${heldBySkippedDep.length} job(s) behind never-ran dependencies [${detail}]. The dep's PRD source is gone — author a fresh PRD for that work to unblock.`);
     }
+    if (heldByUnresolvedDep.length > 0) {
+      const detail = heldByUnresolvedDep.map(({ job, dep }) => `${job.slug} <- ${dep}`).join(', ');
+      reasons.push(`holding ${heldByUnresolvedDep.length} job(s) behind unresolvable dependencies [${detail}]. The dep slug matches no live queue row and no completion record in history/archive — fix the dependsOn entry or archive the dependent.`);
+    }
+    for (const [rootSlug, { rootStatus, slugs }] of heldByRoot) {
+      const names = [...slugs].sort().join(', ');
+      if (rootStatus === 'needs_review') {
+        reasons.push(`holding ${slugs.size} job(s) transitively behind root blocker ${rootSlug} (needs_review) [${names}]. ${rootSlug} is a QUESTION awaiting a human — the chain resumes once it is retired or reset; it will not clear on its own.`);
+      } else if (rootStatus === 'failed') {
+        reasons.push(`holding ${slugs.size} job(s) transitively behind root blocker ${rootSlug} (failed) [${names}]. Reset or archive ${rootSlug} to unblock the chain.`);
+      } else if (rootStatus === 'skipped') {
+        reasons.push(`holding ${slugs.size} job(s) transitively behind root blocker ${rootSlug} (skipped) [${names}]. ${rootSlug}'s PRD source is gone — author a fresh PRD for that work to unblock the chain.`);
+      } else {
+        reasons.push(`holding ${slugs.size} job(s) transitively behind unresolvable root blocker ${rootSlug} (status: ${rootStatus}) [${names}]. Fix the dependsOn chain or archive the dependent(s).`);
+      }
+    }
+    for (const members of dedupeCycles(cycles)) {
+      reasons.push(`dependsOn CYCLE detected among [${members.join(' -> ')}] — these jobs can never become eligible; break the cycle by editing one PRD's dependsOn.`);
+    }
     if (reasons.length > 0) {
       const reason = `[scheduler] depends-gate [${projectCwd}]: ${reasons.join(' ')}`;
       console.log(reason);
@@ -293,6 +440,14 @@ function enqueueTimestamp(job) {
  *     NOW (scheduler jobs AND chat runs). A quiet-machine job only dispatches
  *     when this is 0, unless it has waited past quietMachineWaitMs().
  *   - now: ms epoch, defaults to Date.now() (injectable for tests).
+ *   - satisfiedSlugsByCwd: `Map<cwd, Set<string>|symbol>` — this tick's
+ *     precomputed dependsOn history/archive lookup (PRD 1122), built ONCE by
+ *     the caller (scheduler.cjs's computeDepHistorySatisfaction) before this
+ *     function runs, never inside it. Per-cwd value is either a Set of
+ *     satisfied slugs or `DEP_HISTORY_FAIL_OPEN` when that project's lookup
+ *     itself failed this tick. Missing entry for a cwd defaults to an empty
+ *     Set (fail closed). Threaded to findBlockingDep everywhere it's called
+ *     below — pickForProject and the quiet-machine check both need it.
  * @returns {{ batch: object[], reason: string | null, holds: object[] }} Jobs
  *   to spawn this tick, plus (when batch is empty because a gate held it) the
  *   human-readable hold reason that would otherwise only reach console.log.
@@ -303,6 +458,8 @@ function pickNextBatch(allJobs, running, freeSlots, quietOpts = {}) {
   // this tick (scheduler.cjs computes it from state.launchBlocks). Held rows
   // are invisible to every pick below but still surface as holds.
   const heldSlugs = quietOpts.heldSlugs instanceof Map ? quietOpts.heldSlugs : new Map();
+  const satisfiedSlugsByCwd = quietOpts.satisfiedSlugsByCwd instanceof Map ? quietOpts.satisfiedSlugsByCwd : new Map();
+  const satisfiedSlugsFor = (cwd) => satisfiedSlugsByCwd.get(cwd || DEFAULT_PROJECT_CWD) ?? new Set();
   const pickable = (j) => j.status === 'pending' && !running.has(j.slug) && !heldSlugs.has(j.slug);
 
   // Exclusive lease (PRD 1107): while a quiet-machine job is running, it
@@ -361,7 +518,7 @@ function pickNextBatch(allJobs, running, freeSlots, quietOpts = {}) {
     const quietPending = allJobs.filter((j) => pickable(j) && j.quietMachine === true);
     for (const job of quietPending) {
       const projectJobs = projectMap.get(job.cwd || DEFAULT_PROJECT_CWD) || [job];
-      if (findBlockingDep(job, projectJobs)) continue; // blocked — try the next quiet candidate
+      if (findBlockingDep(job, projectJobs, satisfiedSlugsFor(job.cwd))) continue; // blocked — try the next quiet candidate
       const machineQuiet = machineInUse === 0;
       const waitedMs = now - enqueueTimestamp(job);
       const degraded = !machineQuiet && waitedMs >= quietWaitMs;
@@ -408,7 +565,7 @@ function pickNextBatch(allJobs, running, freeSlots, quietOpts = {}) {
     for (const c of candidates) {
       if (slots <= 0) break;
       if (!c.active) continue;
-      const result = pickForProject(c.view, c.runningSlugsInProject, 1, heldSlugs);
+      const result = pickForProject(c.view, c.runningSlugsInProject, 1, heldSlugs, satisfiedSlugsFor(c.cwd));
       for (const h of result.holds ?? []) if (!holdsBySlug.has(h.slug)) holdsBySlug.set(h.slug, h);
       if (result.batch.length === 0) {
         if (heldReason === null && result.reason) heldReason = result.reason;
@@ -491,4 +648,5 @@ function findStarvedProjects(jobs, now, thresholdMs) {
 
 module.exports = {
   pickForProject, pickNextBatch, enqueueTimestamp, findStarvedProjects, findBlockingDep, DEFAULT_PROJECT_CWD,
+  DEP_HISTORY_FAIL_OPEN,
 };