@ngockhoale/ukit 2.7.7 → 2.7.8

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -294,7 +294,8 @@ export async function readRouteState(projectRoot, payload = {}) {
 }
 
 export async function readExecutionLedger(projectRoot, payload = {}) {
-  return readJson(ledgerPath(projectRoot, payload), null);
+  const target = ledgerPath(projectRoot, payload);
+  return mergeContinuationSidecar(await readJson(target, null), target);
 }
 
 function promptKeyFromText(promptText) {
@@ -313,7 +314,7 @@ function hasUnfinishedCompletion(state = {}, ledger = {}) {
   if (!IMPLEMENT_MODES.has(mode)) return false;
   const required = requiredEvidence(state);
   if (required.length === 0) return false;
-  return required.some((item) => !evidenceSatisfied(item, ledger, state?.routeSummary || {}));
+  return required.some((item) => !evidenceSatisfied(item, ledger, state));
 }
 
 function resumeSessionHash(sessionId) {
@@ -400,9 +401,38 @@ function explicitError(payload = {}) {
     payload.tool_result?.is_error,
     payload.tool_response?.isError,
     payload.tool_response?.is_error,
+    // omp tool details carry their own error flag (eval cells, bash timeouts).
+    payload.details?.isError,
+    payload.tool_output?.details?.isError,
+    payload.tool_result?.details?.isError,
   ].some((value) => value === true);
 }
 
+// omp tool results do not all spell the exit code the same way: bash details
+// carry `exitCode` (non-zero only), other producers serialize `exit_code`, and
+// eval results report per-cell codes under `details.cells[].exitCode`. A missed
+// shape used to journal a failed verification as exitCode null → success, so
+// evidence never satisfied and the Stop gate bounced to the cap.
+function detailsExitCode(details) {
+  if (!details || typeof details !== 'object') return null;
+  for (const value of [details.exitCode, details.exit_code]) {
+    // Number(null) === 0 — a JSON `"exitCode": null` must fall through to the
+    // next probe (exit_code, then cells[]), never journal as a successful exit.
+    if (value === undefined || value === null) continue;
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  const cells = Array.isArray(details.cells) ? details.cells : [];
+  let lastCode = null;
+  for (const cell of cells) {
+    const number = Number(cell?.exitCode ?? cell?.exit_code);
+    if (!Number.isFinite(number)) continue;
+    if (number !== 0) return number;
+    lastCode = number;
+  }
+  return lastCode;
+}
+
 function extractExitCode(payload = {}) {
   const candidates = [
     payload.tool_output?.exitCode,
@@ -415,8 +445,20 @@ function extractExitCode(payload = {}) {
     payload.tool_response?.exit_code,
     payload.exitCode,
     payload.exit_code,
+    // omp details shapes: the bridge mirrors event.details under BOTH
+    // tool_output.details and tool_result.details, and eval results nest the
+    // real code under details.cells[].
+    detailsExitCode(payload.tool_output?.details),
+    detailsExitCode(payload.tool_result?.details),
+    detailsExitCode(payload.details),
+    detailsExitCode(payload.tool_response?.details),
+    detailsExitCode(payload.tool_output),
+    detailsExitCode(payload.tool_result),
   ];
   for (const value of candidates) {
+    // Number(null) === 0 — a JSON `"exitCode": null` (or a details probe that
+    // found nothing) must read as "no code", never as a successful exit.
+    if (value === undefined || value === null) continue;
     const number = Number(value);
     if (Number.isFinite(number)) return number;
   }
@@ -801,6 +843,96 @@ function journalQuarantinePathFor(target) {
   return `${journalPathFor(target)}.quarantine`;
 }
 
+// F-4: the continuation counter is STATE, not a journal row. When the journal is
+// full (or its lock unavailable) a continuation/notified event used to be rejected
+// outright, so MAX_CONTINUATIONS fired several bounces late — or never while the
+// ledger lock stayed contended. Rejected counter events land in this small sidecar
+// instead; readExecutionLedger merges it into the view every evaluator sees, and
+// the next committed ledger write folds it in and removes it.
+function continuationSidecarPathFor(target) {
+  return `${target}.continuations.json`;
+}
+
+// Overlay sidecar counter state onto the ledger when the sidecar is newer than the
+// ledger's last continuation. A sidecar at or behind the ledger is already folded
+// (or written for a superseded request) and is ignored — never double-counted.
+// When the main file is absent the sidecar IS the counter state: returning null
+// hid every tick from evaluators and the next committed write deleted the sidecar
+// unread, so the cap fired late. A sidecar without counter state still yields null
+// — the no-ledger contract is preserved.
+async function mergeContinuationSidecar(ledger, target) {
+  let sidecar = null;
+  try {
+    sidecar = JSON.parse(await fs.readFile(continuationSidecarPathFor(target), 'utf8'));
+  } catch {
+    return ledger;
+  }
+  if (!sidecar || typeof sidecar !== 'object') return ledger;
+  const sidecarAt = Number(sidecar.lastContinuationAt) || 0;
+  if (!ledger) {
+    const hasState = sidecarAt > 0
+      || Number(sidecar.continuationCount) > 0
+      || sidecar.notified === true;
+    if (!hasState) return null;
+    return {
+      requestKey: sidecar.requestKey ?? null,
+      promptKey: sidecar.promptKey ?? null,
+      continuationRequestKey: sidecar.requestKey ?? null,
+      continuationCount: Number(sidecar.continuationCount) || 0,
+      noProgressCount: Number(sidecar.noProgressCount) || 0,
+      lastProgressDigest: sidecar.lastProgressDigest ?? null,
+      notified: sidecar.notified === true,
+      lastContinuationAt: sidecarAt,
+      updatedAt: Number(sidecar.updatedAt) || sidecarAt,
+    };
+  }
+  const ledgerAt = Number(ledger.lastContinuationAt) || 0;
+  if (!(sidecarAt > ledgerAt)) return ledger;
+  return {
+    ...ledger,
+    continuationCount: Number(sidecar.continuationCount) || 0,
+    noProgressCount: Number(sidecar.noProgressCount) || 0,
+    continuationRequestKey: sidecar.requestKey ?? ledger.continuationRequestKey ?? null,
+    lastProgressDigest: sidecar.lastProgressDigest ?? ledger.lastProgressDigest ?? null,
+    notified: ledger.notified === true || sidecar.notified === true,
+    lastContinuationAt: sidecarAt,
+    updatedAt: Math.max(Number(ledger.updatedAt) || 0, sidecarAt),
+  };
+}
+
+// Best-effort counter tick for a continuation/notified event the journal rejected.
+// Reads the merged ledger view (main file + existing sidecar) so consecutive ticks
+// accumulate even while the main lock stays busy. Returns { ok } — a sidecar write
+// failure means the tick is genuinely lost and the caller reports the rejection.
+async function bumpContinuationSidecar(target, event) {
+  try {
+    const base = (await mergeContinuationSidecar(await readJson(target, null), target)) || {};
+    const applied = event.type === 'notified'
+      ? { ...base, notified: true, updatedAt: Date.now() }
+      : applyContinuationToLedger(base, event);
+    // The merge gate requires sidecarAt > ledgerAt. A notified tick inherits the
+    // base stamp unchanged, so it must be bumped past the base it was computed
+    // from — otherwise the tick is invisible to every evaluator and the cap's
+    // final notice loops forever while contention persists. The +1 floor also
+    // covers a continuation landing in the same millisecond as the base stamp.
+    const baseAt = Number(base.lastContinuationAt) || 0;
+    const stampedAt = Math.max(Number(applied.lastContinuationAt) || 0, baseAt + 1);
+    await writeJsonAtomic(continuationSidecarPathFor(target), {
+      requestKey: event?.requestKey ?? applied.requestKey ?? applied.continuationRequestKey ?? null,
+      promptKey: event?.promptKey ?? applied.promptKey ?? null,
+      continuationCount: Number(applied.continuationCount) || 0,
+      noProgressCount: Number(applied.noProgressCount) || 0,
+      lastProgressDigest: applied.lastProgressDigest ?? null,
+      notified: applied.notified === true,
+      lastContinuationAt: stampedAt,
+      updatedAt: Date.now(),
+    });
+    return { ok: true };
+  } catch {
+    return { ok: false };
+  }
+}
+
 function newEventId() {
   return `${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
 }
@@ -1214,6 +1346,11 @@ export async function recordLedgerEvent(event, {
     // Consume the journal only after the ledger write landed: a crash before this line
     // leaves the journal intact and the next drain re-applies idempotently by eventId.
     if (drained.commit) await drained.commit();
+    // The continuation sidecar was already merged into `current` (and therefore into
+    // the ledger just written): its ticks are now durable state, so the sidecar is
+    // retired. A tick landing between the read and this rm is lost — same accepted
+    // window as the journal drain — but the breaker still advances.
+    try { await fs.rm(continuationSidecarPathFor(target), { force: true }); } catch {}
     return { committed: true, eventId, value, drained: drained.applied, quarantined: drained.quarantined };
   });
   if (outcome.ok) {
@@ -1228,9 +1365,16 @@ export async function recordLedgerEvent(event, {
   // NEVER mutated unlocked — journal the event once; the next acquired lock reconciles it.
   const record = buildJournalRecord({ event, eventId, payload, routeState: routeState || null });
   const journalResult = await appendJournalRecord(target, record, { signal, deadlineMs });
-  return journalResult.ok
-    ? { journaled: true, eventId }
-    : { rejected: true, eventId, reason: journalResult.reason };
+  if (journalResult.ok) return { journaled: true, eventId };
+  // F-4: continuation/notified are counter state, not journal rows — a journal-full
+  // (or journal-unavailable) rejection must still advance the counter or
+  // MAX_CONTINUATIONS fires late/never. Land the tick in the sidecar the evaluator
+  // merges; only a sidecar write failure is a real rejection.
+  if (event.type === 'continuation' || event.type === 'notified') {
+    const sidecar = await bumpContinuationSidecar(target, event);
+    if (sidecar.ok) return { counted: true, eventId, reason: journalResult.reason };
+  }
+  return { rejected: true, eventId, reason: journalResult.reason };
 }
 
 // TASK-027: the receipt is classified (kind, file, command, targeted/broad scope) from the
@@ -1291,6 +1435,44 @@ export async function recordExecutionReceipt({
   );
 }
 
+// F-15: mirror of isExplicitBroadVerificationRequest in
+// templates/.claude/hooks/verification-guard.sh — the guard uses this prompt signal to
+// let a broad suite run under a targeted policy, so the completion gate must honor the
+// same signal when it classifies the resulting broad receipt. Keep both lists in sync.
+function isExplicitBroadVerificationRequest(promptText) {
+  const text = String(promptText || '').toLowerCase();
+  return [
+    /run (the )?full test suite/,
+    /run all tests/,
+    /full verification/,
+    /verify everything/,
+    /run the whole suite/,
+    /run broad verification/,
+    /full suite/,
+    /chạy (?:toàn bộ|full) test/,
+    /chạy hết test/,
+    /chạy full test suite/,
+    /verify toàn bộ/,
+    /kiểm tra toàn bộ/,
+    // Plan-driven execution prompts often authorize the plan's final broad
+    // verification without spelling it as "full test suite".
+    /(?:run|execute|implement|do)\b.*\bfull\b.*\b(?:prd\s+)?plan\b/,
+    /\bfull\b.*\b(?:prd\s+)?plan\b.*\b(?:verify|verification|test|tests)\b/,
+    /(?:chạy|lam|làm|thực hiện|triển khai)\b.*\bfull\b.*\b(?:prd|plan|ke hoach|kế hoạch)\b/,
+    /\bfull\b.*\b(?:prd|plan|ke hoach|kế hoạch)\b.*\b(?:verify|verification|test|tests|kiểm tra)\b/,
+  ].some((pattern) => pattern.test(text));
+}
+
+// The route cache strips prompt text (route-task.mjs *ForCache deletes it), so the live
+// state is the only place the explicit-broad signal survives for the evaluator.
+function explicitBroadVerificationRequested(state = {}) {
+  const routingContext = state?.routingContext || {};
+  return [
+    routingContext.lastExplicitUserPromptText,
+    routingContext.promptText,
+  ].some((promptText) => isExplicitBroadVerificationRequest(promptText));
+}
+
 function requiredEvidence(state = {}) {
   const routeSummary = state?.routeSummary || {};
   const contractEvidence = routeSummary.executionContract?.completionEvidence;
@@ -1300,14 +1482,19 @@ function requiredEvidence(state = {}) {
   return [...new Set(routeSummary.completionState?.missingEvidence || [])];
 }
 
-function evidenceSatisfied(evidence, ledger = {}, routeSummary = {}) {
+function evidenceSatisfied(evidence, ledger = {}, state = {}) {
+  const routeSummary = state?.routeSummary || {};
   if (evidence === 'write-evidence') return ledger.writeSucceeded === true;
   if (evidence === 'verification-evidence') {
     // WS-C: when the route names concrete verification commands, only a receipt that ran
     // one of them counts — an unrelated `yarn test` no longer satisfies the gate.
+    // F-15: unless the user explicitly requested/approved a broad suite — the same
+    // prompt signal verification-guard.sh honors — in which case a passing
+    // scope='broad' receipt (verificationSucceeded) satisfies the gate too.
     const routedCommands = routedVerificationCommands(routeSummary);
     if (routedCommands.length > 0) {
-      return ledger.targetedVerificationSucceeded === true;
+      return ledger.targetedVerificationSucceeded === true
+        || (explicitBroadVerificationRequested(state) && ledger.verificationSucceeded === true);
     }
     return ledger.verificationSucceeded === true;
   }
@@ -1433,7 +1620,7 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
     || ledger.requestKey === state.requestKey
     || (ledger.promptKey && evidencePromptKey(state) === ledger.promptKey);
   const effectiveLedger = sameRequest ? ledger : {};
-  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, routeSummary));
+  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, state));
   if (missingEvidence.length === 0) {
     // Silent success: the route is present and every required evidence is satisfied. Marked
     // `complete` so the CLI dispatch recognizes it BEFORE the loud final else — otherwise a
@@ -1609,12 +1796,19 @@ async function readStdin() {
 
 // Malformed hook input crashes the evaluate BEFORE any route/session can be read, so the only
 // stable identity is the project root. Count consecutive crashes there; past MAX_GATE_CRASHES,
-// release LOUD naming the crash and the remedy instead of blocking a corrupt hook forever. Any
-// counter I/O failure fails SAFE to block (still loud, never silent). A successful evaluate
-// resets the count.
+// release LOUD naming the crash and the remedy instead of blocking a corrupt hook forever. A
+// successful evaluate resets the count.
+//
+// F-3: the counter exists to break the infinite bounce — so losing the count must
+// never BECOME the infinite bounce. When the counter write fails, fail OPEN (loud
+// release) instead of emitting an unconditional block that can never reach the cap.
 async function handleEvaluateCrash(projectRoot, error) {
   const detail = `malformed hook input crashed the completion gate (${error?.message || error})`;
   const blockReason = () => `${detail}. This is the UKit completion gate, not the task — re-send the task in a new message so the hook payload is regenerated.`;
+  const loudRelease = (message) => {
+    process.stderr.write(`[ukit-completion] ${message}\n`);
+    process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
+  };
   let count = 0;
   try {
     const current = await readJson(crashCounterPath(projectRoot), null);
@@ -1625,15 +1819,21 @@ async function handleEvaluateCrash(projectRoot, error) {
   const next = count + 1;
   try {
     await writeJsonAtomic(crashCounterPath(projectRoot), { count: next, updatedAt: Date.now() });
-  } catch {
-    // Counter unwritable: we cannot bound the crash loop, but silence is never an option.
-    process.stdout.write(`${JSON.stringify({ decision: 'block', reason: blockReason() })}\n`);
+  } catch (writeError) {
+    // Counter unwritable: the crash loop can no longer be bounded, so blocking again
+    // would bounce this stop forever. Release loudly — never silently.
+    loudRelease(
+      `UKit completion gate: ${detail}. The crash counter could not be persisted `
+      + `(${writeError?.message || writeError}), so the gate cannot bound repeated crashes and is `
+      + 'releasing loudly instead of blocking forever. Run: ukit install to refresh the runtime, '
+      + 'then re-send the task in a new message.',
+    );
     return;
   }
   if (next >= MAX_GATE_CRASHES) {
-    const message = `UKit completion gate: ${detail}. This recurred ${next} times and cannot be bounded, so the stop is releasing loudly instead of blocking again. The hook payload is corrupt — run: ukit install to refresh the runtime, then re-send the task in a new message.`;
-    process.stderr.write(`[ukit-completion] ${message}\n`);
-    process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
+    loudRelease(
+      `UKit completion gate: ${detail}. This recurred ${next} times and cannot be bounded, so the stop is releasing loudly instead of blocking again. The hook payload is corrupt — run: ukit install to refresh the runtime, then re-send the task in a new message.`,
+    );
     return;
   }
   process.stdout.write(`${JSON.stringify({ decision: 'block', reason: blockReason() })}\n`);

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -437,6 +437,36 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
   return { results, elapsedMs, budgetMs: totalBudgetMs, budgetExhausted, skippedFailClosed };
 }
 
+// TASK-006 (SPEC §S6, F-RC-2): a timed-out in-proc step abandons its
+// Promise.race loser — when that loser holds ref'd libuv handles (timers,
+// watchers, sockets) the event loop stays pinned and the host waits the full
+// registered 30–73s timeout for a process that already produced its verdict.
+// Every emit path ends here: flush stdout/stderr, then exit explicitly. The
+// flush is bounded — a reader that never drains must not turn the fix into a
+// new stall.
+const FLUSH_EXIT_MS = Number(process.env.UKIT_HOOK_FLUSH_EXIT_MS || 2000);
+
+function flushStream(stream) {
+  return new Promise((resolve) => {
+    try {
+      // end() flushes every queued chunk before invoking the callback —
+      // including when the stream was already ended/destroyed (the callback
+      // still fires, with an error we deliberately ignore).
+      stream.end(() => resolve());
+    } catch {
+      resolve();
+    }
+  });
+}
+
+async function flushAndExit(code) {
+  await Promise.race([
+    Promise.all([flushStream(process.stdout), flushStream(process.stderr)]),
+    new Promise((resolve) => setTimeout(resolve, FLUSH_EXIT_MS).unref()),
+  ]);
+  process.exit(code);
+}
+
 try {
   let argv = process.argv.slice(2);
   // TASK-234: `--emit-verdict` adapts the runner for Claude Code settings.json
@@ -493,16 +523,16 @@ try {
       });
       if (emitVerdict) {
         process.stdout.write(deny);
-        process.exitCode = 0;
       } else {
         process.stdout.write(JSON.stringify({
           results: [],
           wrapperError: 'stdin staging truncated — fail-closed chain refused',
           stdinTruncated: true,
         }));
-        process.exitCode = 2;
       }
-      process.exit(emitVerdict ? 0 : 2);
+      // TASK-006: flush before exit — a bare process.exit can truncate a
+      // verdict still queued on the pipe.
+      await flushAndExit(emitVerdict ? 0 : 2);
     }
   }
   const chain = await run(payloadText, scriptPaths, {
@@ -595,10 +625,14 @@ try {
       }
     }
   }
+  // TASK-006 (F-RC-2): the verdict is on the wire — exit now. Waiting for a
+  // natural exit lets an abandoned in-proc step's ref'd handles pin the loop
+  // until the host's registered timeout kills us.
+  await flushAndExit(process.exitCode ?? 0);
 } catch (error) {
   process.stdout.write(JSON.stringify({
     results: [],
     wrapperError: error?.message || String(error),
   }));
-  process.exitCode = 1;
+  await flushAndExit(1);
 }

package/templates/.claude/ukit/runtime/hook-payload-store.mjs

@@ -16,6 +16,7 @@
 // Readers (hook-chain-runner.mjs) keep accepting the `@path` argv form unchanged.
 
 import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 
@@ -90,6 +91,62 @@ export function createPayloadReference(text, {
   }
 }
 
+// createPayloadReferenceAsync(text, {maxBytes, deadlineMs, dir}) -> Promise<reference>
+//
+// TASK-008 (SPEC §S8, OMP-6): the sync variant's mkdirSync/writeFileSync/renameSync
+// run deadline-free on the CALLER's event loop — on the omp host a stalled mount
+// freezes the whole app, and the deadlineMs check at t≈0 is decorative because a
+// stalled sync call never returns to re-check it. This variant does the same
+// atomic staging through async fs raced against a real deadline; on expiry or
+// any failure it degrades to inline transport exactly like the sync path.
+// The losing fs promise is left to settle in the background — it is unref'd by
+// the race and its result discarded; worst case it completes a tmp write that
+// the sampled sweep later reclaims.
+export async function createPayloadReferenceAsync(text, {
+  maxBytes = PAYLOAD_INLINE_MAX_BYTES,
+  deadlineMs = 250,
+  dir,
+} = {}) {
+  const payloadText = String(text ?? '');
+  const bytes = Buffer.byteLength(payloadText, 'utf8');
+  if (bytes <= maxBytes) return inlineReference(payloadText, bytes);
+  if (!(deadlineMs > 0) || !dir) return inlineReference(payloadText, bytes);
+
+  const stage = (async () => {
+    await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+    const name = `${Date.now().toString(36)}-${process.pid}-${crypto.randomBytes(6).toString('hex')}.json`;
+    const finalPath = path.join(dir, name);
+    const tmpPath = path.join(dir, `.${name}.tmp`);
+    await fsp.writeFile(tmpPath, payloadText, { encoding: 'utf8', mode: 0o600 });
+    await fsp.rename(tmpPath, finalPath);
+    return {
+      mode: 'file',
+      arg: `@${finalPath}`,
+      text: payloadText,
+      path: finalPath,
+      bytes,
+      cleanup() {
+        try { fs.rmSync(finalPath, { force: true }); } catch { /* best effort */ }
+      },
+    };
+  })();
+  // Fail-open contract (TASK-008 fix): the race must resolve to inline on ANY
+  // staging outcome that is not a completed file — deadline expiry AND fs
+  // rejection (ENOTDIR/EACCES/EROFS on a read-only or wedged mount). Racing the
+  // raw stage promise let a fast rejection propagate through runScriptChain and
+  // skip the whole hook chain; .catch(() => null) consumes it so the winner is
+  // always a reference or null. The same catch also swallows a rejection that
+  // lands after the deadline already won, so no unhandled rejection escapes.
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), deadlineMs);
+    timer.unref?.();
+  });
+  const winner = await Promise.race([stage.catch(() => null), deadline]);
+  clearTimeout(timer);
+  return winner ?? inlineReference(payloadText, bytes);
+}
+
 // probePayloadIntegrity(reference) -> null | 'missing' | 'partial'
 //
 // O(1): one stat of the file this bridge staged. Called by the bridge after the

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

@@ -168,7 +168,7 @@ export const DEDUPE_WINDOW_MS = 2000;
 // Fixed budget slices inside the default 3000ms hook deadline: the ledger child
 // gets the larger slice, each watchdog lock acquisition gets a short one.
 const LEDGER_BUDGET_MS = 1500;
-const LOCK_BUDGET_MS = 600;
+export const LOCK_BUDGET_MS = 600;
 
 const WATCHDOG_PROVENANCE_PREFIX = '[ukit-stop-coordinator] task-watchdog also requested a block: ';
 const WATCHDOG_FAILURE_PREFIX = '[ukit-stop-coordinator] task-watchdog evaluator failed (advisory lane, reported verbatim): ';
@@ -453,28 +453,43 @@ function parseRunCursor(text) {
 /**
  * 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; a lock-timeout or any
- * I/O failure returns null (fail-open — never decides the stop).
+ * resets the streak. Returns the committed streak count.
+ *
+ * RC-4: a lock-busy acquisition used to return null, and the release branch
+ * required `streak !== null` — so a leaked state lock froze the
+ * stopGateMaxStalledBlocks breaker forever and the handoff-cursor lane became an
+ * unbounded bounce loop. The breaker must ALWAYS advance: on lock-busy (or any
+ * lock error) the same read-modify-write runs best-effort unlocked. A lost tick
+ * 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 }) {
   const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'stop-coordinator', 'state.json');
+  const bump = async () => {
+    let current = {};
+    try {
+      current = JSON.parse(await fs.readFile(statePath, 'utf8')) || {};
+    } catch {}
+    const prev = current.handoff || {};
+    const count = prev.signature === signature ? (Number(prev.count) || 0) + 1 : 1;
+    await fs.mkdir(path.dirname(statePath), { recursive: true });
+    await fs.writeFile(
+      statePath,
+      `${JSON.stringify({ ...current, handoff: { signature, count } }, null, 1)}\n`,
+      'utf8',
+    );
+    return count;
+  };
   try {
-    const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, async () => {
-      let current = {};
-      try {
-        current = JSON.parse(await fs.readFile(statePath, 'utf8')) || {};
-      } catch {}
-      const prev = current.handoff || {};
-      const count = prev.signature === signature ? (Number(prev.count) || 0) + 1 : 1;
-      await fs.mkdir(path.dirname(statePath), { recursive: true });
-      await fs.writeFile(
-        statePath,
-        `${JSON.stringify({ ...current, handoff: { signature, count } }, null, 1)}\n`,
-        'utf8',
-      );
-      return count;
-    });
-    return outcome.ok ? outcome.value : null;
+    const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, bump);
+    if (outcome.ok) return outcome.value;
+  } catch {
+    // fall through to the best-effort tick below
+  }
+  try {
+    // Lock-busy: count the stop as a stall tick anyway so the liveness breaker
+    // keeps advancing behind a wedged or leaked lock.
+    return await bump();
   } catch {
     return null;
   }
@@ -547,7 +562,7 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
  * invocation is a same-session duplicate inside the window. Fail-open — an
  * unreadable/unlockable dedupe state must never disable the Stop coordinator.
  */
-async function alreadyCoordinatedThisStop({ projectRoot, sessionKey, now, dedupeWindowMs, lockBudgetMs }) {
+export async function alreadyCoordinatedThisStop({ projectRoot, sessionKey, now, dedupeWindowMs, lockBudgetMs }) {
   const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'stop-coordinator', 'state.json');
   try {
     const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, async () => {