@ngockhoale/ukit 2.7.6 → 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

@@ -97,6 +97,20 @@ function chainFailureKind(processResult) {
   }
 }
 
+// B1 (TASK-001, SPEC §FR-001): a child that emits a `hookSpecificOutput`
+// permission decision owns the verdict. `hookSpecificOutput` alone is NOT
+// enough — a child killed mid-write can carry the marker in a truncated
+// capture, and calling that a decision would exempt a genuinely-skipped gate
+// from the fail-closed verdict. A real decision is a clean exit-0 verdict.
+function emitsPermissionDecision(entry) {
+  return Boolean(entry)
+    && !entry.killed
+    && entry.code === 0
+    && entry.failureKind === 'ok'
+    && typeof entry.stdout === 'string'
+    && entry.stdout.includes('"hookSpecificOutput"');
+}
+
 function recordTiming(projectRoot, payload, timing) {
   // Timing telemetry is advisory and must never delay or block a tool call;
   // appendTelemetryRow carries the same posture (and the per-session cap).
@@ -109,12 +123,37 @@ function recordTiming(projectRoot, payload, timing) {
 // A `:0` or negative suffix is rejected (falls back) — zero would mean "no
 // budget", which silently disables the deadline; that is never a valid hook
 // contract.
+// TASK-001 (C8 / SPEC §FR-006): "rejected silently" was the bug. A `:0`/`: -1`
+// typo used to leave the suffix on the path, so the child never spawned and the
+// hook silently vanished from the chain. It now warns (never hard-fails — a
+// config typo must not block every tool call in a fail-closed chain) and runs
+// the script under the DEFAULT child budget.
+const TIMEOUT_SUFFIX_RE = /^(.*):(-?\d+(?:\.\d+)?)$/;
+
+// The ONE suffix stripper. Identity checks that need a script's declared name
+// (fail-closed lookups, skipped-gate reporting) go through it too: a `:-1` arg
+// must not look like an advisory script there while `parseScriptArg` already
+// normalized it to a gate for execution.
+function stripTimeoutSuffix(arg) {
+  const match = TIMEOUT_SUFFIX_RE.exec(String(arg ?? ''));
+  return match ? match[1] : String(arg ?? '');
+}
+
+function failClosedName(arg) {
+  return path.basename(stripTimeoutSuffix(arg));
+}
+
 function parseScriptArg(arg) {
-  const match = /^(.*):(\d+(?:\.\d+)?)$/.exec(arg || '');
-  if (!match) return { scriptPath: arg, timeoutMs: null };
-  const seconds = Number(match[2]);
-  if (!Number.isFinite(seconds) || seconds <= 0) return { scriptPath: arg, timeoutMs: null };
-  return { scriptPath: match[1], timeoutMs: Math.round(seconds * 1000) };
+  const suffix = TIMEOUT_SUFFIX_RE.exec(String(arg ?? ''));
+  if (!suffix) return { scriptPath: arg, timeoutMs: null };
+  const seconds = Number(suffix[2]);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    process.stderr.write(
+      `[ukit] ignoring invalid timeout suffix "${arg}" — using default child budget\n`,
+    );
+    return { scriptPath: suffix[1], timeoutMs: null };
+  }
+  return { scriptPath: suffix[1], timeoutMs: Math.round(seconds * 1000) };
 }
 
 // TASK-001 (SPEC §FR-001, §8): a chain arg ending in `.mjs` is an IN-PROC step —
@@ -178,7 +217,7 @@ async function runModuleStep({ scriptPath, payload, payloadText, projectRoot, en
   }
 }
 
-async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
+async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortCircuit = false, stdinStageMs = null } = {}) {
   const parsedArgs = scriptArgs.map(parseScriptArg);
   const scriptPaths = parsedArgs.map((a) => a.scriptPath);
   const payload = JSON.parse(payloadText || '{}');
@@ -224,7 +263,7 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
   const deadline = startedAt + totalBudgetMs;
   const results = [];
   let budgetExhausted = false;
-
+  let decisionEmitted = false;
   for (let scriptIndex = 0; scriptIndex < scriptPaths.length; scriptIndex++) {
     const scriptPath = scriptPaths[scriptIndex];
     const scriptName = path.basename(scriptPath);
@@ -321,7 +360,20 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
       });
     }
 
