@ngockhoale/ukit 3.4.67 → 3.4.68

package/template_project/.claude/ukit/runtime/stop-coordinator.mjs

@@ -1,75 +1,18 @@
 #!/usr/bin/env node
 /**
- * stop-coordinator.mjs — the ONE Stop decision coordinator (TASK-025, PLAN §2 H17).
- *
- * H17: `.claude/settings.json` used to register BOTH `completion-gate.sh` and
- * `task-watchdog.sh` on the Stop event. Each hook evaluated its own policy and each
- * could emit `decision: block`, so a single Stop could produce two continuation
- * decisions and two state mutations (completion gate continuation counter + watchdog
- * hard-block counter). This module replaces that with one coordinator:
- *
- *   - it evaluates the completion policy by spawning execution-ledger.mjs
- *     `--evaluate-stop` exactly once (the ledger owns its own counting semantics);
- *   - it evaluates the watchdog policy in-process through task-watchdog.mjs's
- *     exported `evaluateStopWatchdog` exactly once;
- *   - it evaluates the handoff-cursor policy in-process: while
- *     `docs/AI_HANDOFF/RUN.md` carries `Phase:` other than `done`/`blocked`, a
- *     handoff-fullstack run is still in flight and the stop is bounced back with
- *     the cursor's `Next:` step — this is what keeps an overnight run moving
- *     after a recap instead of stalling idle. When RUN.md carries an
- *     `ExitPredicate:` line (mechanic #7), `Phase: done` is accepted only if the
- *     predicate evaluates true — `all(index:all-done, git:clean,
- *     file-exists:<relpath>)` terms checked mechanically, no eval, no shell-out.
- *     A stalled-cursor breaker releases the stop if the cursor has not advanced
- *     across `stopGateMaxStalledBlocks` consecutive blocked stops (same liveness
- *     shape as the ledger's noProgressCount breaker), and its advisory reports
- *     the predicate state so a plateau is visible;
- *   - it merges the three evaluator results with a deterministic owner order —
- *     fail-closed completion failure > completion block > handoff-cursor block >
- *     watchdog block > merged advisory > silent release — and emits AT MOST ONE
- *     Stop JSON line;
- *   - a lock-scoped once-per-stop guard makes a legacy double-registered Stop
- *     (old settings.json still listing both hooks) inert: the second coordinator
- *     invocation for the same session inside the dedupe window emits nothing and
- *     mutates nothing, so counters still move at most once.
- *
- * Failure posture (security test row):
- *   - The completion gate is the fail-closed blocker. If it fails to produce a
- *     verdict (missing script, spawn error, non-zero exit, unparseable output,
- *     budget overrun) the coordinator BLOCKS fail-closed with a fixed, redacted
- *     infrastructure reason — raw failure detail goes to stderr only, never into
- *     the parsed decision (mirrors execution-ledger's own crash counter posture).
- *   - The watchdog is an advisory lane. Its failure never decides anything; the
- *     other evaluator's decision stands and the failure is reported verbatim in
- *     the emitted `systemMessage` (stderr carries it too).
- *
- * Exports (independently testable — tests import the module directly):
- *   DEDUPE_WINDOW_MS            — same-session Stop invocations closer than this are
- *                                 treated as one event (a recovery turn takes >>2s).
- *   redactInfrastructureReason  — the fixed redacted block reason for a failed
- *                                 fail-closed blocker; never repeats its input.
- *   redactDeadlineReason        — the fixed redacted block reason for a deadline
- *                                 overrun (budget, not crash — same redaction).
- *   emitDeadlineBlock           — the deadline path's single fail-closed emission.
- *   normalizeEvaluatorStdout    — ledger stdout → { kind, reason?, systemMessage? }.
- *   coordinateStopDecisions     — the pure ordered merge; owns ordering + provenance
- *                                 only (evaluators stay independently testable).
- *   evaluateHandoffCursor       — in-process RUN.md lane; advisory on any failure.
- *   evaluateCompletionPolicy    — spawns the ledger once, returns the normalized
- *                                 completion evaluator result (throws on failure).
- *   runStopCoordinator          — event guard + dedupe + both evaluators + merge.
- *
- * Like every UKit hook runtime this fails loud and stays inside the hook deadline:
- * a self-kill timer honours UKIT_HOOK_DEADLINE_MS (default 3000ms), the ledger child
- * gets a bounded budget, and every path exits 0.
- *
- * Deadline posture (fix round 1 — reviewer critical): the deadline is the LAST line
- * of defence for the fail-closed blocker, so it must not be a silent exit. The
- * wrapper (`completion-gate.sh`) reads "exit 0 with empty stdout" as a clean release,
- * which meant a coordinator that hit its own deadline while the completion evaluator
- * hung RELEASED Stop instead of blocking it. The deadline now emits the same fixed
- * redacted fail-closed block (synchronously, so process.exit cannot drop a buffered
- * pipe write) and reaps any in-flight evaluator child before exiting.
+ * One Stop coordinator (TASK-025, PLAN §2 H17): evaluate the ledger child,
+ * watchdog and RUN cursor once; emit at most one decision. A lock-scoped dedupe
+ * window prevents legacy double hook registration from double-counting.
+ * Priority: fail-closed completion failure > completion block > cursor block >
+ * watchdog block > merged advisory > silent release.
+ * RUN Next carries continuation; done requires its mechanical ExitPredicate.
+ * Stalled-cursor releases are advisory, never completion evidence.
+ * Completion infrastructure failures block with redacted reasons (details only
+ * on stderr); watchdog failures are advisory and reported verbatim.
+ * UKIT_HOOK_DEADLINE_MS bounds execution (default 3000ms), including the ledger
+ * child. Deadline expiry synchronously emits a fail-closed block and reaps the
+ * child before exit0: empty stdout would incorrectly release the wrapper.
+ * Exported evaluators, merge, normalization and redaction seams are tested directly.
  */
 
 import fs from 'node:fs/promises';
@@ -79,6 +22,10 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 
 import { withAsyncLock } from './async-lock.mjs';
