@ngockhoale/ukit 3.4.29 → 3.4.30

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

@@ -74,6 +74,7 @@
 
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
+import crypto from 'node:crypto';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 
@@ -207,6 +208,10 @@ export const HANDOFF_CURSOR_DEFAULTS = Object.freeze({
   // RUN.md — e.g. one opened just to plan something else — is never hijacked.
   // 'project': legacy behaviour, any session in the repo is bounced.
   scope: 'session',
+  // Same failing task across consecutive stops → release after this many
+  // completion-gate failures (overridable via handoff.fullstack.maxAttemptsPerFailure
+  // or orchestration.maxAttemptsPerFailure).
+  maxAttemptsPerFailure: 2,
 });
 
 // ─── Redaction ────────────────────────────────────────────────────────────
@@ -698,6 +703,11 @@ async function loadHandoffGateConfig(projectRoot) {
       await fs.readFile(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8'),
     );
     const gate = parsed?.handoff?.fullstack;
+    const configuredAttempts = Number.isFinite(gate?.maxAttemptsPerFailure)
+      ? Math.max(1, gate.maxAttemptsPerFailure)
+      : Number.isFinite(parsed?.orchestration?.maxAttemptsPerFailure)
+        ? Math.max(1, parsed.orchestration.maxAttemptsPerFailure)
+        : HANDOFF_CURSOR_DEFAULTS.maxAttemptsPerFailure;
     return {
       enabled: typeof gate?.stopGateEnabled === 'boolean' ? gate.stopGateEnabled : HANDOFF_CURSOR_DEFAULTS.enabled,
       maxStalledBlocks: Number.isFinite(gate?.stopGateMaxStalledBlocks)
@@ -706,6 +716,10 @@ async function loadHandoffGateConfig(projectRoot) {
       scope: gate?.stopGateScope === 'project' || gate?.stopGateScope === 'session'
         ? gate.stopGateScope
         : HANDOFF_CURSOR_DEFAULTS.scope,
+      // Same failing task across consecutive stops → release after this many
+      // completion-gate failures (orchestration.maxAttemptsPerFailure when set,
+      // else the documented default of 2).
+      maxAttemptsPerFailure: configuredAttempts,
     };
   } catch {
     return { ...HANDOFF_CURSOR_DEFAULTS };
@@ -721,9 +735,38 @@ function parseRunCursor(text) {
     cursor: field('Cursor'),
     next: field('Next'),
     exitPredicate: field('ExitPredicate'),
+    goalScope: field('GoalScope').toLowerCase(),
   };
 }
 
+// ─── Goal backlog beyond the active cycle ──────────────────────────────────
+// A finalized cycle resets INDEX.md to a header-only table, so "empty INDEX" proves nothing
+// about the GOAL. For a run-all goal (`GoalScope: run-all` in RUN.md) the authoritative
+// remaining backlog is the set of queued blueprints that a cycle can still consume:
+// docs/AI_HANDOFF/queued/<slug>/ — excluding `QueueIntent: deliberate-future` ones (separate
+// backlog by contract) and blueprints already moved to archive/. Unreadable → null (unknown is
+// never "nothing left").
+export async function pendingQueuedBlueprints(runRoot) {
+  const dir = path.join(runRoot, 'docs', 'AI_HANDOFF', 'queued');
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    return error?.code === 'ENOENT' ? [] : null;
+  }
+  const pending = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    let header = '';
+    try {
+      header = await fs.readFile(path.join(dir, entry.name, 'HANDOFF.md'), 'utf8');
+    } catch { /* a blueprint without HANDOFF.md uses the legacy fold-in behaviour */ }
+    if (/^QueueIntent:\s*deliberate-future\b/im.test(header)) continue;
+    pending.push(entry.name);
+  }
+  return pending.sort();
+}
+
 // ─── Exit predicate (mechanic #7 — exit-predicate-first loop) ─────────────
 //
 // The planner writes one `ExitPredicate:` line into RUN.md at P2 and the gate
@@ -747,7 +790,7 @@ export function parseExitPredicate(expr) {
     .map((t) => t.trim())
     .filter(Boolean);
   if (terms.length === 0) return null;
-  const TERM_RE = /^(index:all-done|git:clean|file-exists:[^\s,]+)$/;
+  const TERM_RE = /^(index:all-done|git:clean|file-exists:[^\s,]+|agents:none-running|verify:pass)$/;
   return terms.every((t) => TERM_RE.test(t)) ? terms : null;
 }
 
