@ngockhoale/ukit 2.4.1 → 2.4.3

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

@@ -5,7 +5,15 @@ import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { withFileLock } from './token-utils.mjs';
+import { withAsyncLock, LOCK_MAX_SLICE_MS } from './async-lock.mjs';
+
+// Hook-context self-deadline (2.4.1 orphan-leak class): wrapper hooks pass
+// UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the
+// hook budget. CLI usage never sets it and is never self-killed.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
+if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
+  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+}
 
 const LEDGER_VERSION = 1;
 const RESUME_INTENT_VERSION = 1;
@@ -25,14 +33,22 @@ const MAX_GATE_CRASHES = 3;
 const VERIFICATION_LOOP_STREAK = 2;
 const VIBECODE_VERIFICATION_FAILURE_LIMIT = 4;
 const MAX_TRACKED_VERIFICATIONS = 8;
+// TASK-026 vibecode liveness circuit breaker (H18): vibecode bypasses MAX_CONTINUATIONS,
+// so an evidence-free Stop loop had NO absolute escape — the verification-loop blocker only
+// fires when a check actually fails. This ceiling bounds consecutive PROGRESS-FREE
+// continuations; past it, vibecode releases exactly like the ordinary cap (one final
+// notice, then a loud capped stop naming the missing evidence). It never fabricates
+// completion. Genuinely new verifiable progress (see progressDigest) resets the counter,
+// so a run that keeps producing real evidence stays autonomous indefinitely.
+const VIBECODE_NO_PROGRESS_CAP = 20;
 // hook-chain-runner.mjs gives every hook script a 4s child budget, and omp blocks Edit|Write
 // when a chain script is killed. Waiting longer than that for a contended lock got the