+// Frozen RUN scope membership (TaskScope / ScopeQueue / ScopePlans, cycle-qualified):
+// the SAME selector filters the completion and blocked predicates below. Sandbox
+// runtimes that copy this file by an explicit sibling list must copy this module too.
+import { selectTaskScope } from './handoff-task-scope.mjs';
 // TASK-005 (FR-005): the outcome seam loads LAZILY — a partial install missing
 // observability-emit.mjs must degrade to "no outcome record" (telemetry is
 // advisory), never crash the coordinator at module load.
@@ -884,8 +831,15 @@ export function parseExitPredicate(expr) {
  * `index:all-done` — every TASK-xxx row in docs/AI_HANDOFF/INDEX.md is in a
  * terminal-success status (`done` or `cancelled_superseded`). An unreadable or
  * taskless INDEX cannot prove all-done, so the term fails.
+ *
+ * Frozen RUN scope: rows are filtered through the SAME TaskScope selector the
+ * blocked predicate uses (runText supplies the mappings; the live INDEX resolves
+ * against the run's current `Cycle:`). A row explicitly mapped outside the frozen
+ * ScopeQueue/ScopePlans is excluded; unknown/ambiguous mappings are retained AND
+ * their reconciliation diagnostics fail the term — completion is never declared
+ * over an unresolved mapping.
  */
-async function evalIndexAllDone(projectRoot, { goalScope = '', scopeQueue = '', cycleField = '' } = {}) {
+async function evalIndexAllDone(projectRoot, { goalScope = '', scopeQueue = '', cycleField = '', runText = '' } = {}) {
   let text;
   try {
     text = await fs.readFile(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'INDEX.md'), 'utf8');
@@ -893,9 +847,20 @@ async function evalIndexAllDone(projectRoot, { goalScope = '', scopeQueue = '',
     return { pass: false, detail: 'INDEX.md unreadable' };
   }
   const rows = indexTaskRows(text);
-  if (rows.length === 0) return evalFinalizedCycles(projectRoot, goalScope, scopeQueue, cycleField);
+  if (rows.length === 0) return evalFinalizedCycles(projectRoot, goalScope, scopeQueue, cycleField, runText);
+  const selectable = rows.map((raw) => ({ id: (indexTaskCells(raw)[0] || ''), raw }));
+  const { rows: scoped, reconciliation } = selectTaskScope(runText, selectable, { cycle: parseRunCycle(cycleField) });
+  if (reconciliation.length > 0) {
+    return { pass: false, detail: `frozen TaskScope reconciliation unresolved: ${reconciliation.slice(0, 3).join(' | ')}` };
+  }
   const failing = [];
-  for (const row of rows) {
+  const liveIds = new Set(scoped.map((r) => goalTaskId(r.id)));
+  const liveCls = new Map(scoped.filter((r) => indexTaskRowIsWellFormed(r.raw)).map((r) => {
+    const c = indexTaskCells(r.raw);
+    return [goalTaskId(c[0]), classifyTaskStatus((c[4] || '').toLowerCase(), c[0], liveIds)];
+  }));
+  for (const scopedRow of scoped) {
+    const row = scopedRow.raw;
     if (!indexTaskRowIsWellFormed(row)) {
       const shape = row.startsWith('|') ? 'malformed task row' : 'unsupported task row (missing outer leading pipe)';
       failing.push(`${shape} (expected ${INDEX_TASK_COLUMNS} columns): ${row.slice(0, 60)}`);
@@ -903,12 +868,14 @@ async function evalIndexAllDone(projectRoot, { goalScope = '', scopeQueue = '',
     }
     const cells = indexTaskCells(row);
     const status = (cells[4] || '').toLowerCase();
-    if (status !== 'done' && status !== 'cancelled_superseded') {
-      failing.push(`${cells[0]}=${cells[4] || '?'}`);
+    const cls = classifyTaskStatus(status, cells[0], liveIds);
+    const terminal = cls === 'delivered' || (cls === 'cancelled-grounded' && groundedCancellationResolved(cells[0], liveCls));
+    if (!terminal) {
+      failing.push(`${cells[0]}=${cells[4] || '?'}${cls === 'review-obligation' ? ' (review/integration owed; not delivered)' : cls === 'unresolved' ? ' (bare cancelled does not prove the requirement was met)' : ''}`);
     }
   }
   return failing.length === 0
-    ? { pass: true, detail: `${rows.length} task row(s) done` }
+    ? { pass: true, detail: `${scoped.length} in-scope task row(s) done` }
     : { pass: false, detail: `not done: ${failing.join(', ')}` };
 }
 
@@ -934,8 +901,13 @@ function parseIndexStatuses(text) {
  * happened" either: the archived task files ARE the auditable record. All-done holds when at
  * least one archived task exists, every archived task is terminal-success, and — for a run-all
  * goal — no consumable queued blueprint remains. No archive evidence → still unprovable (fail).
+ *
+ * Frozen RUN scope: each archive cycle's rows resolve through the SAME TaskScope selector
+ * against that ARCHIVE cycle's own keys (`runText` supplies the preserved mappings), so a
+ * snapshot row mapped outside the frozen scope is excluded and an unknown/ambiguous mapping
+ * fails closed — an unresolved mapping can never prove a finalized cycle.
  */
-async function evalFinalizedCycles(projectRoot, goalScope, scopeQueue = '', cycleField = '') {
+async function evalFinalizedCycles(projectRoot, goalScope, scopeQueue = '', cycleField = '', runText = '') {
   const cycles = [];
   const seen = new Set();
   const assignedCycle = parseRunCycle(cycleField);
@@ -992,7 +964,20 @@ async function evalFinalizedCycles(projectRoot, goalScope, scopeQueue = '', cycl
       snapshot = parseIndexStatuses(raw);
       if (snapshot === null) return { pass: false, detail: `archive INDEX snapshot malformed: ${cycle.name}` };
     }
-    for (const file of files.filter((f) => /^TASK-[\w.-]+\.md$/i.test(f))) {
+    // Frozen-scope selection over THIS archive cycle: rows resolve against the archive
+    // cycle's own keys, so preserved per-cycle mappings decide and a stale unqualified
+    // line that another cycle qualified is ambiguous (included + reconciliation, fail).
+    const taskFiles = files.filter((f) => /^TASK-[\w.-]+\.md$/i.test(f));
+    const { rows: scopedFiles, reconciliation: scopeDiags } = selectTaskScope(
+      runText,
+      taskFiles.map((f) => ({ id: f.replace(/\.md$/i, ''), file: f })),
+      { cycle: cycle.name },
+    );
+    if (scopeDiags.length > 0) {
+      return { pass: false, detail: `archive ${cycle.name}: frozen TaskScope reconciliation unresolved: ${scopeDiags.slice(0, 3).join(' | ')}` };
+    }
+    for (const scopedFile of scopedFiles) {
+      const file = scopedFile.file;
       total += 1;
       const id = file.replace(/\.md$/i, '').toUpperCase();
       // A snapshot that exists but has no row for this task is unproven → fail closed; only an
@@ -1003,7 +988,11 @@ async function evalFinalizedCycles(projectRoot, goalScope, scopeQueue = '', cycl
         try { body = await fs.readFile(path.join(cycle.dir, file), 'utf8'); } catch { /* unreadable → not proven */ }
         status = (body.match(/^-\s*Status:\s*`?([\w-]+)`?/im)?.[1] || '').toLowerCase();
       }
-      if (status !== 'done' && status !== 'cancelled_superseded') {
+      const archIds = new Set(snapshot ? [...snapshot.keys()].map(goalTaskId) : []);
+      const archCls = classifyTaskStatus(status, id, archIds);
+      const archClsByKey = new Map([...(snapshot || new Map()).entries()].map(([k, st]) => [goalTaskId(k), classifyTaskStatus(st, k, archIds)]));
+      const archTerminal = archCls === 'delivered' || (archCls === 'cancelled-grounded' && groundedCancellationResolved(id, archClsByKey));
+      if (!archTerminal) {
         failing.push(`${file.replace(/\.md$/i, '')}=${status || '?'}${snapshot ? ' (not in the archive INDEX snapshot)' : ' (no INDEX snapshot — run `node .claude/ukit/runtime/resumable-run.mjs archive-cycle <root> <NN>`)'}`);
       }
     }
@@ -1151,7 +1140,7 @@ async function evalVerifyPass(projectRoot) {
  * malformed (unsatisfiable). Advisory like the rest of the lane — a thrown
  * error becomes a failed term, never an exception.
  */
-async function evaluateExitPredicate(projectRoot, expr, { goalScope = '', scopeQueue = '', cycleField = '' } = {}) {
+async function evaluateExitPredicate(projectRoot, expr, { goalScope = '', scopeQueue = '', cycleField = '', runText = '' } = {}) {
   const terms = parseExitPredicate(expr);
   if (!terms) {
     return { ok: false, terms: [{ term: String(expr || '').trim() || '(empty)', pass: false, detail: 'malformed predicate' }] };
@@ -1160,7 +1149,7 @@ async function evaluateExitPredicate(projectRoot, expr, { goalScope = '', scopeQ
   for (const term of terms) {
     let r;
     try {
-      if (term === 'index:all-done') r = await evalIndexAllDone(projectRoot, { goalScope, scopeQueue, cycleField });
+      if (term === 'index:all-done') r = await evalIndexAllDone(projectRoot, { goalScope, scopeQueue, cycleField, runText });
       else if (term === 'git:clean') r = evalGitClean(projectRoot);
       else if (term === 'agents:none-running') r = await evalAgentsNoneRunning(projectRoot);
       else if (term === 'verify:pass') r = await evalVerifyPass(projectRoot);
@@ -1195,7 +1184,70 @@ export const GOAL_STATUSES = Object.freeze(['RUNNING', 'PAUSED', 'BLOCKED', 'COM
 
 // Terminal-SUCCESS task statuses (INDEX `Status:` vocabulary). `blocked` is
 // pending-but-not-executable; everything else executable is pending work.
-const GOAL_DONE_TASK_STATUSES = new Set(['done', 'cancelled', 'cancelled_superseded']);
+//
+// The same status vocabulary must NOT answer every question. Four distinct facts:
+//   delivered        `done` only — proves delivery.
+//   cancelled-grounded `cancelled_superseded` = the RULES recovery state (record could not resume;
+//                    a `<ID>-R<n>` successor row carries the obligation and is judged on its own).
+//                    Terminal, but never proof of delivery. A bare `cancelled` carries no such
+//                    grounds and does not prove the requirement was met: it stays an unresolved
+//                    obligation (reconcile, never silently dropped).
+//   review-obligation `pending_review`/`approved`/`approved_minor`: nothing left to IMPLEMENT, but
+//                    review/integration/status-flip/release is still owed — never "delivered".
+//   history          `archived`: moved out of the live cycle; no obligation, no delivery claim.
+//   needs-planning   `needs_breakdown`: not yet validator+review-approved, so its actor is the
+//                    PLANNER/REVIEW gate (/ukit:handoff-create resume-gates), never the executor
+//                    (handoff-implement only picks `ready`). It keeps the run open and is never
+//                    delivered/done — but it is NOT executor-executable, and ordering the executor
+//                    to run it deadlocks the stop until a liveness cap falsely releases the run.
+// Everything else (ready, in_progress, changes_requested, critical_block, needs_executor_report,
+// merge_conflict, queued_blueprint, unknown) is dispatchable work. `blocked` is pending but not
+// dispatchable.
+const REVIEW_OBLIGATION_STATUSES = new Set(['pending_review', 'approved', 'approved_minor', 'approved_with_minor']);
+
+// A grounded cancellation (`cancelled_superseded`) is resolved ONLY by a STRICTLY LATER
+// `<ID>-R<n>` successor — a repair number strictly greater than its own (the root accepts
+// any R>=1) — that is itself delivered, or that is grounded-cancelled and resolved in turn
+// (chained recovery). A same-or-lower-numbered sibling delivers an EARLIER obligation, not
+// this one: `root cancelled_superseded → R1 done → R2 cancelled_superseded` leaves R2 open
+// even though R1 is done. A missing successor, a pending/review-owed successor (ready,
+// pending_review, approved*) and a bare `cancelled` successor all leave the obligation open.
+// `clsByKey`: Map<lower-cased id, classification> over the SAME task set. Each hop appends
+// `-R<n>`, so chains are finite; `seen` guards any loop. Recovery numbering is per root
+// (`TASK-xxx-R1`, `-R2`, …), so a successor of any `-R<n>` row is a sibling `<root>-R<m>`
+// row with m > n; suffixes compare numerically (BigInt, like the claim runtime), so R2 does
+// not resolve R10. The root is the id with its trailing `-R<n>` stripped.
+function groundedCancellationResolved(id, clsByKey, seen = new Set()) {
+  const key = goalTaskId(id);
+  if (seen.has(key)) return false;
+  seen.add(key);
+  const root = key.replace(/-r\d+$/, '');
+  const ownSuffix = key.match(/-r(\d+)$/);
+  const ownNum = ownSuffix ? BigInt(ownSuffix[1]) : 0n;
+  const prefix = `${root}-r`;
+  for (const [other, cls] of clsByKey) {
+    if (!other.startsWith(prefix) || !/^\d+$/.test(other.slice(prefix.length))) continue;
+    const num = BigInt(other.slice(prefix.length));
+    if (num <= ownNum) continue;
+    if (cls === 'delivered') return true;
+    if (cls === 'cancelled-grounded' && groundedCancellationResolved(other, clsByKey, seen)) return true;
+  }
+  return false;
+}
+
+/** Classify one task. `allIds` = Set of lower-cased ids in the same task set (for successor grounding). */
+export function classifyTaskStatus(status, id, allIds = new Set()) {
+  const st = String(status ?? '').trim().toLowerCase();
+  if (st === 'done') return 'delivered';
+  if (st === 'cancelled_superseded') return 'cancelled-grounded';
+  if (st === 'cancelled') return 'unresolved';
+  if (st === 'archived') return 'history';
+  if (st === 'blocked') return 'blocked';
+  if (st === 'needs_breakdown') return 'needs-planning';
+  if (st === 'malformed') return 'malformed';
+  if (REVIEW_OBLIGATION_STATUSES.has(st)) return 'review-obligation';
+  return 'dispatchable';
+}
 
 function goalTaskId(id) {
   return String(id ?? '').trim().toLowerCase();
@@ -1246,24 +1298,45 @@ export function deriveGoalStatus({ runCursor = null, tasks = null, ledger = null
         dependsOn: Array.isArray(t.dependsOn) ? t.dependsOn.map(goalTaskId) : [],
       }))
     : [];
-  const doneIds = new Set(list.filter((t) => GOAL_DONE_TASK_STATUSES.has(t.status)).map((t) => t.key));
-  const pending = list.filter((t) => !GOAL_DONE_TASK_STATUSES.has(t.status));
+  const allKeys = new Set(list.map((t) => t.key));
+  for (const t of list) t.cls = classifyTaskStatus(t.status, t.id, allKeys);
+  // A dependency is satisfied by delivery, history, or a grounded cancellation whose successor
+  // was delivered; approved/cancelled-without-grounds never satisfy it.
+  const deliveredKeys = new Set(list.filter((t) => t.cls === 'delivered').map((t) => t.key));
+  const doneIds = new Set(list.filter((t) => t.cls === 'delivered' || t.cls === 'history').map((t) => t.key));
+  const clsByKey = new Map(list.map((t) => [t.key, t.cls]));
+  for (const t of list) {
+    if (t.cls === 'cancelled-grounded' && groundedCancellationResolved(t.key, clsByKey)) doneIds.add(t.key);
+  }
+  // Only a RESOLVED grounded cancellation leaves pending; an orphan one is an open obligation.
+  const pending = list.filter((t) => !doneIds.has(t.key));
   // Dependency consistency: no task may be `done` while a dependency is not.
-  const depInconsistent = list.filter((t) => t.status === 'done' && t.dependsOn.some((d) => !doneIds.has(d)));
+  const depInconsistent = list.filter((t) => t.cls === 'delivered' && t.dependsOn.some((d) => !doneIds.has(d)));
   if (depInconsistent.length > 0) {
     reasons.push(`dependency-inconsistent done task(s): ${depInconsistent.map((t) => t.id || '?').join(', ')}`);
   }
-  const executable = pending.filter((t) => t.status !== 'blocked' && t.dependsOn.every((d) => doneIds.has(d)));
-  const blockedTasks = pending.filter((t) => t.status === 'blocked');
+  // Executor-executable: dispatchable/review-obligation/malformed work whose deps are done.
+  // needs-planning rows (needs_breakdown) are NOT executor-executable — their actor is the
+  // planner/review gate — and `blocked` rows are pending but not dispatchable.
+  const executable = pending.filter((t) => t.cls !== 'blocked' && t.cls !== 'needs-planning' && t.dependsOn.every((d) => doneIds.has(d)));
+  const blockedTasks = pending.filter((t) => t.cls === 'blocked');
+  const planningTasks = pending.filter((t) => t.cls === 'needs-planning');
   const agentsActive = agentsRunning === true || (Number.isFinite(agentsRunning) && agentsRunning > 0);
 
-  // Blocked work with nothing executable anywhere is BLOCKED — whatever the
-  // cursor says; the goal cannot advance.
-  if (pending.length > 0 && executable.length === 0 && blockedTasks.length > 0) {
+  // Blocked or planning-gated work with nothing executor-executable anywhere is
+  // BLOCKED — whatever the cursor says; the goal cannot advance.
+  if (pending.length > 0 && executable.length === 0 && (blockedTasks.length > 0 || planningTasks.length > 0)) {
+    const deadEnd = [...reasons];
+    if (blockedTasks.length > 0) {
+      deadEnd.push(`no executable work; blocked task(s): ${blockedTasks.slice(0, 5).map((t) => t.id || '?').join(', ')}`);
+    }
+    if (planningTasks.length > 0) {
+      deadEnd.push(`needs-planning task(s) await the planner/review gate, not the executor (run /ukit:handoff-create resume-gates (validator + plan review)): ${planningTasks.slice(0, 5).map((t) => t.id || '?').join(', ')}`);
+    }
     return {
       status: 'BLOCKED',
       nextCycle: false,
-      reasons: [...reasons, `no executable work; blocked task(s): ${blockedTasks.slice(0, 5).map((t) => t.id || '?').join(', ')}`],
+      reasons: deadEnd,
     };
   }
 
@@ -1328,10 +1401,32 @@ function indexTasks(indexText) {
   return indexTaskRows(indexText).map((row) => {
     if (!indexTaskRowIsWellFormed(row)) return { id: '', status: 'malformed' };
     const cells = indexTaskCells(row);
-    return { id: cells[0] || '', status: (cells[4] || '').toLowerCase() };
+    const deps = (cells[3] || '').split(',').map((d) => d.trim()).filter((d) => d && d.toLowerCase() !== 'none');
+    return { id: cells[0] || '', status: (cells[4] || '').toLowerCase(), deps };
   });
 }
 
+// Task-file dependency authority for the blocked-run predicate. Returns normalized TASK ids,
+// [] for `(none)`, or null when the file/section cannot be read (caller fails closed).
+async function readTaskFileDependencies(runRoot, taskId) {
+  const id = String(taskId ?? '').trim();
+  if (!/^TASK-[A-Za-z0-9._-]+$/.test(id)) return null;
+  try {
+    const text = await fs.readFile(path.join(runRoot, 'docs', 'AI_HANDOFF', 'tasks', `${id}.md`), 'utf8');
+    const m = text.match(/^##\s+Dependencies\s*$([\s\S]*?)(?=^##\s|(?![\s\S]))/m);
+    if (!m) return null;
+    // Only list items / bare id lines declare dependencies; prose ("Unlike TASK-001 ...") does not.
+    const body = m[1]
+      .replace(/<!--[\s\S]*?-->/g, ' ')
+      .split(/\r?\n/)
+      .filter((l) => /^\s*(?:[-*+]|\d+[.)])\s/.test(l) || /^\s*TASK-[\w.,\s-]*$/i.test(l))
+      .join('\n');
+    return [...new Set((body.match(/TASK-[A-Za-z0-9._-]*[A-Za-z0-9]/g) || []).map(goalTaskId))];
+  } catch {
+    return null;
+  }
+}
+
 function indexTaskSnapshotHash(indexText) {
   const rows = indexTaskRows(indexText).map((row) => {
     const cells = indexTaskCells(row);
@@ -1341,10 +1436,17 @@ function indexTaskSnapshotHash(indexText) {
 }
 
 function firstOpenIndexTaskId(indexText) {
+  const allIds = new Set(indexTaskRows(indexText).map((r) => goalTaskId(indexTaskCells(r)[0])));
+  const clsByKey = new Map(indexTaskRows(indexText).filter((r) => indexTaskRowIsWellFormed(r)).map((r) => {
+    const c = indexTaskCells(r);
+    return [goalTaskId(c[0]), classifyTaskStatus((c[4] || '').toLowerCase(), c[0], allIds)];
+  }));
   for (const row of indexTaskRows(indexText)) {
     const cells = indexTaskCells(row);
     const status = (cells[4] || '').toLowerCase();
-    if (status !== 'done' && status !== 'cancelled_superseded') return cells[0] || null;
+    const cls = classifyTaskStatus(status, cells[0], allIds);
+    const terminal = cls === 'delivered' || (cls === 'cancelled-grounded' && groundedCancellationResolved(cells[0], clsByKey));
+    if (!terminal) return cells[0] || null;
   }
   return null;
 }
@@ -1412,7 +1514,7 @@ export async function transcriptShowsHandoffRun(transcriptPath, opts = {}) {
  * under a racing writer only delays the cap by one stop; a frozen breaker loops
  * forever. Only a genuinely unwritable state file still returns null.
  */
-async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs, snapshotHash = '', firstOpenTaskId = null, failing = false }) {
+async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs, snapshotHash = '', firstOpenTaskId = null, failing = false, cycle = null }) {
   const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'stop-coordinator', 'state.json');
   const bump = async () => {
     let current = {};
@@ -1422,15 +1524,17 @@ async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs, sna
     const prev = current.handoff || {};
     const count = prev.signature === signature ? (Number(prev.count) || 0) + 1 : 1;
     const prevTask = current.handoffTask || {};
+    // A reused task id under a NEW cycle is a different task: the failing streak restarts.
     const sameFailingTask = prevTask.snapshotHash === snapshotHash
-      && (prevTask.firstOpenTaskId || null) === (firstOpenTaskId || null);
+      && (prevTask.firstOpenTaskId || null) === (firstOpenTaskId || null)
+      && (prevTask.cycle || null) === (cycle || null);
     const failingCount = failing
       ? (sameFailingTask ? (Number(prevTask.failingCount) || 0) + 1 : 1)
       : 0;
     await fs.mkdir(path.dirname(statePath), { recursive: true });
     await fs.writeFile(
       statePath,
-      `${JSON.stringify({ ...current, handoff: { signature, count }, handoffTask: { snapshotHash, firstOpenTaskId, failingCount } }, null, 1)}\n`,
+      `${JSON.stringify({ ...current, handoff: { signature, count }, handoffTask: { snapshotHash, firstOpenTaskId, cycle: cycle || null, failingCount } }, null, 1)}\n`,
       'utf8',
     );
     return { count, failingCount };
@@ -1497,7 +1601,7 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
   // Shared terminal predicate — tests/handoff/cycle21 greps this exact shape across
   // all four RUN.md consumers; keep `^(done|blocked)` as one expression.
   const terminal = String(phase).match(/^(done|blocked)\b/i)?.[1]?.toLowerCase() || '';
-  if (!phase || terminal === 'blocked') {
+  if (!phase) {
     return { kind: 'none' };
   }
   // Default exit predicate (goal completion): a `done` cursor with no explicit
@@ -1526,6 +1630,108 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
     };
   }
 
+  // `Phase: blocked` is a true external-blocker release only when NO pending row is executable:
+  // every pending row is blocked or waits on a dependency that is not done. An independent READY
+  // row (deps all done) keeps the run open. Malformed rows fail closed (treated as executable).
+  // Runs AFTER the pause check, so a paused run is never bounced here. Empty INDEX → legacy release.
+  if (terminal === 'blocked') {
+    const blockedIndex = await readIndexSnapshot(runRoot);
+    const allRows = indexTasks(blockedIndex);
+    // Same frozen-scope selector as the completion predicate: a row explicitly mapped outside
+    // the frozen ScopeQueue/ScopePlans does not keep a blocked run open, and rows whose mapping
+    // is unknown/ambiguous are RETAINED (reconcile, never guess). The live INDEX resolves
+    // against the run's current `Cycle:`; repair/replan tasks inherit their original scope.
+    const { rows, reconciliation } = selectTaskScope(text, allRows, { cycle: parseRunCycle(cycleField) });
+    // Blocked gate asks "is any pending row still EXECUTOR-workable?" — NOT "is it delivered?".
+    // Dispatchable, review-obligation (pending_review/approved*: review/flip/integration still
+    // owed), unresolved (bare cancelled / superseded without successor) and malformed rows all
+    // keep the run open when their dependencies are satisfied. needs-planning rows
+    // (needs_breakdown) do NOT: their actor is the planner/review gate, and ordering the executor
+    // to run them deadlocks the stop (FS-04).
+    const allKeys = new Set(rows.map((t) => goalTaskId(t.id)));
+    for (const t of rows) t.cls = t.status === 'malformed' ? 'malformed' : classifyTaskStatus(t.status, t.id, allKeys);
+    const clsOf = new Map(rows.map((t) => [goalTaskId(t.id), t.cls]));
+    const depSatisfied = (d) => {
+      const c = clsOf.get(d);
+      if (c === 'delivered' || c === 'history') return true;
+      if (c === 'cancelled-grounded') {
+        // Satisfied once the recovery successor (if any) is delivered; with no successor row the
+        // grounded cancellation itself is terminal.
+        return groundedCancellationResolved(d, clsOf);
+      }
+      return false;
+    };
+    const pending = rows.filter((t) => t.cls !== 'delivered' && t.cls !== 'history'
+      && !(t.cls === 'cancelled-grounded' && groundedCancellationResolved(t.id, clsOf)));
+    const planning = pending.filter((t) => t.cls === 'needs-planning');
+    // INDEX has no dependency column: the authority is the task file's `## Dependencies`
+    // section. Unreadable file, unknown dependency id => fail closed (row counts as executable).
+    const executable = [];
+    for (const t of pending) {
+      if (t.cls === 'malformed') { executable.push(t); continue; }
+      if (t.cls === 'blocked' || t.cls === 'needs-planning') continue;
+      const deps = await readTaskFileDependencies(runRoot, t.id);
+      if (deps === null) { executable.push(t); continue; }
+      if (deps.every(depSatisfied)) executable.push(t);
+      else if (deps.some((d) => !allKeys.has(d))) executable.push(t);
+      else if (deps.some((d) => clsOf.get(d) === 'unresolved')) executable.push(t);
+    }
+    if (rows.length === 0) return { kind: 'none' };
+    if (executable.length === 0) {
+      if (planning.length === 0) return { kind: 'none' }; // legacy terminal: genuinely stuck / externally blocked
+      // FS-04(d)/FS-05: the ONLY remaining rows are planner-gated. Defined terminal
+      // outcome — release WITHOUT a completion claim and persist the durable
+      // unfinished marker through the existing `Paused: yes` writer (Phase untouched,
+      // never `done`), so a later resume sees the obligation instead of silently
+      // inheriting a "completed" session.
+      const pause = await markRunCursorPaused(runRoot);
+      const namedPlanning = planning.slice(0, 5).map((t) => (t.id ? `${t.id}=${t.status}` : '(malformed INDEX row)')).join(', ');
+      return {
+        kind: 'advisory',
+        waitForApproval: true,
+        systemMessage: [
+          `[ukit-stop-coordinator] handoff run released: Phase: blocked and every remaining in-scope task is needs_breakdown (${namedPlanning}).`,
+          'These rows are planner/review-gated, not executor-executable — the run ends this stop UNFINISHED, never as completed.',
+          pause?.ok
+            ? 'RUN.md is marked `Paused: yes` (Phase untouched): the open obligation is persisted and no resume is auto-injected.'
+            : 'WARNING: RUN.md could not be marked `Paused: yes` (write failed) — the unfinished obligation is NOT durably marked.',
+          'CONTINUE LATER: run /ukit:handoff-create resume-gates (validator + plan review) for these tasks, then resume explicitly with /ukit:handoff-fullstack (or clear with /ukit:handoff-clear).',
+        ].join('\n'),
+      };
+    }
+    const named = executable.slice(0, 5).map((t) => (t.id ? `${t.id}=${t.status}` : '(malformed INDEX row)')).join(', ');
+    // Unresolved scope reconciliation is surfaced bounded — it must be resolved against
+    // RUN.md before terminal phases, never guessed away.
+    const reconcileNote = reconciliation.length > 0
+      ? [
+        '',
+        `Frozen TaskScope needs reconciliation (${reconciliation.slice(0, 3).join(' | ')}).`,
+        'Resolve the mapping lines in docs/AI_HANDOFF/RUN.md before terminal phases.',
+      ]
+      : [];
+    // FS-04: planning-gated rows ride along so the executor is never ordered to run
+    // work only the planner gate can act on.
+    const planningNote = planning.length > 0
+      ? [
+        '',
+        `needs_breakdown row(s) (${planning.slice(0, 5).map((t) => (t.id ? `${t.id}=${t.status}` : '(malformed INDEX row)')).join(', ')}) are NOT executor-executable.`,
+        'Run /ukit:handoff-create resume-gates (validator + plan review) for these tasks.',
+      ]
+      : [];
+    return {
+      kind: 'block',
+      reason: [
+        `UKit handoff run: Phase: blocked, but independent in-scope work is still executable (${named}).`,
+        'A blocker on one task does not end the run.',
+        ...planningNote,
+        ...reconcileNote,
+        '',
+        'CONTINUE IMMEDIATELY: execute the executable row(s) above, then rewrite the run cursor.',
+        'Set `Phase: blocked` only when no executable row remains.',
+      ].join('\n'),
+    };
+  }
+
   let effectivePredicate = exitPredicate;
   let predicateIsDefault = false;
   let openNextCycle = null;
@@ -1572,7 +1778,7 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
   if (terminal === 'done') {
     let predicate;
     try {
-      predicate = await evaluateExitPredicate(runRoot, effectivePredicate, { goalScope, scopeQueue, cycleField });
+      predicate = await evaluateExitPredicate(runRoot, effectivePredicate, { goalScope, scopeQueue, cycleField, runText: text });
     } catch {
       return { kind: 'none' }; // advisory lane: evaluator failure never wedges a stop
     }
@@ -1630,13 +1836,16 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
   const indexText = await readIndexSnapshot(runRoot);
   const snapshotHash = indexTaskSnapshotHash(indexText);
   const firstOpenTask = firstOpenIndexTaskId(indexText);
-  const signature = `${phase}|${cursor}|${next}|${snapshotHash}`;
+  // The run's cycle is part of the identity: a streak accrued under cycle-01 must not carry into
+  // cycle-02 when task ids restart (same TASK-001, same cursor wording would otherwise match).
+  const signature = `${cycleField || ''}|${phase}|${cursor}|${next}|${snapshotHash}`;
   const streak = await bumpHandoffStallCount({
     projectRoot: runRoot,
     signature,
     lockBudgetMs,
     snapshotHash,
     firstOpenTaskId: firstOpenTask,
+    cycle: cycleField,
     failing: completionKind === 'block',
   });
   // Reentrancy valve (stop_hook_active): Claude Code sets it when this Stop fires
@@ -1657,39 +1866,76 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
     let predicateState = 'no ExitPredicate recorded';
     if (effectivePredicate) {
       try {
-        predicateState = formatPredicateState(await evaluateExitPredicate(runRoot, effectivePredicate, { goalScope, scopeQueue, cycleField }));
+        predicateState = formatPredicateState(await evaluateExitPredicate(runRoot, effectivePredicate, { goalScope, scopeQueue, cycleField, runText: text }));
       } catch {
         predicateState = 'predicate evaluation failed';
       }
     }
+    // FS-05: releasing a nonterminal run is a loop-liveness escape, never a
+    // completion — persist the durable unfinished marker before the advisory.
+    const pause = await markRunCursorPaused(runRoot);
     return {
       kind: 'advisory',
+      waitForApproval: true,
       systemMessage:
         `[ukit-stop-coordinator] handoff-cursor released this stop: the run cursor ` +
         `("${signature}") has not advanced across ${streak.count - 1} consecutive blocked stops ` +
         `(cap ${gate.maxStalledBlocks}), so the gate treats the run as stalled rather than ` +
         `looping forever. ExitPredicate state: ${predicateState}. ` +
+        `${unfinishedMarkerNote(pause)} ` +
         `Inspect docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md; ` +
-        `the run can be resumed with /ukit:handoff-fullstack or cleared with /ukit:handoff-clear.`,
+        `To resume, send a fresh explicit /ukit:handoff-fullstack in a new message (only that explicit invoke lifts the pause; ordinary prompts do not); ` +
+        `or clear with /ukit:handoff-clear.`,
     };
   }
   // Same failing task (maxAttempts): a completion gate that keeps failing on the
   // same first-open task and snapshot is a retry loop, not progress — release
   // after `maxAttemptsPerFailure` consecutive failures so the session reports
-  // honestly instead of being bounced into the same wall.
+  // honestly instead of being bounced into the same wall. FS-05: the release
+  // persists the durable unfinished marker — it is a loop escape, not a done.
   if (streak !== null && streak.failingCount >= gate.maxAttemptsPerFailure && firstOpenTask) {
+    const pause = await markRunCursorPaused(runRoot);
     return {
       kind: 'advisory',
+      waitForApproval: true,
       systemMessage:
         `[ukit-stop-coordinator] handoff-cursor released this stop: task ${firstOpenTask} has now ` +
         `failed the completion gate ${streak.failingCount} consecutive times ` +
         `(maxAttemptsPerFailure ${gate.maxAttemptsPerFailure}). The task snapshot ` +
         `("${snapshotHash}") has not changed — record the concrete blocker on the task ` +
         `(or fix the failure differently) and continue; the counter resets on any ` +
-        `snapshot or first-open-task change.`,
+        `snapshot or first-open-task change. ${unfinishedMarkerNote(pause)} ` +
+        `Resume explicitly with /ukit:handoff-fullstack or clear with /ukit:handoff-clear.`,
     };
   }
 
+  // FS-04: a run whose ENTIRE in-scope backlog is needs_breakdown is planner-gated —
+  // handoff-implement only picks `ready`, so the generic "execute the `Next:` step"
+  // order below would loop on work the executor refuses. Route this stop to the
+  // planner/review gate instead. Malformed rows fail closed (treated as executor
+  // work, generic block), and any dispatchable/review/blocked row keeps the generic
+  // continuation. The stall-cap and maxAttempts releases above keep priority: a
+  // wedged planning-only run still trips liveness and releases (FS-05 marker).
+  if (indexText.trim()) {
+    const ntScope = selectTaskScope(text, indexTasks(indexText), { cycle: parseRunCycle(cycleField) });
+    const ntRows = ntScope.rows || [];
+    const isPlanningRow = (t) => t.status !== 'malformed' && classifyTaskStatus(t.status, t.id) === 'needs-planning';
+    const planningRows = ntRows.filter(isPlanningRow);
+    const executorRows = ntRows.filter((t) => !isPlanningRow(t));
+    if (ntRows.length > 0 && executorRows.length === 0 && planningRows.length > 0) {
+      const namedPlanning = planningRows.slice(0, 5).map((t) => (t.id ? `${t.id}=${t.status}` : '(malformed INDEX row)')).join(', ');
+      return {
+        kind: 'block',
+        reason: [
+          `UKit handoff run: every in-scope task is needs_breakdown (${namedPlanning}) — nothing here is executor-executable.`,
+          'handoff-implement only picks `ready` rows: these tasks are awaiting the planner/review gate, so continuing the current `Next:` step cannot start them.',
+          '',
+          'CONTINUE IMMEDIATELY: run /ukit:handoff-create resume-gates (validator + plan review) for these tasks, flip them to `ready`, then rewrite the run cursor and keep working.',
+        ].join('\n'),
+      };
+    }
+  }
+
   const lines = [
     'UKit handoff run in progress — this stop is refused. A handoff-fullstack cycle is still',
     'in flight; a recap, wave summary, or "waiting" reply is NOT completion. The only valid',
@@ -1909,6 +2155,18 @@ export async function markRunCursorPaused(runRoot) {
   }
 }
 
+// FS-05: a liveness release (stalled-cursor cap, maxAttemptsPerFailure, or a
+// blocked run whose only remaining rows are planner-gated) must be
+// distinguishable from a completed report. The marker is the run cursor's own
+// `Paused: yes` line — the exact contract the SessionStart resume hook reads
+// (never auto-inject a resume; only an explicit instruction lifts it) — written
+// by the existing markRunCursorPaused writer, which never touches `Phase:`.
+function unfinishedMarkerNote(pause) {
+  return pause?.ok
+    ? 'The run is unfinished, not completed: RUN.md is marked `Paused: yes` (Phase untouched), so no resume is auto-injected and nothing is reported as done.'
+    : 'WARNING: the run is unfinished, not completed, but RUN.md could not be marked `Paused: yes` (write failed) — the open obligation is not durably marked.';
+}
+
 // ─── Once-per-stop guard ──────────────────────────────────────────────────
 /**
  * Lock-scoped dedupe: persist `{ lastStop: { key, ts } }` and report whether this
@@ -1952,6 +2210,18 @@ async function resolveRunRoot(projectRoot, cwd) {
   return mod.resolveHandoffRunRoot(projectRoot, cwd);
 }
 
+// The run's pinned cycle (RUN.md `Cycle:`, normalized by parseRunCycle) — the
+// watchdog's cycle-scoping input so per-task anchors from a PREVIOUS cycle are
+// reset instead of false-tripping a reused task id. Unreadable/blank → null.
+async function readRunCycle(runRoot) {
+  try {
+    const text = await fs.readFile(path.join(runRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    return parseRunCycle((String(text).match(/^Cycle:\s*(.+)$/m) || [])[1] || '');
+  } catch {
+    return null;
+  }
+}
+
 // ─── Orchestration ────────────────────────────────────────────────────────
 /**
  * One coordinator invocation: event guard → once-per-stop dedupe → completion
@@ -2013,7 +2283,12 @@ export async function runStopCoordinator({
   let watchdog = null;
   try {
     const watchdogRuntime = await import(new URL('./task-watchdog.mjs', import.meta.url).href);
-    watchdog = await watchdogRuntime.evaluateStopWatchdog({ projectRoot, now, lockBudgetMs });
+    watchdog = await watchdogRuntime.evaluateStopWatchdog({
+      projectRoot,
+      now,
+      lockBudgetMs,
+      cycle: await readRunCycle(await resolveRunRoot(projectRoot, payload?.cwd)),
+    });
   } catch (error) {
     failures.watchdog = error?.message || String(error);
     process.stderr.write(`[ukit-stop-coordinator] task-watchdog evaluator failed: ${failures.watchdog}\n`);
@@ -2232,6 +2507,15 @@ async function main() {
 // Compare real paths (same shape as execution-ledger.mjs): a project under a
 // symlinked root makes import.meta.url resolve to the real path while argv[1]
 // keeps the symlinked spelling. Importing this module must never run main().
+// FS-06: a direct run through a RENAMED symlink (`node stop-gate.mjs` where
+// stop-gate.mjs → stop-coordinator.mjs) used to be rejected by the basename
+// fast path, so main() never ran and a wrapper spawning the coordinator through
+// such a link got a silent release instead of the fail-closed block. argv[1] is
+// realpath'd first: it is the entry node already executed (never a stalled
+// mount), and when it moved, the decision is made on real paths — an importer's
+// real path is its own file and can never equal ours, so that comparison is
+// decisive. Plain importers keep the BUG-C22-01 fast path (basename skip, no
+// extra fs beyond the one argv realpath).
 function isDirectRun() {
   const argvPath = process.argv[1];
   if (!argvPath) return false;
@@ -2243,9 +2527,25 @@ function isDirectRun() {
     selfUrlPath = null;
   }
   if (selfUrlPath && selfUrlPath === selfPath) return true;
+  if (!selfUrlPath) return false;
+  let realArgPath = null;
+  try {
+    realArgPath = fsSync.realpathSync(selfPath);
+  } catch {
+    realArgPath = null;
+  }
+  if (realArgPath && realArgPath !== selfPath) {
+    let realSelfPath = null;
+    try {
+      realSelfPath = fsSync.realpathSync(selfUrlPath);
+    } catch {
+      realSelfPath = selfUrlPath;
+    }
+    return realArgPath === realSelfPath;
+  }
   // BUG-C22-01: skip fs entirely for non-matching importers — a stalled mount
   // must not park the event loop during `await import` inside an armed deadline.
-  if (selfUrlPath && path.basename(selfUrlPath) !== path.basename(selfPath)) return false;
+  if (path.basename(selfUrlPath) !== path.basename(selfPath)) return false;
   try {
     return fsSync.realpathSync(selfUrlPath) === fsSync.realpathSync(selfPath);
   } catch {