@@ -756,7 +799,7 @@ export function parseExitPredicate(expr) {
  * terminal-success status (`done` or `cancelled_superseded`). An unreadable or
  * taskless INDEX cannot prove all-done, so the term fails.
  */
-async function evalIndexAllDone(projectRoot) {
+async function evalIndexAllDone(projectRoot, { goalScope = '' } = {}) {
   let text;
   try {
     text = await fs.readFile(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'INDEX.md'), 'utf8');
@@ -767,7 +810,7 @@ async function evalIndexAllDone(projectRoot) {
     .split('\n')
     .map((line) => line.trim())
     .filter((line) => /^\|\s*TASK-/i.test(line));
-  if (rows.length === 0) return { pass: false, detail: 'INDEX.md has no task rows' };
+  if (rows.length === 0) return evalFinalizedCycles(projectRoot, goalScope);
   const failing = [];
   for (const row of rows) {
     const cells = row.split('|').map((c) => c.trim()).filter(Boolean);
@@ -781,6 +824,72 @@ async function evalIndexAllDone(projectRoot) {
     : { pass: false, detail: `not done: ${failing.join(', ')}` };
 }
 
+/** Task id → lower-cased status from the rows of an INDEX.md (or archive INDEX snapshot). */
+function parseIndexStatuses(text) {
+  const map = new Map();
+  for (const line of String(text).split('\n')) {
+    const row = line.trim();
+    if (!/^\|\s*TASK-/i.test(row)) continue;
+    const cells = row.split('|').slice(1, -1).map((c) => c.trim()); // keep empty cells: columns must not shift
+    map.set(String(cells[0]).toUpperCase(), String(cells[4] || '').toLowerCase());
+  }
+  return map;
+}
+
+/**
+ * A finalized cycle (F3) resets INDEX.md to a header-only table and moves its task files to
+ * archive/cycle-NN/. Zero index rows therefore proves nothing by itself, but it is not "no work
+ * 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).
+ */
+async function evalFinalizedCycles(projectRoot, goalScope) {
+  const base = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'archive');
+  let cycles;
+  try {
+    cycles = (await fs.readdir(base, { withFileTypes: true })).filter((e) => e.isDirectory() && /^cycle-\d+$/.test(e.name));
+  } catch {
+    return { pass: false, detail: 'INDEX.md has no task rows' };
+  }
+  let total = 0;
+  const failing = [];
+  for (const cycle of cycles) {
+    let files;
+    try { files = await fs.readdir(path.join(base, cycle.name)); } catch { continue; }
+    // Authoritative status = the INDEX snapshot taken at archive time (resumable-run.mjs
+    // archive-cycle). A task file's own `- Status:` header is executor-written and goes stale
+    // (`ready`) once INDEX.md owns the lifecycle; it is only the fallback for legacy archives
+    // that carry no snapshot. A snapshot row that is NOT terminal always wins (fail closed).
+    let snapshot = null;
+    if (files.includes('INDEX.md')) {
+      try { snapshot = parseIndexStatuses(await fs.readFile(path.join(base, cycle.name, 'INDEX.md'), 'utf8')); } catch { /* unreadable → header fallback */ }
+    }
+    for (const file of files.filter((f) => /^TASK-[\w.-]+\.md$/i.test(f))) {
+      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
+      // archive with NO snapshot (legacy) falls back to the task header.
+      let status = snapshot ? (snapshot.get(id) || '') : '';
+      if (!snapshot) {
+        let body = '';
+        try { body = await fs.readFile(path.join(base, cycle.name, file), 'utf8'); } catch { /* unreadable → not proven */ }
+        status = (body.match(/^-\s*Status:\s*`?([\w-]+)`?/im)?.[1] || '').toLowerCase();
+      }
+      if (status !== 'done' && status !== 'cancelled_superseded') {
+        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>`)'}`);
+      }
+    }
+  }
+  if (total === 0) return { pass: false, detail: 'INDEX.md has no task rows' };
+  if (failing.length > 0) return { pass: false, detail: `archived task not done: ${failing.join(', ')}` };
+  if (String(goalScope).toLowerCase() === 'run-all') {
+    const remaining = await pendingQueuedBlueprints(projectRoot);
+    if (!Array.isArray(remaining)) return { pass: false, detail: 'queued backlog unreadable' };
+    if (remaining.length > 0) return { pass: false, detail: `queued blueprint(s) remain: ${remaining.join(', ')}` };
+  }
+  return { pass: true, detail: `${total} archived task(s) done, index finalized` };
+}
+
 /**
  * `git:clean` — `git status --porcelain` is empty. A non-git directory (or a
  * missing git binary) cannot prove clean, so the term fails without throwing.
@@ -824,13 +933,92 @@ async function evalFileExists(projectRoot, rel) {
   }
 }
 
+// ─── Goal-level predicate terms (agents:none-running, verify:pass) ─────────
+// Both read EXISTING state only — the task-claim book (resumable-run.mjs) and
+// the exec-ledger receipts — and both treat unknown/unreadable state as UNMET
+// with a clear detail, never as a crash and never as a pass.
+
+let resumableRunModulePromise = null;
+function loadResumableRunModule() {
+  if (!resumableRunModulePromise) {
+    resumableRunModulePromise = import(
+      new URL('./resumable-run.mjs', import.meta.url).href
+    ).catch(() => null);
+  }
+  return resumableRunModulePromise;
+}
+
+/**
+ * `agents:none-running` — the per-task claim book holds no ACTIVE claim
+ * (owner + heartbeat within its TTL). No registry at all proves none running;
+ * an unreadable registry proves nothing → unmet.
+ */
+async function evalAgentsNoneRunning(projectRoot) {
+  const mod = await loadResumableRunModule();
+  if (!mod || typeof mod.countActiveTaskClaims !== 'function') {
+    return { pass: false, detail: 'claims registry unavailable (runtime module missing)' };
+  }
+  try {
+    const count = await mod.countActiveTaskClaims(projectRoot);
+    if (count === null) return { pass: false, detail: 'claims registry unreadable' };
+    return count === 0
+      ? { pass: true, detail: 'no active claims' }
+      : { pass: false, detail: `${count} active task claim(s)` };
+  } catch {
+    return { pass: false, detail: 'claims registry unreadable' };
+  }
+}
+
+/**
+ * `verify:pass` — the NEWEST verification receipt in the newest exec-ledger
+ * file passed. No ledger, no verification receipt, or a failed one → unmet.
+ * Details stay fixed strings (no paths, no ledger content) so the predicate
+ * state is safe to echo into block reasons.
+ */
+async function evalVerifyPass(projectRoot) {
+  const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'exec-ledger');
+  let entries;
+  try {
+    entries = (await fs.readdir(dir))
+      .filter((f) => f.endsWith('.json') && f !== 'gate-crash-counter.json');
+  } catch {
+    return { pass: false, detail: 'no exec ledger recorded' };
+  }
+  if (entries.length === 0) return { pass: false, detail: 'no exec ledger recorded' };
+  let newest = null;
+  let newestMs = -1;
+  for (const name of entries.slice(0, 64)) {
+    try {
+      const st = await fs.stat(path.join(dir, name));
+      if (st.mtimeMs > newestMs) { newestMs = st.mtimeMs; newest = name; }
+    } catch { /* vanished mid-scan — skip */ }
+  }
+  if (!newest) return { pass: false, detail: 'exec ledger unreadable' };
+  let ledger;
+  try {
+    ledger = JSON.parse(await fs.readFile(path.join(dir, newest), 'utf8'));
+  } catch {
+    return { pass: false, detail: 'exec ledger unreadable' };
+  }
+  const receipts = Array.isArray(ledger?.receipts) ? ledger.receipts : [];
+  for (let i = receipts.length - 1; i >= 0; i -= 1) {
+    const r = receipts[i];
+    if (!r || typeof r !== 'object' || r.kind !== 'verification') continue;
+    if (r.success === true && r.verdict?.kind !== 'failed') {
+      return { pass: true, detail: 'last verification passed' };
+    }
+    return { pass: false, detail: 'last verification failed' };
+  }
+  return { pass: false, detail: 'no verification receipt recorded' };
+}
+
 /**
  * Evaluate the RUN.md `ExitPredicate:` expression. Returns
  * `{ ok, terms: [{term, pass, detail}] }`; `ok` is false when the expression is
  * malformed (unsatisfiable). Advisory like the rest of the lane — a thrown
  * error becomes a failed term, never an exception.
  */
-async function evaluateExitPredicate(projectRoot, expr) {
+async function evaluateExitPredicate(projectRoot, expr, { goalScope = '' } = {}) {
   const terms = parseExitPredicate(expr);
   if (!terms) {
     return { ok: false, terms: [{ term: String(expr || '').trim() || '(empty)', pass: false, detail: 'malformed predicate' }] };
@@ -839,8 +1027,10 @@ async function evaluateExitPredicate(projectRoot, expr) {
   for (const term of terms) {
     let r;
     try {
-      if (term === 'index:all-done') r = await evalIndexAllDone(projectRoot);
+      if (term === 'index:all-done') r = await evalIndexAllDone(projectRoot, { goalScope });
       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);
       else r = await evalFileExists(projectRoot, term.slice('file-exists:'.length));
     } catch (err) {
       r = { pass: false, detail: `evaluator error: ${err?.message || err}` };
@@ -855,6 +1045,172 @@ function formatPredicateState(result) {
   return result.terms.map((t) => `${t.term}=${t.pass ? 'pass' : `FAIL (${t.detail})`}`).join(', ');
 }
 
+// ─── Goal status derivation (pure, deterministic) ──────────────────────────
+// The GOAL is the whole run-all objective; a CYCLE is one pass of the pipeline
+// (cursor P0..F). Four mechanical states, derived — never inferred from model
+// text:
+//   RUNNING    — work remains (or the run is mid-cycle / evidence unproven)
+//   PAUSED     — the user or a quota pause held the run (never force-continued)
+//   BLOCKED    — remaining work exists but none of it is executable
+//   COMPLETED  — cursor done AND every in-scope task terminal AND no active
+//                agents AND dependency-consistent AND verification evidence
+//                passes AND the final snapshot is consistent
+// COMPLETED is only ever PROVEN from the caller-supplied inputs; absent
+// evidence is unmet, so a bare `Phase: done` can never derive COMPLETED.
+
+export const GOAL_STATUSES = Object.freeze(['RUNNING', 'PAUSED', 'BLOCKED', 'COMPLETED']);
+
+// 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']);
+
+function goalTaskId(id) {
+  return String(id ?? '').trim().toLowerCase();
+}
+
+function goalVerificationVerdict(ledger) {
+  // Evidence travels in the caller's own verdict/ledger fields (the completion
+  // gate's ledger or a receipt verdict) — this function never re-derives it.
+  if (!ledger || typeof ledger !== 'object') return { pass: false, detail: 'verification evidence absent' };
+  const verdict = typeof ledger.verdict === 'string' ? ledger.verdict.trim().toLowerCase() : null;
+  if (verdict === 'pass' || verdict === 'passed' || verdict === 'verified') return { pass: true, detail: 'verification verdict: pass' };
+  if (verdict === 'fail' || verdict === 'failed') return { pass: false, detail: 'verification verdict: fail' };
+  if (ledger.verified === true) return { pass: true, detail: 'verification: verified' };
+  if (ledger.verified === false) return { pass: false, detail: 'verification: not verified' };
+  if (typeof ledger.verify === 'string' && ledger.verify.trim().toLowerCase() === 'pass') return { pass: true, detail: 'verify: pass' };
+  return { pass: false, detail: 'verification evidence unmet' };
+}
+
+/**
+ * Derive the goal status from structured inputs. Pure: no fs, no clock, no
+ * transcript — callers hand in the cursor fields, the CURRENT task snapshot
+ * (INDEX rows incl. review-created repair tasks and newly added tasks), the
+ * ledger verdict fields, and the agent/cycle state.
+ *
+ * @param {object} [input]
+ * @param {{ phase?: string, paused?: boolean } | null} [input.runCursor]
+ * @param {Array<{id: string, status: string, dependsOn?: string[]}> | null} [input.tasks]
+ * @param {{ verdict?: string, verified?: boolean, verify?: string } | null} [input.ledger]
+ * @param {boolean|number} [input.agentsRunning]
+ * @param {boolean} [input.snapshotConsistent]
+ * @returns {{ status: 'RUNNING'|'PAUSED'|'BLOCKED'|'COMPLETED', nextCycle: boolean, reasons: string[] }}
+ */
+export function deriveGoalStatus({ runCursor = null, tasks = null, ledger = null, agentsRunning = false, snapshotConsistent = true } = {}) {
+  const reasons = [];
+  const phase = String(runCursor?.phase ?? '').trim();
+  if (runCursor?.paused === true || /^paused\b/i.test(phase)) {
+    return { status: 'PAUSED', nextCycle: false, reasons: ['run cursor is paused'] };
+  }
+
+  const list = Array.isArray(tasks)
+    ? tasks
+      .filter((t) => t && typeof t === 'object')
+      .map((t) => ({
+        id: String(t.id ?? '').trim(),
+        key: goalTaskId(t.id),
+        status: String(t.status ?? '').trim().toLowerCase(),
+        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));
+  // 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)));
+  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');
+  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) {
+    return {
+      status: 'BLOCKED',
+      nextCycle: false,
+      reasons: [...reasons, `no executable work; blocked task(s): ${blockedTasks.slice(0, 5).map((t) => t.id || '?').join(', ')}`],
+    };
+  }
+
+  if (/^done\b/i.test(phase)) {
+    // Cycle end: executable backlog → the goal simply continues in a new cycle.
+    if (executable.length > 0) {
+      return {
+        status: 'RUNNING',
+        nextCycle: true,
+        reasons: [...reasons, `${executable.length} executable task(s) remain (e.g. ${executable.slice(0, 3).map((t) => t.id || '?').join(', ')})`],
+      };
+    }
+    if (pending.length > 0) {
+      // Tasks remain but none is executable and none is blocked (waiting on a
+      // dependency that is itself still pending, or a dep cycle) — not BLOCKED
+      // (no dead end), not COMPLETED (work remains).
+      return { status: 'RUNNING', nextCycle: false, reasons: [...reasons, 'tasks remain but none is currently executable'] };
+    }
+    // Everything terminal: completion must be PROVEN, each gate in turn.
+    if (depInconsistent.length > 0) return { status: 'RUNNING', nextCycle: false, reasons };
+    const verdict = goalVerificationVerdict(ledger);
+    if (!verdict.pass) return { status: 'RUNNING', nextCycle: false, reasons: [...reasons, verdict.detail] };
+    if (agentsActive) return { status: 'RUNNING', nextCycle: false, reasons: [...reasons, 'agents/cycle still running'] };
+    if (snapshotConsistent === false) return { status: 'RUNNING', nextCycle: false, reasons: [...reasons, 'final snapshot inconsistent'] };
+    return { status: 'COMPLETED', nextCycle: false, reasons: ['all in-scope tasks terminal, verification passed, no agents running, snapshot consistent'] };
+  }
+
+  // Nonterminal cycle: the goal tracks the live run.
+  reasons.push(`run phase "${phase || '(none)'}" is not terminal`);
+  return { status: 'RUNNING', nextCycle: false, reasons };
+}
+
+// ─── INDEX snapshot (task ids + statuses) ──────────────────────────────────
+// The CURRENT INDEX rows feed both the goal derivation and the no-progress
+// breaker: the ids+statuses hash changes whenever a task moves or a new one is
+// reconciled in, so the stall signature tracks goal progress, not just cursor
+// wording.
+
+function indexTaskRows(text) {
+  return String(text)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => /^\|\s*TASK-/i.test(line));
+}
+
+function indexTaskCells(row) {
+  return row.split('|').map((c) => c.trim()).filter(Boolean);
+}
+
+function indexTasks(indexText) {
+  return indexTaskRows(indexText).map((row) => {
+    const cells = indexTaskCells(row);
+    return { id: cells[0] || '', status: (cells[4] || '').toLowerCase() };
+  });
+}
+
+function indexTaskSnapshotHash(indexText) {
+  const rows = indexTaskRows(indexText).map((row) => {
+    const cells = indexTaskCells(row);
+    return `${(cells[0] || '').toLowerCase()}=${(cells[4] || '').toLowerCase()}`;
+  });
+  return crypto.createHash('sha256').update(rows.join('|')).digest('hex').slice(0, 16);
+}
+
+function firstOpenIndexTaskId(indexText) {
+  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;
+  }
+  return null;
+}
+
+async function readIndexSnapshot(runRoot) {
+  try {
+    return await fs.readFile(path.join(runRoot, 'docs', 'AI_HANDOFF', 'INDEX.md'), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
 // ─── Session intent (does THIS session CURRENTLY drive the run?) ──────────
 // Structured-evidence rules live in the shared handoff-intent module so the
 // SessionStart resume hook and this Stop lane classify a transcript identically.
@@ -894,7 +1250,13 @@ export async function transcriptShowsHandoffRun(transcriptPath, opts = {}) {
 /**
  * Mutate `.ukit/storage/cache/stop-coordinator/state.json`'s `handoff` slot:
  * { signature, count }. Same signature as last time → count+1; a moved cursor
- * resets the streak. Returns the committed streak count.
+ * or task snapshot resets the streak (the signature carries the INDEX
+ * ids+statuses hash, so reconciling a new task or moving a task status counts
+ * as progress). Also maintains the sibling `handoffTask` slot:
+ * { snapshotHash, firstOpenTaskId, failingCount } — `failingCount` accrues only
+ * while the completion gate keeps blocking on the SAME first-open task and
+ * snapshot, and resets to 0 on any progress or a non-failing stop. Returns
+ * `{ count, failingCount }` (both null only when the state file is unwritable).
  *
  * RC-4: a lock-busy acquisition used to return null, and the release branch
  * required `streak !== null` — so a leaked state lock froze the
@@ -904,7 +1266,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 }) {
+async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs, snapshotHash = '', firstOpenTaskId = null, failing = false }) {
   const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'stop-coordinator', 'state.json');
   const bump = async () => {
     let current = {};
@@ -913,13 +1275,19 @@ async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
     } catch {}
     const prev = current.handoff || {};
     const count = prev.signature === signature ? (Number(prev.count) || 0) + 1 : 1;
+    const prevTask = current.handoffTask || {};
+    const sameFailingTask = prevTask.snapshotHash === snapshotHash
+      && (prevTask.firstOpenTaskId || null) === (firstOpenTaskId || 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 } }, null, 1)}\n`,
+      `${JSON.stringify({ ...current, handoff: { signature, count }, handoffTask: { snapshotHash, firstOpenTaskId, failingCount } }, null, 1)}\n`,
       'utf8',
     );
-    return count;
+    return { count, failingCount };
   };
   try {
     const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, bump);
@@ -932,7 +1300,7 @@ async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
     // keeps advancing behind a wedged or leaked lock.
     return await bump();
   } catch {
-    return null;
+    return { count: null, failingCount: null };
   }
 }
 
@@ -944,19 +1312,28 @@ async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
  * premature "done" reply gets bounced straight back into the pipeline. Releases
  * when the cursor says `done` (or `blocked` — a genuinely stuck run is a
  * legitimate final report), when RUN.md is absent/unreadable, or when the same
- * un-advancing cursor has already bounced `maxStalledBlocks` stops in a row
- * (liveness breaker — the gate must never be an unstoppable loop).
+ * un-advancing cursor AND task snapshot have already bounced `maxStalledBlocks`
+ * stops in a row (liveness breaker — the gate must never be an unstoppable
+ * loop).
  *
  * Exit predicate (mechanic #7): when RUN.md carries an `ExitPredicate:` line,
  * `Phase: done` is only accepted if the predicate evaluates true — a `done`
- * claim with failing terms is bounced back with the per-term state. A missing
- * predicate keeps the legacy phase-only release; `Phase: blocked` stays
+ * claim with failing terms is bounced back with the per-term state. A `done`
+ * claim WITHOUT a predicate evaluates the default `all(index:all-done)` (the
+ * goal-completion floor: a run-all goal cannot claim done over an unfinished
+ * backlog); a project with NO INDEX.md at all keeps the legacy phase-only
+ * release because there is nothing in scope to prove. `Phase: blocked` stays
  * terminal either way. The predicate is never relaxed: the stalled-cursor
  * advisory reports its state so a plateau is visible, not silent.
  *
+ * Same failing task (task #5): when the completion gate keeps blocking on the
+ * same first-open task across consecutive stops, the lane releases after
+ * `maxAttemptsPerFailure` failures — retrying the same edit is a loop, not
+ * progress.
+ *
  * Advisory lane: EVERY failure path returns { kind: 'none' }, never throws.
  */
-export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null, stopHookActive = false } = {}) {
+export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null, stopHookActive = false, completionKind = null } = {}) {
   // `runRoot` is the checkout whose RUN.md cursor this session may be held to: the
   // git-verified linked worktree when the session runs in one, else `projectRoot`.
   // Policy (gate config) stays with `projectRoot`; the cursor, its exit predicate
@@ -970,14 +1347,38 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
   } catch {
     return { kind: 'none' };
   }
-  const { command, goal, phase, cursor, next, exitPredicate } = parseRunCursor(text);
+  const { command, goal, phase, cursor, next, exitPredicate, goalScope } = parseRunCursor(text);
   // 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') {
     return { kind: 'none' };
   }
-  if (terminal === 'done' && !exitPredicate) return { kind: 'none' }; // legacy phase-only release
+  // Default exit predicate (goal completion): a `done` cursor with no explicit
+  // ExitPredicate is no longer released on phase alone when the project HAS a
+  // task index — the default `all(index:all-done)` applies so a run-all goal
+  // cannot claim done over an unfinished backlog. No INDEX.md at all → the
+  // legacy phase-only release (nothing in scope to prove).
+  let effectivePredicate = exitPredicate;
+  let predicateIsDefault = false;
+  let openNextCycle = null;
+  if (terminal === 'done' && !effectivePredicate) {
+    const doneIndex = await readIndexSnapshot(runRoot);
+    if (!doneIndex.trim()) return { kind: 'none' }; // legacy release: no index, nothing in scope
+    // A finalized cycle resets INDEX.md to a header-only table before `Phase: done`:
+    // zero task rows = nothing in scope, so release rather than fail all-done.
+    if (!/^\s*\|\s*TASK-/im.test(doneIndex)) {
+      // Header-only INDEX = this CYCLE is finalized, not necessarily the GOAL: a run-all goal
+      // continues while consumable queued blueprints remain (or the backlog is unreadable).
+      if (goalScope !== 'run-all') return { kind: 'none' };
+      const remaining = await pendingQueuedBlueprints(runRoot);
+      if (Array.isArray(remaining) && remaining.length === 0) return { kind: 'none' };
+      openNextCycle = { remaining };
+    } else {
+      effectivePredicate = 'all(index:all-done)';
+      predicateIsDefault = true;
+    }
+  }
 
   // Session scope: a run owned by another session (or abandoned) must not
   // hijack an unrelated session, and a session whose CURRENT intent is planning
@@ -989,22 +1390,56 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
     return { kind: 'none' };
   }
 
+  if (terminal === 'done' && openNextCycle) {
+    const names = openNextCycle.remaining;
+    return {
+      kind: 'block',
+      reason: [
+        'UKit run-all goal: this cycle is finalized but the GOAL is not complete — ',
+        names === null
+          ? 'the queued backlog (docs/AI_HANDOFF/queued/) could not be read, so remaining work is unknown, not zero.'
+          : `${names.length} queued blueprint(s) remain: ${names.slice(0, 5).join(', ')}.`,
+        '',
+        'CONTINUE IMMEDIATELY: open the next cycle — fold the next queued blueprint into',
+        'INDEX.md / tasks/ (P2), set `Phase:` to a live phase, and execute it. Archive each',
+        'consumed blueprint to archive/blueprints/. Set `Phase: blocked` only for a real external blocker.',
+      ].join('\n').replace('— \n', '— '),
+    };
+  }
+
   if (terminal === 'done') {
     let predicate;
     try {
-      predicate = await evaluateExitPredicate(runRoot, exitPredicate);
+      predicate = await evaluateExitPredicate(runRoot, effectivePredicate, { goalScope });
     } catch {
       return { kind: 'none' }; // advisory lane: evaluator failure never wedges a stop
     }
     if (predicate.ok) return { kind: 'none' };
+    // Goal derivation over the CURRENT index snapshot — informs the bounce with
+    // the mechanical goal state (release stays predicate-owned: verification
+    // evidence belongs to the completion-gate lane, not the cursor lane).
+    let goalLine = '';
+    try {
+      const doneIndex = await readIndexSnapshot(runRoot);
+      const claimState = await evalAgentsNoneRunning(runRoot);
+      const goal = deriveGoalStatus({
+        runCursor: { phase },
+        tasks: indexTasks(doneIndex),
+        ledger: null,
+        // Unreadable registry proves nothing → treated as running (fail closed).
+        agentsRunning: !claimState.pass,
+      });
+      goalLine = `  Goal status:    ${goal.status}${goal.nextCycle ? ' (next cycle — executable work remains)' : ''}`;
+    } catch { /* enrichment only — never changes the decision */ }
     const lines = [
       'UKit handoff run claims `Phase: done` but its ExitPredicate is not satisfied — this',
       'stop is refused. "Done" means the predicate the planner wrote at P2 evaluates true;',
       'a plateau is not a stop and the predicate is never relaxed.',
       '',
       `  Goal:           ${goal || '(not recorded)'}`,
-      `  ExitPredicate:  ${exitPredicate}`,
+      `  ExitPredicate:  ${effectivePredicate}${predicateIsDefault ? '  (default — no ExitPredicate line recorded)' : ''}`,
       `  Predicate state: ${formatPredicateState(predicate)}`,
+      ...(goalLine ? [goalLine] : []),
       '',
       'CONTINUE IMMEDIATELY: read docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md, finish',
       'the work the failing terms name (or record the real external blocker and set',
@@ -1037,14 +1472,28 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
     };
   }
 
-  const signature = `${phase}|${cursor}|${next}`;
-  const streak = await bumpHandoffStallCount({ projectRoot: runRoot, signature, lockBudgetMs });
+  // No-progress breaker inputs: the stall signature now carries the INDEX
+  // ids+statuses hash, so an unchanged task snapshot accrues toward the cap even
+  // when the cursor wording keeps moving — and reconciling a new task or moving
+  // a task status resets it (real goal progress).
+  const indexText = await readIndexSnapshot(runRoot);
+  const snapshotHash = indexTaskSnapshotHash(indexText);
+  const firstOpenTask = firstOpenIndexTaskId(indexText);
+  const signature = `${phase}|${cursor}|${next}|${snapshotHash}`;
+  const streak = await bumpHandoffStallCount({
+    projectRoot: runRoot,
+    signature,
+    lockBudgetMs,
+    snapshotHash,
+    firstOpenTaskId: firstOpenTask,
+    failing: completionKind === 'block',
+  });
   // Reentrancy valve (stop_hook_active): Claude Code sets it when this Stop fires
   // inside the continuation turn WE forced. The same cursor signature seen again
   // (streak > 1) means that continuation made no cursor progress — blocking again
   // is a no-progress loop, so release once instead of waiting for the stalled cap.
   // A moved cursor resets the streak to 1 and keeps blocking (real progress).
-  if (stopHookActive === true && streak !== null && streak > 1) {
+  if (stopHookActive === true && streak !== null && streak.count > 1) {
     return {
       kind: 'advisory',
       systemMessage:
@@ -1053,11 +1502,11 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
         `RUN.md is untouched; resume with /ukit:handoff-fullstack or clear with /ukit:handoff-clear.`,
     };
   }
-  if (streak !== null && streak > gate.maxStalledBlocks) {
+  if (streak !== null && streak.count > gate.maxStalledBlocks) {
     let predicateState = 'no ExitPredicate recorded';
-    if (exitPredicate) {
+    if (effectivePredicate) {
       try {
-        predicateState = formatPredicateState(await evaluateExitPredicate(runRoot, exitPredicate));
+        predicateState = formatPredicateState(await evaluateExitPredicate(runRoot, effectivePredicate, { goalScope }));
       } catch {
         predicateState = 'predicate evaluation failed';
       }
@@ -1066,13 +1515,29 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
       kind: 'advisory',
       systemMessage:
         `[ukit-stop-coordinator] handoff-cursor released this stop: the run cursor ` +
-        `("${signature}") has not advanced across ${streak - 1} consecutive blocked stops ` +
+        `("${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}. ` +
         `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.`,
     };
   }
+  // 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.
+  if (streak !== null && streak.failingCount >= gate.maxAttemptsPerFailure && firstOpenTask) {
+    return {
+      kind: 'advisory',
+      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.`,
+    };
+  }
 
   const lines = [
     'UKit handoff run in progress — this stop is refused. A handoff-fullstack cycle is still',
@@ -1188,6 +1653,111 @@ export async function detectUserInterruption(transcriptPath, {
   }
 }
 
+// ─── Provider quota / rate-limit pause (goal-loop liveness) ────────────────
+// A provider quota exhaustion is a genuine external pause: forcing continuation
+// would bounce the model against a wall, and reporting completion would be a
+// lie. The gate RELEASES such a stop with an advisory and marks the run cursor
+// PAUSED (the `Paused: yes` line — the exact marker runCursorPaused reads —
+// with `Phase:` untouched), so a later resume is possible. Never COMPLETED.
+//
+// 'stream_disconnected' is deliberately NOT a quota signature: a dropped stream
+// is a retry, not a pause.
+export const QUOTA_SCAN_MAX_BYTES = 64 * 1024;
+export const QUOTA_SCAN_BUDGET_MS = 500;
+export const QUOTA_LIMIT_RE = /\busage limit\b|\brate limit\b|\bquota\b|\b429\b|\bcredit balance\b/i;
+
+/** First quota/rate-limit signature in the text (lowercased), or null. */
+export function detectQuotaSignal(text) {
+  const m = QUOTA_LIMIT_RE.exec(String(text || ''));
+  return m ? m[0].toLowerCase() : null;
+}
+
+/**
+ * Quota signature in STRUCTURED provider-error records only. Ordinary
+ * assistant/user/tool text that merely mentions "rate limit" or "429" (code,
+ * discussion) must never pause a run, so each JSONL line is parsed and only
+ * error records (`isApiErrorMessage`, error/api_error type or subtype, or an
+ * `error` field) are scanned. A partial first line of the tail fails to parse
+ * and is skipped.
+ */
+export function detectQuotaSignalInTranscript(text) {
+  for (const line of String(text || '').split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{')) continue;
+    let rec;
+    try { rec = JSON.parse(t); } catch { continue; }
+    if (!rec || typeof rec !== 'object') continue;
+    const kind = `${rec.type || ''} ${rec.subtype || ''}`;
+    const structured = rec.isApiErrorMessage === true || /\berror\b|api_error/i.test(kind) || rec.error != null;
+    if (!structured) continue;
+    const hit = detectQuotaSignal(JSON.stringify(rec.error ?? rec.message ?? rec.content ?? ''));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/**
+ * Bounded tail scan of the host transcript (plus any caller-supplied text) for
+ * a quota/rate-limit signature. Unknown/unreadable/over-budget → null, so a
+ * lost read never pauses a healthy run.
+ */
+export async function detectQuotaPauseSignal({ transcriptPath = null, extraText = '' } = {}) {
+  if (typeof extraText === 'string' && extraText) {
+    const direct = detectQuotaSignal(extraText);
+    if (direct) return direct;
+  }
+  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return null;
+  let handle;
+  try {
+    handle = await fs.open(transcriptPath, 'r');
+    const size = Number((await handle.stat()).size) || 0;
+    const start = Math.max(0, size - QUOTA_SCAN_MAX_BYTES);
+    const deadline = Date.now() + QUOTA_SCAN_BUDGET_MS;
+    const buf = Buffer.allocUnsafe(size - start);
+    let got = 0;
+    while (got < buf.length) {
+      if (Date.now() > deadline) return null;
+      const { bytesRead } = await handle.read(buf, got, buf.length - got, start + got);
+      if (!bytesRead) break;
+      got += bytesRead;
+    }
+    return detectQuotaSignalInTranscript(buf.toString('utf8', 0, got));
+  } catch {
+    return null;
+  } finally {
+    try { await handle?.close(); } catch {}
+  }
+}
+
+/**
+ * Mark RUN.md paused WITHOUT touching its `Phase:` line: write/replace a
+ * literal `Paused: yes` line — the exact marker the shared `runCursorPaused`
+ * contract reads, so every consumer (resume hook, Stop gate, omp bridge) sees
+ * the same pause. Idempotent; atomic tmp+rename; missing RUN.md → no-op.
+ */
+export async function markRunCursorPaused(runRoot) {
+  const runMdPath = path.join(runRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
+  let text;
+  try {
+    text = await fs.readFile(runMdPath, 'utf8');
+  } catch {
+    return { ok: false, reason: 'no-run-md' };
+  }
+  if (/^Paused:\s*yes\b/im.test(text)) return { ok: true, already: true };
+  const next = /^Paused:/m.test(text)
+    ? text.replace(/^Paused:.*$/m, 'Paused: yes')
+    : `${text.replace(/\s*$/, '\n')}Paused: yes\n`;
+  const tmp = `${runMdPath}.tmp-pause-${process.pid}-${Date.now()}`;
+  try {
+    await fs.writeFile(tmp, next, 'utf8');
+    await fs.rename(tmp, runMdPath);
+    return { ok: true, already: false };
+  } catch {
+    try { await fs.rm(tmp, { force: true }); } catch {}
+    return { ok: false, reason: 'write-failed' };
+  }
+}
+
 // ─── Once-per-stop guard ──────────────────────────────────────────────────
 /**
  * Lock-scoped dedupe: persist `{ lastStop: { key, ts } }` and report whether this
@@ -1297,6 +1867,41 @@ export async function runStopCoordinator({
     failures.watchdog = error?.message || String(error);
     process.stderr.write(`[ukit-stop-coordinator] task-watchdog evaluator failed: ${failures.watchdog}\n`);
   }
+
+  // Provider quota / rate limit: a genuine external pause. Release the stop with
+  // an advisory, mark the cursor PAUSED via the shared `Paused: yes` contract
+  // (`Phase:` untouched), and never report completion for this stop.
+  try {
+    const quotaSignal = await detectQuotaPauseSignal({
+      transcriptPath: typeof payload?.transcript_path === 'string' ? payload.transcript_path : null,
+      // Only a structured hook-payload error counts; raw input text is free-form.
+      extraText: payload?.error != null ? JSON.stringify(payload.error) : '',
+    });
+    if (quotaSignal) {
+      const pause = await markRunCursorPaused(await resolveRunRoot(projectRoot, payload?.cwd));
+      return {
+        skip: null,
+        merged: {
+          decision: null,
+          reason: undefined,
+          quotaPause: true,
+          // This early return bypasses the shared terminalOutcome assignment
+          // below, so the paused outcome is stamped here: a quota pause waits,
+          // it is never COMPLETE.
+          terminalOutcome: 'WAIT_FOR_APPROVAL',
+          systemMessage:
+            `[ukit-stop-coordinator] stop released: a provider quota/rate-limit signal ("${quotaSignal}") ` +
+            `was detected. ` + (pause.ok
+              ? 'The run cursor is marked PAUSED; nothing was resumed or completed. '
+              : 'No RUN.md cursor found to pause; nothing was resumed or completed. ')
+            + 'Continue in a NEW message (or /ukit:handoff-fullstack) once the quota resets.',
+          policyOwner: 'quota-pause',
+          policies: ['quota-pause'],
+        },
+      };
+    }
+  } catch { /* advisory lane: detection failure never changes the stop */ }
+
   let handoff = null;
   try {
     handoff = await evaluateHandoffCursor({
@@ -1306,6 +1911,7 @@ export async function runStopCoordinator({
       lockBudgetMs,
       transcriptPath: typeof payload?.transcript_path === 'string' ? payload.transcript_path : null,
       stopHookActive: payload?.stop_hook_active === true,
+      completionKind: completion?.kind ?? null,
     });
   } catch (error) {
     failures.handoff = error?.message || String(error);
@@ -1321,11 +1927,12 @@ export async function runStopCoordinator({
   } catch { /* detector failure keeps the original decision */ }
 
   // Termination contract (label only; no new hook, no LLM): every coordinated stop ends in one
-  // outcome. A loop-breaker release is BLOCKED_AND_STOP, never approval; a PAUSED run waits.
+  // outcome. A loop-breaker release is BLOCKED_AND_STOP, never approval; a PAUSED run
+  // (user interruption or quota pause) waits — it is never COMPLETE.
   // Advisory label only (nothing consumes it); a gate block approves nothing.
   merged.terminalOutcome = merged.decision === 'block' ? 'CONTINUE_REQUIRED'
     : merged.loopBreak === true ? 'BLOCKED_AND_STOP'
-    : handoff?.waitForApproval === true ? 'WAIT_FOR_APPROVAL' : 'COMPLETE_AND_STOP';
+    : merged.quotaPause === true || handoff?.waitForApproval === true ? 'WAIT_FOR_APPROVAL' : 'COMPLETE_AND_STOP';
 
   // C85 TASK-015 (BL-015): advisory review-policy verdict. The evaluator runs
   // only when a route record exists; its action + namedCheck are recorded on