-    if (code === 2 || killed || (code !== 0 && FAIL_CLOSED_SCRIPTS.has(scriptName))) {
+    // B1 (TASK-001, SPEC §FR-001): under `--emit-verdict` a child that emits a
+    // `hookSpecificOutput` permission decision owns the verdict even at exit 0
+    // (the direct Claude contract: deny + exit 0 still blocks). The chain stops
+    // HERE, before the next child spawns — filtering the decision at emit time
+    // instead would still let the next script's side effects run (e.g.
+    // pre-edit-backup.sh backing up a file whose edit was just denied) and its
+    // stdout would be concatenated in front of the decision JSON, which Claude
+    // Code rejects as invalid JSON. The predicate is shared with the emit-time
+    // lookup so a truncated capture can never count as a decision here.
+
+    if (decisionShortCircuit && emitsPermissionDecision(results[results.length - 1])) {
+      decisionEmitted = true;
+    }
+    if (decisionEmitted || code === 2 || killed || (code !== 0 && FAIL_CLOSED_SCRIPTS.has(scriptName))) {
       break;
     }
   }
@@ -331,9 +383,12 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
   // of those unrun scripts is fail-closed, the chain must fail CLOSED — the old
   // per-script path ran every hook independently, so a timed-out advisory never
   // skipped a gate. `skippedFailClosed` carries that signal to the verdict.
-  const skippedFailClosed = scriptPaths
+  // ... unless this break WAS the decision: a decision owns the verdict, so the
+  // unrun gates are not a fail-closed gap (SPEC §FR-001 — the verdict must stay
+  // exit 0 with the decision JSON).
+  const skippedFailClosed = !decisionEmitted && scriptPaths
     .slice(results.length)
-    .some((p) => FAIL_CLOSED_SCRIPTS.has(path.basename(p)));
+    .some((p) => FAIL_CLOSED_SCRIPTS.has(failClosedName(p)));
 
   const elapsedMs = Date.now() - startedAt;
   // TASK-019: versioned rows shared with direct hooks. `outcome` reuses this
@@ -350,6 +405,18 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
     toolName: payload?.tool_name || null,
     toolUseId: payload?.tool_use_id || null,
     elapsedMs,
+    // O3 (SPEC §FR-009): the row's wall time split into the stdin stage — the
+    // bounded read this process waits on while the producer writes — and the
+    // chain's own execution. A producer holding the pipe open is then
+    // attributable instead of looking like a slow hook (the reported artifact:
+    // project-important.sh p95 = 1539ms with no row doing real work ≥ 1s).
+    // Clamped to `elapsedMs` because the split describes the row it sits on
+    // (the two are measured from different origins). Absent — not 0 and not
+    // null — when this invocation never read stdin, so a v1 reader sees the
+    // row it always saw.
+    ...(stdinStageMs === null
+      ? {}
+      : { stdinStageMs: Math.min(Math.max(0, Math.round(stdinStageMs)), elapsedMs) }),
     budgetMs: totalBudgetMs,
     budgetExhausted,
     scripts: results.map(({ scriptName, code, killed, failureKind, elapsedMs: scriptElapsedMs }) => ({
@@ -358,12 +425,48 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
       killed,
       failureKind,
       elapsedMs: scriptElapsedMs,
+      // TASK-007 (SPEC §FR-012): which steps the runner treated as gates. The
+      // doctor reads this flag instead of importing FAIL_CLOSED_SCRIPTS — the
+      // runner is the only component that knows which paths it gated, and a
+      // second copy of a security-relevant list is a drift hazard. Additive and
+      // optional: v1 readers that read the five original keys keep working.
+      failClosed: FAIL_CLOSED_SCRIPTS.has(scriptName),
     })),
   });
 
   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