-// recording hook killed mid-chain (receipt lost, edit blocked). Give up and fail open well
-// inside the budget instead — under extreme contention a receipt may be lost, but the hook
-// is never killed by its own chain.
-const HOOK_SAFE_LOCK_WAIT_MS = 2500;
-function withLedgerLock(target, fn) {
-  return withFileLock(target, fn, { maxWaitMs: HOOK_SAFE_LOCK_WAIT_MS });
+// recording hook killed mid-chain (receipt lost, edit blocked). Locking is FAIL-CLOSED
+// (TASK-027): the acquisition budget is the short 1.2s slice from async-lock (callers may
+// derive a tighter deadline budget); when it expires the callback is NEVER run unlocked —
+// the event is journaled beside the ledger and reconciled by the next acquired lock.
+function withLedgerLock(target, { signal, deadlineMs } = {}, fn) {
+  return withAsyncLock(target, { signal, deadlineMs: deadlineMs ?? LOCK_MAX_SLICE_MS }, fn);
 }
 const IMPLEMENT_MODES = new Set([
   'tiny-fix',
@@ -122,14 +138,18 @@ async function readJson(filePath, fallback = null) {
 // a single `pid`-suffixed temp path: one rename removed the file under the other and the
 // writer crashed with ENOENT mid-hook. Make every write's temp path unique.
 let atomicWriteCounter = 0;
-async function writeJsonAtomic(filePath, value) {
+async function writeTextAtomic(filePath, text) {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   atomicWriteCounter += 1;
   const tempPath = `${filePath}.${process.pid}-${atomicWriteCounter}-${Math.random().toString(16).slice(2)}.tmp`;
-  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fs.writeFile(tempPath, text, 'utf8');
   await fs.rename(tempPath, filePath);
 }
 
+async function writeJsonAtomic(filePath, value) {
+  await writeTextAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
 export async function readRouteState(projectRoot, payload = {}) {
   const state = await readJson(path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json'), null);
   const sessionId = explicitSessionId(payload);
@@ -451,6 +471,71 @@ function appendReceipt(receipts, receipt) {
   return [...(receipts || []), compactReceipt(receipt)].slice(-MAX_RECEIPTS);
 }
 
+// TASK-026: the monotone verifiable-progress BANK. The digest used to be recomputed from
+// ledger.receipts, which appendReceipt caps at MAX_RECEIPTS by recency — so REPLAYED evidence
+// re-entered the set as older receipts evicted, moving the digest with zero new progress and
+// pinning noProgressCount at 0 forever (a stuck loop rewriting >MAX_RECEIPTS distinct targets
+// in rotation never reached VIBECODE_NO_PROGRESS_CAP). Evidence is now banked MONOTONICALLY:
+// the first successful write to a target, or the first successful run of a verification
+// command, mints a bank key that is NEVER evicted by later receipts — so a replay is a no-op
+// however much recency churn happens around it. Keys are hashed to keep the bank compact; it
+// lives for one request only (a genuinely new promptKey gets a fresh ledger). Reads are
+// deliberately excluded: an endless read-only loop must not reset an absolute liveness
+// escape. Route state is not consulted (the bank is derived from the ledger itself) so
+// journaled replays stay route-state-free.
+const EVIDENCE_BANK_KEY_LENGTH = 16;
+const BANK_FIELDS = { write: 'bankedWrites', verification: 'bankedVerifications' };
+
+function evidenceBankKey(target) {
+  return crypto.createHash('sha256').update(String(target)).digest('hex').slice(0, EVIDENCE_BANK_KEY_LENGTH);
+}
+
+function bankedEvidenceTarget(receipt) {
+  if (!receipt || receipt.success !== true) return null;
+  if (receipt.kind === 'write') return receipt.file ? String(receipt.file) : null;
+  if (receipt.kind === 'verification') {
+    return receipt.command ? (terminalShellCommandUnit(receipt.command) || String(receipt.command)) : null;
+  }
+  return null;
+}
+
+function seedBankFromReceipts(ledger = {}, field) {
+  const bank = {};
+  const receipts = Array.isArray(ledger?.receipts) ? ledger.receipts : [];
+  for (const receipt of receipts) {
+    const target = bankedEvidenceTarget(receipt);
+    if (!target || BANK_FIELDS[receipt.kind] !== field) continue;
+    bank[evidenceBankKey(target)] = true;
+  }
+  return bank;
+}
+
+// A ledger written before the bank existed is migrated from the receipt window it still
+// carries: an in-flight run must not re-count already-seen evidence as new progress.
+function evidenceBank(ledger = {}, field) {
+  const bank = ledger?.[field];
+  if (bank && typeof bank === 'object' && !Array.isArray(bank)) return bank;
+  return seedBankFromReceipts(ledger, field);
+}
+
+// Returns the next bank when `target` is genuinely NEW, or null when it is already banked
+// (a replay — never progress).
+function bankEvidence(ledger, field, target) {
+  const bank = evidenceBank(ledger, field);
+  const key = evidenceBankKey(target);
+  if (bank[key] === true) return null;
+  return { ...bank, [key]: true };
+}
+
+function progressDigest(ledger = {}) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify({
+      writes: Object.keys(evidenceBank(ledger, 'bankedWrites')).sort(),
+      verifications: Object.keys(evidenceBank(ledger, 'bankedVerifications')).sort(),
+    }))
+    .digest('hex');
+}
+
 // A re-key within the same logical request must not drop the evidence the request
 // already produced — that turned one finished task into a cap-exhausted forced stop.
 // A genuinely different prompt keeps a clean slate so old work never satisfies a new
@@ -479,6 +564,19 @@ function carriedEvidenceLedger(fresh, current) {
     // must keep counting toward the cap. Resetting it here made the cap unreachable and the
     // Stop gate loop forever on harnesses without a stop_hook_active valve.
     continuationCount: Math.max(Number(fresh.continuationCount || 0), Number(current.continuationCount || 0)),
+    // The vibecode liveness breaker (TASK-026) belongs to the same logical request: a
+    // same-prompt re-key must keep the no-progress streak, or a re-key mid-loop would
+    // grant a fresh escape budget. A genuinely different prompt returns `fresh` above,
+    // which starts the breaker at zero.
+    noProgressCount: Math.max(Number(fresh.noProgressCount || 0), Number(current.noProgressCount || 0)),
+    lastProgressDigest: current.lastProgressDigest || fresh.lastProgressDigest || null,
+    // The evidence bank is monotone and request-scoped, so a same-prompt re-key must keep
+    // it: dropping it would let every already-banked target count as NEW progress again.
+    bankedWrites: { ...evidenceBank(current, 'bankedWrites'), ...evidenceBank(fresh, 'bankedWrites') },
+    bankedVerifications: {
+      ...evidenceBank(current, 'bankedVerifications'),
+      ...evidenceBank(fresh, 'bankedVerifications'),
+    },
     continuationRequestKey: current.continuationRequestKey || fresh.continuationRequestKey || null,
     notified: fresh.notified === true || current.notified === true,
     // Verification-loop tracking and any minted blocker belong to the same logical request
@@ -486,6 +584,11 @@ function carriedEvidenceLedger(fresh, current) {
     failedVerificationStreak: current.failedVerificationStreak || null,
     verificationFailureCounts: current.verificationFailureCounts || {},
     blocker: current.blocker || null,
+    // Journal bookkeeping belongs to the file, not the request: the dedupe memory must
+    // survive a re-key or replayed journal events would be applied twice (TASK-027).
+    journalSeen: current.journalSeen || [],
+    journalQuarantined: current.journalQuarantined || 0,
+    lastJournalQuarantineAt: current.lastJournalQuarantineAt || null,
   };
 }
 
@@ -522,135 +625,530 @@ function freshLedger(payload, routeState, harness) {
     receipts: [],
     blocker: null,
     continuationCount: 0,
+    noProgressCount: 0,
+    lastProgressDigest: null,
+    // Monotone verifiable-progress bank (TASK-026 fix round 1): request-scoped, never
+    // evicted, so replaying banked evidence can never look like new progress.
+    bankedWrites: {},
+    bankedVerifications: {},
     notified: false,
     updatedAt: Date.now(),
   };
 }
 
-export async function recordExecutionReceipt({
-  projectRoot,
-  payload = {},
-  toolName = payload.tool_name,
-  harness = 'unknown',
-} = {}) {
-  if (!projectRoot || !toolName) return null;
-  // The whole read-modify-write is locked: parallel subagents record receipts through the
-  // same session ledger file, and an unlocked snapshot rewrite dropped whichever receipts
-  // landed between the read and the write.
-  return withLedgerLock(ledgerPath(projectRoot, payload), async () => {
-    const routeState = await readRouteState(projectRoot, payload);
-    const current = await readExecutionLedger(projectRoot, payload);
-    const nextRequestKey = routeState?.requestKey || null;
-    // A missing/foreign route state must never blank the evidence this session already
-    // banked. The shared state slot is single-owner (a parallel subagent re-stamps it), so
-    // routeState === null is routine mid-request — rebuilding from fresh there re-demanded
-    // every evidence the request had produced and froze the run. Without a live requestKey
-    // the only safe move is to keep appending to the current ledger.
-    const ledger = current && !nextRequestKey
-      ? { ...current, harness: current.harness || harness }
-      : (!current || current.requestKey !== nextRequestKey
-        ? carriedEvidenceLedger(freshLedger(payload, routeState, harness), current)
-        : { ...current, harness: current.harness || harness });
-
-    const failed = explicitError(payload);
-    const exitCode = extractExitCode(payload);
-    const success = !failed && (exitCode === null || exitCode === 0);
-    const toolInput = payload.tool_input || {};
-    const receipt = {
-      ts: Date.now(),
-      toolName,
-      toolUseId: payload.tool_use_id || null,
-      success,
-      exitCode,
-    };
+// --- TASK-027: fail-closed ledger events with a bounded lock-timeout journal -------------------
+// The ledger used to lock fail-open: when the wait expired, the read-modify-write ran
+// unlocked and parallel writers interleaved — evidence was lost exactly when the machine
+// was most contended. Every mutation now goes through recordLedgerEvent:
+//   * lock acquired  -> pending journal events are reconciled first (idempotent, by
+//     eventId), then the caller's event is applied, and ONE atomic ledger write lands.
+//     Reconciliation therefore happens inside the caller's own deadline, before its own
+//     evidence.
+//   * lock expired/aborted -> the main ledger is NEVER touched; the event is appended
+//     once to `<ledger>.journal` (JSONL, route-scoped) and reported as `journaled`.
+// Journal invariants: records are route-scoped (the sessionKey must match the journal
+// owner), idempotent (eventId deduped against ledger.journalSeen), bounded (record cap at
+// append time, bounded quarantine, bounded seen-list), and atomic per record (single
+// O_APPEND write; a torn trailing line is quarantined, never applied). Records carry
+// receipts and route metadata only — never prompt bodies or tool output; the receipt
+// whitelist below is the gate.
+const JOURNAL_VERSION = 1;
+const MAX_JOURNAL_SEEN = 64;
+const MAX_JOURNAL_RECORDS = 128;
+const MAX_JOURNAL_QUARANTINE_LINES = 32;
+const LEDGER_EVENT_TYPES = new Set(['receipt', 'continuation', 'notified', 'stop-progress']);
+const RECEIPT_KINDS = new Set(['source', 'write', 'verification']);
+
+function journalPathFor(target) {
+  return `${target}.journal`;
+}
 
-    if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
-      receipt.kind = 'source';
-      receipt.file = toolInput.file_path || toolInput.path || null;
-      ledger.sourceSucceeded ||= success;
-      if (success && receipt.file) {
-        ledger.sourceFiles = [...new Set([...(ledger.sourceFiles || []), receipt.file])].slice(-MAX_SOURCE_FILES);
-      }
-    } else if (toolName === 'Edit' || toolName === 'Write') {
-      receipt.kind = 'write';
-      receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
-      ledger.writeAttempted = true;
-      ledger.writeSucceeded ||= success;
-      // A mutation attempt between failures breaks the "no change in between" loop shape.
-      if (ledger.failedVerificationStreak) ledger.failedVerificationStreak = null;
-    } else if (toolName === 'Bash' && isVerificationCommand(toolInput.command)) {
-      receipt.kind = 'verification';
-      receipt.command = String(toolInput.command || '').trim();
-      // WS-C routed-verification receipt: a command counts as "targeted" when it matches the
-      // routed plan (preferredOrder / primaryCommands). Off-plan verification still records
-      // as broad — counted only when the route carried no commands at all.
-      const routedCommands = routedVerificationCommands(routeState?.routeSummary);
-      if (routedCommands.length > 0) {
-        const matched = routedCommands.find((cmd) => matchesRoutedCommand(receipt.command, cmd));
-        receipt.scope = matched ? 'targeted' : 'broad';
-        if (receipt.scope === 'targeted') {
-          ledger.targetedVerificationSucceeded ||= success;
-        }
-      }
-      ledger.verificationAttempted = true;
-      ledger.verificationSucceeded ||= success;
-      ledger.verificationFailed ||= !success;
-
-      // Verification-loop tracking. `terminalShellCommandUnit` gives the loop identity:
-      // the same failing check rerun — `setup && yarn test` and `yarn test 2>&1 | tail`
-      // both count as the same command, while a different check resets the streak.
-      const fingerprint = terminalShellCommandUnit(receipt.command) || receipt.command;
-      const counts = { ...(ledger.verificationFailureCounts || {}) };
-      if (success) {
-        delete counts[fingerprint];
-        ledger.verificationFailureCounts = counts;
-        if (ledger.failedVerificationStreak?.fingerprint === fingerprint) {
-          ledger.failedVerificationStreak = null;
+function journalQuarantinePathFor(target) {
+  return `${journalPathFor(target)}.quarantine`;
+}
+
+function newEventId() {
+  return `${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
+}
+
+const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope'];
+
+function sanitizeReceiptForJournal(receipt) {
+  const clean = {};
+  for (const key of JOURNAL_RECEIPT_FIELDS) {
+    if (receipt && receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
+      clean[key] = receipt[key];
+    }
+  }
+  return clean;
+}
+
+function buildJournalRecord({ event, eventId, payload, routeState }) {
+  return {
+    v: JOURNAL_VERSION,
+    eventId,
+    ts: Date.now(),
+    sessionKey: sessionIdentity(payload),
+    sessionId: explicitSessionId(payload),
+    requestKey: routeState?.requestKey ?? null,
+    promptKey: evidencePromptKey(routeState),
+    type: event.type,
+    event: event.type === 'receipt'
+      ? { receipt: sanitizeReceiptForJournal(event.receipt), vibecode: event.vibecode === true }
+      : { ...event, type: undefined },
+  };
+}
+
+async function appendJournalRecord(target, record, { signal, deadlineMs } = {}) {
+  const journalPath = journalPathFor(target);
+  try {
+    // Serialize the bounded-cap check with every producer. The main ledger lock is
+    // intentionally unavailable here (that is why this path is running), but a
+    // journal-local lock prevents concurrent read/check/append flows from exceeding
+    // the cap. A busy journal-local lock rejects the new event and leaves the existing
+    // unreconciled evidence untouched.
+    const outcome = await withAsyncLock(
+      journalPath,
+      { signal, deadlineMs: deadlineMs ?? LOCK_MAX_SLICE_MS },
+      async () => {
+        let existing = null;
+        try {
+          existing = await fs.readFile(journalPath, 'utf8');
+        } catch (error) {
+          if (error?.code !== 'ENOENT') return { ok: false, reason: 'journal-unavailable' };
         }
-      } else {
-        const streakFingerprint = ledger.failedVerificationStreak?.fingerprint;
-        const streakCount = streakFingerprint === fingerprint
-          ? Number(ledger.failedVerificationStreak.count || 0) + 1
-          : 1;
-        ledger.failedVerificationStreak = { fingerprint, count: streakCount };
-        counts[fingerprint] = Number(counts[fingerprint] || 0) + 1;
-        const trackedKeys = Object.keys(counts);
-        if (trackedKeys.length > MAX_TRACKED_VERIFICATIONS) {
-          for (const key of trackedKeys.slice(0, trackedKeys.length - MAX_TRACKED_VERIFICATIONS)) {
-            delete counts[key];
-          }
+        // Never rewrite or trim an unlocked journal: a concurrent drain may be relying on
+        // its prefix, and trimming would silently destroy unreconciled evidence. Once the
+        // bounded producer queue is full, apply backpressure and reject this event while
+        // preserving every record for the next lock holder to reconcile.
+        const lines = existing === null
+          ? []
+          : existing.split('\n').filter((line) => line.trim());
+        if (lines.length >= MAX_JOURNAL_RECORDS) return { ok: false, reason: 'journal-full' };
+        await fs.appendFile(journalPath, `${JSON.stringify(record)}\n`, 'utf8');
+        return { ok: true };
+      },
+    );
+    if (!outcome.ok) return { ok: false, reason: 'journal-unavailable' };
+    return outcome.value;
+  } catch {
+    return { ok: false, reason: 'journal-unavailable' };
+  }
+}
+
+function parseJournalRecord(line, expectedSessionKey) {
+  let record;
+  try {
+    record = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!record || typeof record !== 'object' || Array.isArray(record)) return null;
+  if (record.v !== JOURNAL_VERSION) return null;
+  if (typeof record.eventId !== 'string' || !record.eventId) return null;
+  if (record.sessionKey !== expectedSessionKey) return null; // route-scoped
+  if (!LEDGER_EVENT_TYPES.has(record.type)) return null;
+  if (!record.event || typeof record.event !== 'object') return null;
+  if (record.type === 'receipt') {
+    const receipt = record.event.receipt;
+    if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
+  }
+  return record;
+}
+
+async function quarantineJournalLines(target, lines) {
+  const quarantinePath = journalQuarantinePathFor(target);
+  try {
+    await fs.mkdir(path.dirname(quarantinePath), { recursive: true });
+    let existing = '';
+    try {
+      existing = await fs.readFile(quarantinePath, 'utf8');
+    } catch {
+      existing = '';
+    }
+    const stamped = lines.map((line) => `${new Date().toISOString()} ${line}`);
+    const kept = [...existing.split('\n').filter((line) => line.trim()), ...stamped]
+      .slice(-MAX_JOURNAL_QUARANTINE_LINES);
+    await writeTextAtomic(quarantinePath, `${kept.join('\n')}\n`);
+  } catch {
+    // Quarantine write failed: the malformed lines are still consumed from the journal
+    // and the ledger's quarantine report records the loss. Never crash the caller.
+  }
+}
+
+// Uniform applier: returns { ledger, value } or null when the record is unappliable
+// (the caller quarantines it instead of applying it).
+function applyJournalRecord(ledger, record) {
+  if (record.type === 'receipt') {
+    return applyReceiptToLedger(ledger, record.event?.receipt, { vibecode: record.event?.vibecode === true });
+  }
+  if (record.type === 'continuation') {
+    return { ledger: applyContinuationToLedger(ledger, record.event), value: null };
+  }
+  if (record.type === 'notified') {
+    return { ledger: { ...ledger, notified: true, updatedAt: Date.now() }, value: null };
+  }
+  if (record.type === 'stop-progress') {
+    return applyStopProgressToLedger(ledger);
+  }
+  return null;
+}
+
+// Read the journal and apply every unseen record onto `ledger` IN MEMORY. The journal is
+// consumed only after the caller's ledger write lands (commit()), so a crash anywhere
+// before that leaves the journal intact and the records re-apply idempotently by eventId.
+async function drainJournal(target, { ledger, payload, signal, deadlineMs }) {
+  const journalPath = journalPathFor(target);
+  let text = null;
+  try {
+    text = await fs.readFile(journalPath, 'utf8');
+  } catch {
+    return { ledger, applied: 0, quarantined: 0, commit: null };
+  }
+  if (!text) return { ledger, applied: 0, quarantined: 0, commit: null };
+
+  const expectedSessionKey = sessionIdentity(payload);
+  const seen = new Set(Array.isArray(ledger.journalSeen) ? ledger.journalSeen : []);
+  const malformed = [];
+  let next = ledger;
+  let applied = 0;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue; // structural newline
+    const record = parseJournalRecord(line, expectedSessionKey);
+    if (!record) {
+      malformed.push(line);
+      continue;
+    }
+    if (seen.has(record.eventId)) continue; // idempotent replay
+    const result = applyJournalRecord(next, record);
+    if (!result) {
+      malformed.push(line);
+      continue;
+    }
+    next = result.ledger;
+    seen.add(record.eventId);
+    applied += 1;
+  }
+  if (malformed.length > 0) {
+    await quarantineJournalLines(target, malformed);
+    next = {
+      ...next,
+      journalQuarantined: Number(next.journalQuarantined || 0) + malformed.length,
+      lastJournalQuarantineAt: Date.now(),
+    };
+  }
+  next = { ...next, journalSeen: [...seen].slice(-MAX_JOURNAL_SEEN) };
+
+  // Consume the drained records, preserving anything appended while we held the lock:
+  // journal writers append only, so a fresh read is our snapshot plus a suffix.
+  // The fresh-read + remainder-write/`rm` runs under the SAME journal-local lock that
+  // serializes producers in appendJournalRecord — an acknowledged `journaled` append
+  // can never land inside the read→replace window and be silently deleted. Lock order
+  // is safe (main→journal only): appenders take the journal lock precisely because the
+  // main lock was unavailable, so no appender ever holds journal while waiting on main.
+  const commit = async () => {
+    const outcome = await withAsyncLock(
+      journalPath,
+      { signal, deadlineMs: deadlineMs ?? LOCK_MAX_SLICE_MS },
+      async () => {
+        let fresh = null;
+        try {
+          fresh = await fs.readFile(journalPath, 'utf8');
+        } catch {
+          return;
         }
-        ledger.verificationFailureCounts = counts;
-
-        const vibecode = routeState?.routeSummary?.autonomyLevel === 'vibecode';
-        const shortCommand = fingerprint.length > 80 ? `${fingerprint.slice(0, 77)}…` : fingerprint;
-        if (streakCount >= VERIFICATION_LOOP_STREAK) {
-          ledger.blocker = {
-            kind: 'verification-loop',
-            visible: true,
-            detail: `verification "${shortCommand}" failed ${streakCount} times in a row with no edit in between — this is a loop, not progress. Report the failing output as a concrete blocker instead of rerunning it.`,
-            command: fingerprint,
-            ts: Date.now(),
-          };
-        } else if (vibecode && counts[fingerprint] >= VIBECODE_VERIFICATION_FAILURE_LIMIT) {
-          ledger.blocker = {
-            kind: 'verification-loop',
-            visible: true,
-            detail: `verification "${shortCommand}" failed ${counts[fingerprint]} times in continuous (vibecode) execution — report the failing output as a concrete blocker instead of retrying.`,
-            command: fingerprint,
-            ts: Date.now(),
-          };
+        if (!fresh.startsWith(text)) return; // rotated/rewritten under us: retry on the next drain
+        const remainder = fresh.slice(text.length);
+        try {
+          if (remainder.trim()) await writeTextAtomic(journalPath, remainder);
+          else await fs.rm(journalPath, { force: true });
+        } catch {
+          // Leftover consumed lines drain again as seen ids on the next lock — no duplication.
         }
+      },
+    );
+    if (!outcome.ok) {
+      // Journal-local lock stayed busy: leave the journal intact. The consumed lines
+      // re-drain as `seen` ids on the next acquired lock — no duplication, no loss.
+    }
+  };
+  return { ledger: next, applied, quarantined: malformed.length, commit };
+}
+
+function applyReceiptToLedger(ledger, receipt, { vibecode = false } = {}) {
+  if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
+  const next = { ...ledger };
+  if (receipt.kind === 'source') {
+    next.sourceSucceeded = next.sourceSucceeded || receipt.success;
+    if (receipt.success && receipt.file) {
+      next.sourceFiles = [...new Set([...(next.sourceFiles || []), receipt.file])].slice(-MAX_SOURCE_FILES);
+    }
+  } else if (receipt.kind === 'write') {
+    next.writeAttempted = true;
+    next.writeSucceeded = next.writeSucceeded || receipt.success;
+    // A mutation attempt between failures breaks the "no change in between" loop shape.
+    if (next.failedVerificationStreak) next.failedVerificationStreak = null;
+    // TASK-026 fix round 1: bank the FIRST successful write to this target. Later replays of
+    // a banked target are no-ops, so recency eviction of the receipt window can never make a
+    // rotation of already-seen targets look like new progress.
+    if (receipt.success && receipt.file) {
+      const banked = bankEvidence(next, 'bankedWrites', String(receipt.file));
+      if (banked) next.bankedWrites = banked;
+    }
+  } else if (receipt.kind === 'verification') {
+    // The targeted/broad scope is resolved at receipt time from the routed plan and
+    // travels with the receipt, so a journaled replay needs no route state.
+    if (receipt.scope === 'targeted') {
+      next.targetedVerificationSucceeded = next.targetedVerificationSucceeded || receipt.success;
+    }
+    next.verificationAttempted = true;
+    next.verificationSucceeded = next.verificationSucceeded || receipt.success;
+    next.verificationFailed = next.verificationFailed || !receipt.success;
+    // TASK-026 fix round 1: bank the FIRST successful run of this command (same
+    // terminal-shell identity the loop tracker uses), so rerunning a banked check is a
+    // replay — never progress — regardless of receipt-window eviction.
+    if (receipt.success && receipt.command) {
+      const banked = bankEvidence(
+        next,
+        'bankedVerifications',
+        terminalShellCommandUnit(receipt.command) || String(receipt.command),
+      );
+      if (banked) next.bankedVerifications = banked;
+    }
+
+    // Verification-loop tracking. `terminalShellCommandUnit` gives the loop identity:
+    // the same failing check rerun — `setup && yarn test` and `yarn test 2>&1 | tail`
+    // both count as the same command, while a different check resets the streak.
+    const fingerprint = terminalShellCommandUnit(receipt.command) || receipt.command;
+    const counts = { ...(next.verificationFailureCounts || {}) };
+    if (receipt.success) {
+      delete counts[fingerprint];
+      next.verificationFailureCounts = counts;
+      if (next.failedVerificationStreak?.fingerprint === fingerprint) {
+        next.failedVerificationStreak = null;
       }
     } else {
-      return ledger;
+      const streakFingerprint = next.failedVerificationStreak?.fingerprint;
+      const streakCount = streakFingerprint === fingerprint
+        ? Number(next.failedVerificationStreak.count || 0) + 1
+        : 1;
+      next.failedVerificationStreak = { fingerprint, count: streakCount };
+      counts[fingerprint] = Number(counts[fingerprint] || 0) + 1;
+      const trackedKeys = Object.keys(counts);
+      if (trackedKeys.length > MAX_TRACKED_VERIFICATIONS) {
+        for (const key of trackedKeys.slice(0, trackedKeys.length - MAX_TRACKED_VERIFICATIONS)) {
+          delete counts[key];
+        }
+      }
+      next.verificationFailureCounts = counts;
+
+      const shortCommand = fingerprint.length > 80 ? `${fingerprint.slice(0, 77)}…` : fingerprint;
+      if (streakCount >= VERIFICATION_LOOP_STREAK) {
+        next.blocker = {
+          kind: 'verification-loop',
+          visible: true,
+          detail: `verification "${shortCommand}" failed ${streakCount} times in a row with no edit in between — this is a loop, not progress. Report the failing output as a concrete blocker instead of rerunning it.`,
+          command: fingerprint,
+          ts: Date.now(),
+        };
+      } else if (vibecode && counts[fingerprint] >= VIBECODE_VERIFICATION_FAILURE_LIMIT) {
+        next.blocker = {
+          kind: 'verification-loop',
+          visible: true,
+          detail: `verification "${shortCommand}" failed ${counts[fingerprint]} times in continuous (vibecode) execution — report the failing output as a concrete blocker instead of retrying.`,
+          command: fingerprint,
+          ts: Date.now(),
+        };
+      }
     }
+  }
+  next.receipts = appendReceipt(next.receipts, receipt);
+  next.updatedAt = Date.now();
+  return { ledger: next, value: null };
+}
 
-    ledger.receipts = appendReceipt(ledger.receipts, receipt);
-    ledger.updatedAt = Date.now();
-    await writeJsonAtomic(ledgerPath(projectRoot, payload), ledger);
-    return ledger;
+function applyContinuationToLedger(ledger, event) {
+  // Mirror evaluateCompletion's staleness rule (see incrementContinuation): a count
+  // minted by an earlier request must not carry into the new request's budget, or the
+  // cap fires early. Same-prompt re-keys are the same request and keep counting.
+  const stale = event?.requestKey
+    && ledger?.continuationRequestKey
+    && ledger.continuationRequestKey !== event.requestKey
+    && !(event?.promptKey && ledger.promptKey && event.promptKey === ledger.promptKey);
+  // TASK-026 vibecode liveness breaker: compare the verifiable-progress digest against
+  // the one banked at the previous continuation. The digest is computed over the MONOTONE
+  // evidence bank (see progressDigest), so it moves only when genuinely NEW write/test
+  // evidence landed since — replaying already-banked evidence, however much receipt-window
+  // churn surrounds it, leaves the digest unchanged and the streak growing. A moved digest
+  // resets the streak for the current route. The very first continuation has no banked
+  // digest and never counts as no-progress.
+  const digest = progressDigest(ledger);
+  const progressed = ledger?.lastProgressDigest !== digest;
+  return {
+    ...ledger,
+    continuationCount: (stale ? 0 : Number(ledger?.continuationCount || 0)) + 1,
+    noProgressCount: progressed ? 0 : Number(ledger?.noProgressCount || 0) + 1,
+    lastProgressDigest: digest,
+    ...(event?.requestKey ? { continuationRequestKey: event.requestKey } : {}),
+    lastContinuationAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+}
+
+// The reentrant-stop fingerprint is computed at APPLICATION time from the ledger's own
+// receipts (not at mint time), so a journal replay after further receipts compares
+// against the then-current shape — a stale replay errs toward "not reentrant", i.e. one
+// extra recovery attempt, which is the safe direction.
+function applyStopProgressToLedger(ledger) {
+  const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
+  const fingerprint = `${receipts.length}:${receipts[receipts.length - 1]?.ts || 0}`;
+  const reentrant = typeof ledger.stopProgressFingerprint === 'string'
+    && ledger.stopProgressFingerprint === fingerprint;
+  return {
+    ledger: { ...ledger, stopProgressFingerprint: fingerprint, updatedAt: Date.now() },
+    value: { reentrant },
+  };
+}
+
+function liveBaseLedger(event, current, payload, routeState, harness, fallbackLedger) {
+  if (event.type === 'receipt') {
+    // A missing/foreign route state must never blank the evidence this session already
+    // banked. The shared state slot is single-owner (a parallel subagent re-stamps it),
+    // so routeState === null is routine mid-request — rebuilding from fresh there
+    // re-demanded every evidence the request had produced and froze the run. Without a
+    // live requestKey the only safe move is to keep appending to the current ledger.
+    const nextRequestKey = routeState?.requestKey || null;
+    if (current && !nextRequestKey) return { ...current, harness: current.harness || harness };
+    if (!current || current.requestKey !== nextRequestKey) {
+      return carriedEvidenceLedger(freshLedger(payload, routeState, harness), current);
+    }
+    return { ...current, harness: current.harness || harness };
+  }
+  return current || fallbackLedger || freshLedger(payload, null, 'unknown');
+}
+
+/**
+ * The one locked mutation protocol for the execution ledger (TASK-027). Never mutates
+ * the ledger without lock ownership; journals the event when the lock cannot be taken.
+ * @param {{ type: string, receipt?: object, vibecode?: boolean, requestKey?: string|null, promptKey?: string|null }} event
+ * @param {{ projectRoot: string, payload?: object, harness?: string, signal?: AbortSignal,
+ *   deadlineMs?: number, routeState?: object|null, fallbackLedger?: object|null }} options
+ * @returns {Promise<{ committed?: boolean, journaled?: boolean, rejected?: boolean,
+ *   eventId: string|null, value?: *, drained?: number, quarantined?: number, reason?: string }>}
+ */
+export async function recordLedgerEvent(event, {
+  projectRoot,
+  payload = {},
+  harness = 'unknown',
+  signal,
+  deadlineMs,
+  routeState = null,
+  fallbackLedger = null,
+} = {}) {
+  if (!projectRoot || !event || !LEDGER_EVENT_TYPES.has(event.type)) {
+    return { rejected: true, eventId: null, reason: 'invalid-event' };
+  }
+  const eventId = newEventId();
+  const target = ledgerPath(projectRoot, payload);
+  const outcome = await withLedgerLock(target, { signal, deadlineMs }, async () => {
+    const state = routeState || await readRouteState(projectRoot, payload);
+    const current = await readExecutionLedger(projectRoot, payload);
+    let ledger = liveBaseLedger(event, current, payload, state, harness, fallbackLedger);
+    // Reconcile pending journaled events first — inside this caller's acquired lock and
+    // before its own evidence, so a timed-out writer's receipt is never stranded.
+    const drained = await drainJournal(target, { ledger, payload, signal, deadlineMs });
+    ledger = drained.ledger;
+    let value;
+    if (event.type === 'receipt') {
+      const applied = applyReceiptToLedger(ledger, event.receipt, { vibecode: event.vibecode === true });
+      if (!applied) return { committed: false, eventId, reason: 'invalid-receipt' };
+      ledger = applied.ledger;
+    } else if (event.type === 'continuation') {
+      ledger = applyContinuationToLedger(ledger, event);
+    } else if (event.type === 'notified') {
+      ledger = { ...ledger, notified: true, updatedAt: Date.now() };
+    } else if (event.type === 'stop-progress') {
+      if (!current && drained.applied === 0) {
+        // A stop with no ledger at all creates nothing (historic noteStopProgress shape).
+        return { committed: true, eventId, value: { reentrant: false }, drained: 0, quarantined: 0 };
+      }
+      const applied = applyStopProgressToLedger(ledger);
+      ledger = applied.ledger;
+      value = applied.value;
+    }
+    await writeJsonAtomic(target, ledger);
+    // 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();
+    return { committed: true, eventId, value, drained: drained.applied, quarantined: drained.quarantined };
   });
+  if (outcome.ok) return outcome.value;
+
+  // Fail-closed: the acquisition budget expired or the wait aborted. The main ledger is
+  // 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 };
+}
+
+// TASK-027: the receipt is classified (kind, file, command, targeted/broad scope) from the
+// advisory route state BEFORE locking — that read is read-only — and then applied through
+// recordLedgerEvent, which owns the fail-closed lock/journal protocol.
+export async function recordExecutionReceipt({
+  projectRoot,
+  payload = {},
+  toolName = payload.tool_name,
+  harness = 'unknown',
+  signal,
+  deadlineMs,
+} = {}) {
+  if (!projectRoot || !toolName) return { rejected: true, eventId: null };
+  const routeState = await readRouteState(projectRoot, payload);
+  const failed = explicitError(payload);
+  const exitCode = extractExitCode(payload);
+  const success = !failed && (exitCode === null || exitCode === 0);
+  const toolInput = payload.tool_input || {};
+  const receipt = {
+    ts: Date.now(),
+    toolName,
+    toolUseId: payload.tool_use_id || null,
+    success,
+    exitCode,
+  };
+
+  if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
+    receipt.kind = 'source';
+    receipt.file = toolInput.file_path || toolInput.path || null;
+  } else if (toolName === 'Edit' || toolName === 'Write') {
+    receipt.kind = 'write';
+    receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
+  } else if (toolName === 'Bash' && isVerificationCommand(toolInput.command)) {
+    receipt.kind = 'verification';
+    receipt.command = String(toolInput.command || '').trim();
+    // WS-C routed-verification receipt: a command counts as "targeted" when it matches the
+    // routed plan (preferredOrder / primaryCommands). Off-plan verification still records
+    // as broad — counted only when the route carried no commands at all. The resolved
+    // scope travels with the receipt so a journaled replay needs no route state.
+    const routedCommands = routedVerificationCommands(routeState?.routeSummary);
+    if (routedCommands.length > 0) {
+      const matched = routedCommands.find((cmd) => matchesRoutedCommand(receipt.command, cmd));
+      receipt.scope = matched ? 'targeted' : 'broad';
+    }
+  } else {
+    // Untracked tool: no event, no lock, no write — same as the old unlocked early return.
+    return { rejected: true, eventId: null };
+  }
+
+  return recordLedgerEvent(
+    {
+      type: 'receipt',
+      receipt,
+      vibecode: routeState?.routeSummary?.autonomyLevel === 'vibecode',
+    },
+    { projectRoot, payload, harness, signal, deadlineMs, routeState },
+  );
 }
 
 function requiredEvidence(state = {}) {
@@ -872,11 +1370,40 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
     };
   }
 
+  // TASK-026 vibecode liveness circuit breaker: vibecode bypasses the continuation cap
+  // ONLY while verifiable progress occurs. A no-progress streak at the ceiling releases
+  // with the exact two-phase shape of the ordinary cap — one final notice, then a loud
+  // capped stop — so the escape is absolute for evidence-free loops. It never fabricates
+  // completion: every release still names the missing evidence.
+  const noProgressCount = Number(effectiveLedger?.noProgressCount || 0);
+  if (vibecode && noProgressCount >= VIBECODE_NO_PROGRESS_CAP) {
+    if (effectiveLedger?.notified === true) {
+      return {
+        continue: false,
+        capped: true,
+        notify: true,
+        noProgressCount,
+        missingEvidence,
+        reason: `UKit vibecode liveness breaker: ${noProgressCount} continuations produced no new verifiable progress (missing evidence: ${missingEvidence.join(', ')}). Stop and tell the user what is unfinished; do not keep continuing without new evidence.`,
+      };
+    }
+    return {
+      continue: true,
+      finalNotice: true,
+      notify: true,
+      capped: true,
+      noProgressCount,
+      missingEvidence,
+      reason: `UKit stopping with unfinished work: ${noProgressCount} continuations produced no new verifiable progress (${missingEvidence.join(', ')}). Tell the user what is unfinished and stop; do not continue further.`,
+    };
+  }
+
   const finalAttempt = !vibecode && continuationCount === MAX_CONTINUATIONS - 1;
   const instruction = recoveryInstruction(missingEvidence, effectiveLedger, routeSummary);
   return {
     continue: true,
     missingEvidence,
+    noProgressCount,
     reason: [
       `UKit completion gate: missing ${missingEvidence.join(', ')}.`,
       instruction,
@@ -886,60 +1413,35 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   };
 }
 
-export async function incrementContinuation(projectRoot, payload = {}, ledger = null, requestKey = null, promptKey = null) {
-  const target = ledgerPath(projectRoot, payload);
-  // Locked re-read: parallel subagents firing Stop hooks share one ledger file, and a
-  // stale-snapshot rewrite would reset each other's continuationCount — the budget would
-  // never advance and the gate would keep issuing continuations.
-  return withLedgerLock(target, async () => {
-    const current = await readExecutionLedger(projectRoot, payload) || ledger || freshLedger(payload, null, 'unknown');
-    // Mirror evaluateCompletion's staleness rule: a count minted by an earlier request must
-    // not be carried into the new request's budget, or the cap fires early (evaluate says 0,
-    // persist says 7) and the next request inherits a nearly exhausted budget. Same-prompt
-    // re-keys are the same request, so their budget must keep counting toward the cap.
-    const stale = requestKey
-      && current?.continuationRequestKey
-      && current.continuationRequestKey !== requestKey
-      && !(promptKey && current.promptKey && promptKey === current.promptKey);
-    const next = {
-      ...current,
-      continuationCount: (stale ? 0 : Number(current.continuationCount || 0)) + 1,
-      ...(requestKey ? { continuationRequestKey: requestKey } : {}),
-      lastContinuationAt: Date.now(),
-      updatedAt: Date.now(),
-    };
-    await writeJsonAtomic(target, next);
-    return next;
-  });
+export async function incrementContinuation(projectRoot, payload = {}, ledger = null, requestKey = null, promptKey = null, { signal, deadlineMs } = {}) {
+  // Locked (and fail-closed) via recordLedgerEvent: parallel subagents firing Stop hooks
+  // share one ledger file, and a stale-snapshot rewrite would reset each other's
+  // continuationCount. An expired lock wait journals the increment instead of running
+  // the read-modify-write unlocked.
+  return recordLedgerEvent(
+    { type: 'continuation', requestKey, promptKey },
+    { projectRoot, payload, fallbackLedger: ledger, signal, deadlineMs },
+  );
 }
 
-export async function markNotified(projectRoot, payload = {}, ledger = null) {
-  const target = ledgerPath(projectRoot, payload);
-  return withLedgerLock(target, async () => {
-    const current = await readExecutionLedger(projectRoot, payload) || ledger || freshLedger(payload, null, 'unknown');
-    const next = { ...current, notified: true, updatedAt: Date.now() };
-    await writeJsonAtomic(target, next);
-    return next;
-  });
+export async function markNotified(projectRoot, payload = {}, ledger = null, { signal, deadlineMs } = {}) {
+  return recordLedgerEvent(
+    { type: 'notified' },
+    { projectRoot, payload, fallbackLedger: ledger, signal, deadlineMs },
+  );
 }
 
 // omp's session_stop carries no stop_hook_active marker, so reentrancy must be detected from
 // the ledger itself: a stop whose recovery turn produced no new receipts is the reentrant
 // shape Claude Code flags natively. The fingerprint deliberately excludes continuation
 // bookkeeping fields (count/notified/updatedAt) so this call's own writes stay invisible to
-// the next comparison — only real receipts change it.
-export async function noteStopProgress(projectRoot, payload = {}) {
-  const target = ledgerPath(projectRoot, payload);
-  return withLedgerLock(target, async () => {
-    const current = await readExecutionLedger(projectRoot, payload);
-    if (!current) return { reentrant: false };
-    const receipts = Array.isArray(current.receipts) ? current.receipts : [];
-    const fingerprint = `${receipts.length}:${receipts[receipts.length - 1]?.ts || 0}`;
-    const reentrant = typeof current.stopProgressFingerprint === 'string'
-      && current.stopProgressFingerprint === fingerprint;
-    await writeJsonAtomic(target, { ...current, stopProgressFingerprint: fingerprint, updatedAt: Date.now() });
-    return { reentrant };
-  });
+// the next comparison — only real receipts change it. The fingerprint is computed under the
+// lock at application time (see applyStopProgressToLedger).
+export async function noteStopProgress(projectRoot, payload = {}, { signal, deadlineMs } = {}) {
+  return recordLedgerEvent(
+    { type: 'stop-progress' },
+    { projectRoot, payload, signal, deadlineMs },
+  );
 }
 
 async function readStdin() {