@@ -384,8 +487,14 @@ try {
   // '-' reads the payload from stdin — the form Claude Code hook commands use.
   let payloadText = payloadArg;
   let stdinTruncated = false;
+  // O3: the stage window is measured HERE, around the bounded read, and not
+  // inside run() — run() starts after the payload is already in hand, and a
+  // truncated read exits before run() is ever called.
+  let stdinStageMs = null;
   if (payloadArg === '-') {
+    const stageStartedAt = Date.now();
     const staged = await readStdinBounded();
+    stdinStageMs = Date.now() - stageStartedAt;
     payloadText = staged.text;
     stdinTruncated = staged.truncated;
   } else if (payloadArg.startsWith('@')) {
@@ -402,8 +511,7 @@ try {
   // chain carries a fail-closed gate, emit deny now instead of letting gates
   // pass on a payload they never fully received.
   if (stdinTruncated) {
-    const hasFailClosed = scriptPaths.some((p) =>
-      FAIL_CLOSED_SCRIPTS.has(path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, ''))));
+    const hasFailClosed = scriptPaths.some((p) => FAIL_CLOSED_SCRIPTS.has(failClosedName(p)));
     if (hasFailClosed) {
       const deny = JSON.stringify({
         hookSpecificOutput: {
@@ -415,19 +523,25 @@ 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, { chainMarker: !emitVerdict });
+  const chain = await run(payloadText, scriptPaths, {
+    chainMarker: !emitVerdict,
+    // B1: only the --emit-verdict contract short-circuits on a decision; the
+    // omp bridge parses the JSON envelope and needs every step's context stdout.
+    decisionShortCircuit: emitVerdict,
+    stdinStageMs,
+  });
   if (!emitVerdict) {
     process.stdout.write(JSON.stringify(chain));
   } else {
@@ -435,10 +549,21 @@ try {
     // verdict even when it exits 0 (the direct Claude contract: deny + exit 0
     // still blocks). The first decision wins, matching per-script semantics
     // where each hook's output is its own verdict and a deny short-circuits.
+    // The loose lookup decides which entry is REPORTED as the verdict owner (a
+    // non-zero decision emitter stays routed through the code-2/fail-closed
+    // paths below, per SPEC §FR-001); the strict predicate decides whether that
+    // entry may claim stdout outright.
     const decisionResult = chain.results.find((r) =>
       typeof r.stdout === 'string' && r.stdout.includes('"hookSpecificOutput"'));
+    const decisionOwnsVerdict = emitsPermissionDecision(decisionResult);
     const last = decisionResult ?? chain.results[chain.results.length - 1];
 
+    // B1 (SPEC §FR-001): a clean decision owns the ENTIRE stdout — no context
+    // text before or after it. Claude Code parses stdout as one JSON document,
+    // so leading context turns a valid deny into "Hook JSON output validation
+    // failed"; the chain already stopped at the decision, so no later script's
+    // output can be concatenated in.
+
     // TASK-234 review fix (critical): context stdout must be REPLAYED, not
     // dropped. SessionStart/UserPromptSubmit hooks emit plain-text context
     // (PROJECT_IMPORTANT mandate, skill-router guidance) — replaying only the
@@ -449,15 +574,18 @@ try {
       .filter((r) => r !== decisionResult && r !== last && typeof r.stdout === 'string' && r.stdout.length > 0)
       .map((r) => r.stdout)
       .join('');
-
-    // TASK-234 review fix (critical): a mid-chain break that skipped a
-    // fail-closed gate must fail CLOSED — the old per-script path ran every
-    // hook independently, so a killed advisory never skipped a gate.
-    if (chain.skippedFailClosed) {
+    if (decisionOwnsVerdict) {
+      process.stdout.write(decisionResult.stdout);
+      if (decisionResult.stderr) process.stderr.write(decisionResult.stderr);
+      process.exitCode = 0;
+    } else if (chain.skippedFailClosed) {
+      // TASK-234 review fix (critical): a mid-chain break that skipped a
+      // fail-closed gate must fail CLOSED — the old per-script path ran every
+      // hook independently, so a killed advisory never skipped a gate.
       if (contextStdout) process.stdout.write(contextStdout);
       const skipped = scriptPaths
         .slice(chain.results.length)
-        .map((p) => path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, '')))
+        .map((p) => failClosedName(p))
         .filter((name) => FAIL_CLOSED_SCRIPTS.has(name))
         .join(', ');
       process.stderr.write(`UKit hook chain broke before fail-closed gate(s) ran: ${skipped}\n`);
@@ -466,7 +594,7 @@ try {
       // No script ran at all (empty chain or budget spent before the first
       // child). With fail-closed scripts declared in the chain this must not
       // fail open.
-      const hasFailClosed = scriptPaths.some((p) => FAIL_CLOSED_SCRIPTS.has(path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, ''))));
+      const hasFailClosed = scriptPaths.some((p) => FAIL_CLOSED_SCRIPTS.has(failClosedName(p)));
       if (hasFailClosed) {
         process.stderr.write('UKit hook chain produced no verdict — fail-closed gate did not run\n');
         process.exitCode = 2;
@@ -497,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);
 }