@ngockhoale/ukit 3.4.20 → 3.4.21

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.21 - 2026-10-07
+
+**Hook runtime no longer burns CPU/disk on every tool call** (five measured bugs, C95).
+- Retention sweeps (tee cache, hook-latency telemetry, execution ledger, hook payloads, omp hook errors) only
+  looked at the first 128 directory entries, so old files past that window were never pruned and the
+  over-cap rule deleted newer files instead. The scan window now rotates.
+- Chained `.sh` hooks no longer each spawn their own `node hook-telemetry.mjs --finish`; `hook-chain-runner.mjs`
+  writes the per-step rows (an Edit chain went from 11 node spawns to 5, same telemetry rows).
+- `unic-decision` now honours its persisted circuit breaker (closed/open/half-open, fail-open): a rejected key
+  or dead endpoint no longer costs a failed call on every prompt.
+- The context hard-cap gate probes the transcript incrementally instead of re-reading the last 4 MB and
+  rewriting `compact-pressure.json` on ~95% of calls; invalid persisted probe state falls back to a full scan.
+
 ## 3.4.20 - 2026-10-06
 
 **`ukit update` now displays the NEW version.** The running process is the old code, so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.20",
+  "version": "3.4.21",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/output/index.js

@@ -386,6 +386,7 @@ export async function sweepTeeCache(dir, {
   maxFiles = TEE_MAX_FILES,
   maxEntries = TEE_SWEEP_MAX_ENTRIES,
   maxRemovals = TEE_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let dirents;
   try {
@@ -404,8 +405,17 @@ export async function sweepTeeCache(dir, {
   const cutoff = now() - maxAgeMs;
   const entries = [];
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  // Circular window at a random start so expired files beyond the first
+  // maxEntries readdir names are still reached (BUG-1: the head slice never
+  // age-pruned the tail). Non-finite random() falls back to start 0.
+  const L = eligibleNames.length;
+  const r = random();
+  const start = L > maxEntries
+    ? Math.min(L - 1, Math.max(0, Math.floor((Number.isFinite(r) ? r : 0) * L)))
+    : 0;
+  const windowSize = Math.min(maxEntries, L);
+  for (let i = 0; i < windowSize; i += 1) {
+    const name = eligibleNames[(start + i) % L];
     scanned += 1;
     try {
       const stats = await fs.stat(path.join(dir, name));
@@ -439,7 +449,7 @@ export async function maybeSweepTeeCache(dir, {
     ? Math.min(1, Math.max(0, probability))
     : teeSweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return sweepTeeCache(dir, options);
+  return sweepTeeCache(dir, { ...options, random });
 }
 
 async function persistRawOutput(projectRoot, {

package/template_project/.claude/ukit/index/route-task.mjs

@@ -1771,7 +1771,18 @@ export async function runRouteDecisionShadow({
 
   let result = null;
   const startedAt = now();
+  // FR-004: skip the CLI spawn while the persisted decision circuit is open
+  // (half-open does not skip — the CLI claims the probe). Any failure = closed.
+  let circuitOpen = false;
   try {
+    const { isDecisionCircuitOpen } = await import('./unic-decision.mjs');
+    circuitOpen = isDecisionCircuitOpen(rootDir, { config, now }) === true;
+  } catch {
+    circuitOpen = false;
+  }
+  if (circuitOpen) {
+    result = { status: 'unavailable', fallbackCode: 'circuit-open' };
+  } else try {
     const spawned = spawnImpl(
       process.execPath,
       [cliPath, '--root', rootDir],

package/template_project/.claude/ukit/index/unic-decision.mjs

@@ -716,6 +716,99 @@ function outcome(status, extra = {}) {
   return { status, finishReason: null, answers: [], ...extra };
 }
 
+// --- Persisted circuit breaker (SPEC FR-004 / BUG-4) -----------------------
+// The hook path spawns a fresh process per prompt, so an in-memory breaker is
+// useless. State lives in <projectRoot>/.ukit/storage/cache/decision-circuit.json.
+// Advisory + best-effort: every read/parse/write error degrades to "closed".
+const CIRCUIT_DEFAULTS = { failureThreshold: 3, cooldownMs: 30000 };
+
+function circuitFile(projectRoot) {
+  return path.join(projectRoot, '.ukit', 'storage', 'cache', 'decision-circuit.json');
+}
+
+function circuitConfig(config) {
+  const raw = decisionPlaneConfig(config).circuitBreaker;
+  const pick = (value, fallback) =>
+    Number.isFinite(value) && value >= 1 ? value : fallback;
+  return {
+    failureThreshold: pick(raw?.failureThreshold, CIRCUIT_DEFAULTS.failureThreshold),
+    cooldownMs: pick(raw?.cooldownMs, CIRCUIT_DEFAULTS.cooldownMs),
+  };
+}
+
+function writeCircuitState(projectRoot, next, now) {
+  const file = circuitFile(projectRoot);
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(
+      tmp,
+      JSON.stringify({
+        schemaVersion: 1,
+        consecutiveFailures: next.consecutiveFailures,
+        openedAt: next.openedAt,
+        lastFallbackCode: next.lastFallbackCode,
+        updatedAt: now,
+      }),
+      'utf8',
+    );
+    fs.renameSync(tmp, file);
+  } catch {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort */ }
+  }
+}
+
+export function readDecisionCircuit(projectRoot, { config = null, now = () => Date.now() } = {}) {
+  const closed = { state: 'closed', consecutiveFailures: 0, openedAt: null, lastFallbackCode: null };
+  if (typeof projectRoot !== 'string' || projectRoot === '') return closed;
+  try {
+    const raw = JSON.parse(fs.readFileSync(circuitFile(projectRoot), 'utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return closed;
+    const consecutiveFailures =
+      Number.isInteger(raw.consecutiveFailures) && raw.consecutiveFailures >= 0
+        ? raw.consecutiveFailures
+        : 0;
+    const lastFallbackCode =
+      typeof raw.lastFallbackCode === 'string' ? raw.lastFallbackCode : null;
+    const base = { consecutiveFailures, openedAt: null, lastFallbackCode };
+    if (!Number.isFinite(raw.openedAt)) return { state: 'closed', ...base };
+    // Negative delta = clock moved backwards / future stamp: never pin open.
+    const delta = now() - raw.openedAt;
+    if (!(delta >= 0)) return { state: 'closed', ...base };
+    const state = delta < circuitConfig(config).cooldownMs ? 'open' : 'half-open';
+    return { state, ...base, openedAt: raw.openedAt };
+  } catch {
+    return closed;
+  }
+}
+
+export function isDecisionCircuitOpen(projectRoot, opts = {}) {
+  return readDecisionCircuit(projectRoot, opts).state === 'open';
+}
+
+function recordCircuitOutcome(projectRoot, prior, kind, { config, now, fallbackCode = null }) {
+  if (typeof projectRoot !== 'string' || projectRoot === '') return;
+  try {
+    const at = now();
+    if (kind === 'success') {
+      if (prior.consecutiveFailures === 0 && prior.openedAt === null) return;
+      writeCircuitState(projectRoot, {
+        consecutiveFailures: 0, openedAt: null, lastFallbackCode: null,
+      }, at);
+      return;
+    }
+    const consecutiveFailures = prior.consecutiveFailures + 1;
+    const reopen =
+      prior.state === 'half-open' ||
+      consecutiveFailures >= circuitConfig(config).failureThreshold;
+    writeCircuitState(projectRoot, {
+      consecutiveFailures,
+      openedAt: reopen ? at : null,
+      lastFallbackCode: fallbackCode,
+    }, at);
+  } catch { /* advisory */ }
+}
+
 /**
  * Send one C13 batch over the configured gateway. `batch` =
  * {batchId?, boundary?, statePacket, questions, deadlineMs?}. Returns a typed
@@ -798,6 +891,24 @@ export async function requestBatch(batch, {
       detail: error?.message ?? String(error),
     });
   }
+  // Persisted breaker (FR-004): consulted only after all local validation, so
+  // those outcomes keep their order and never touch the state file.
+  const breakerOn = typeof projectRoot === 'string' && projectRoot !== '';
+  const circuit = breakerOn
+    ? readDecisionCircuit(projectRoot, { config, now })
+    : null;
+  if (circuit?.state === 'open') {
+    return outcome('unavailable', {
+      batchId: batch?.batchId ?? null,
+      checkpoint,
+      fallbackCode: 'circuit-open',
+      circuitCause: circuit.lastFallbackCode,
+    });
+  }
+  if (circuit?.state === 'half-open') {
+    // Claim the probe: concurrent processes now see 'open' until the cooldown.
+    writeCircuitState(projectRoot, { ...circuit, openedAt: now() }, now());
+  }
   let fingerprint = requestFingerprint(body);
   const timeoutMs = Number.isFinite(dp.timeoutMs) ? dp.timeoutMs : DEFAULT_TIMEOUT_MS;
   const deadlineMs = Number.isFinite(batch?.deadlineMs) ? batch.deadlineMs : timeoutMs;
@@ -889,6 +1000,7 @@ export async function requestBatch(batch, {
     }
 
     const result = parseBatchResponse(parsed, questions);
+    if (breakerOn) recordCircuitOutcome(projectRoot, circuit, 'success', { config, now });
     return {
       batchId: batch?.batchId ?? null,
       checkpoint,
@@ -900,11 +1012,18 @@ export async function requestBatch(batch, {
     };
   }
 
-  return outcome(lastError ?? 'unavailable', {
+  const finalStatus = lastError ?? 'unavailable';
+  const finalCode =
+    lastStatus ?? (lastError === 'timeout' ? 'deadline-exceeded' : 'transport-error');
+  if (breakerOn && (finalStatus === 'timeout' || finalStatus === 'unavailable')) {
+    recordCircuitOutcome(projectRoot, circuit, 'failure', {
+      config, now, fallbackCode: finalCode,
+    });
+  }
+  return outcome(finalStatus, {
     batchId: batch?.batchId ?? null,
     checkpoint,
-    fallbackCode:
-      lastStatus ?? (lastError === 'timeout' ? 'deadline-exceeded' : 'transport-error'),
+    fallbackCode: finalCode,
     requestFingerprint: fingerprint,
   });
 }

package/template_project/.claude/ukit/runtime/compact-threshold.mjs

@@ -557,12 +557,83 @@ const BOUNDARY_TAIL_BYTES = 4 * 1024 * 1024;
 // 4s hook budget on a slow volume.
 const TRANSCRIPT_BOUNDARY_PROBE_TTL_MS = 2_000;
 
+// Persist a probe update only after this many unpersisted bytes were scanned: transcripts grow
+// on every tool call, but rewriting compact-pressure.json (70-110KB) each time is the cost
+// the incremental probe exists to avoid.
+const PROBE_PERSIST_DELTA_BYTES = 256 * 1024;
+
 function normalizeTranscriptProbe(value) {
   if (!value || typeof value !== 'object' || typeof value.path !== 'string' || !value.path) return null;
   const checkedAt = finiteNumber(value.checkedAt, 0);
-  return checkedAt > 0
-    ? { path: value.path, checkedAt, boundaryAt: finiteNumber(value.boundaryAt, 0) }
-    : null;
+  if (!(checkedAt > 0)) return null;
+  // Only a non-negative safe integer is a usable byte offset; anything else (fractional, NaN,
+  // negative, string) is treated as 'no scannedSize' so the next probe does one full scan.
+  const scannedSize = Number.isSafeInteger(value.scannedSize) && value.scannedSize >= 0 ? value.scannedSize : null;
+  return { path: value.path, checkedAt, boundaryAt: finiteNumber(value.boundaryAt, 0), scannedSize };
+}
+
+function boundaryAtOfLine(line) {
+  if (!line.includes('compact_boundary')) return 0;
+  try {
+    const entry = JSON.parse(line);
+    if (entry?.type === 'system' && entry?.subtype === 'compact_boundary') {
+      const at = Date.parse(entry.timestamp ?? '');
+      if (Number.isFinite(at)) return at;
+    }
+  } catch { /* not a usable boundary line */ }
+  return 0;
+}
+
+// Scan `[max(fromOffset, size - tailBytes), size)` of the transcript for the newest
+// compact_boundary (epoch ms, 0 if none). A leading partial line is dropped only when the
+// read starts mid-line. `scannedSize` is the offset just past the last `\n` read, so a
+// trailing line still being written is rescanned once it is complete and a delta scan always
+// starts at a line boundary. A fromOffset beyond EOF (truncation/rotation) scans the tail.
+// Throws on stat/open/read failure; callers decide the fallback.
+export async function scanCompactBoundary(transcriptPath, { tailBytes = BOUNDARY_TAIL_BYTES, fromOffset = 0 } = {}) {
+  const stat = await fs.stat(transcriptPath);
+  const size = stat.size;
+  if (!stat.isFile() || size === 0) {
+    return { boundaryAt: 0, scannedSize: 0, size };
+  }
+  const requested = Number.isSafeInteger(fromOffset) && fromOffset >= 0 && fromOffset <= size ? fromOffset : 0;
+  const start = Math.max(requested, size - tailBytes);
+  // One extra leading byte tells whether `start` sits on a line boundary.
+  const readStart = start > 0 ? start - 1 : 0;
+  const length = size - readStart;
+  const buffer = Buffer.allocUnsafe(length);
+  const handle = await fs.open(transcriptPath, 'r');
+  let bytesRead;
+  try {
+    ({ bytesRead } = await handle.read(buffer, 0, length, readStart));
+  } finally {
+    await handle.close();
+  }
+  const data = buffer.subarray(0, bytesRead);
+  // A delta scan must start on a line boundary (scannedSize sits just past a `\n`). If the
+  // byte before it is not `\n`, the file was replaced at the same path: rescan from the top.
+  if (requested > 0 && start === requested && data.length > 0 && data[0] !== 0x0a) {
+    return scanCompactBoundary(transcriptPath, { tailBytes, fromOffset: 0 });
+  }
+  let begin = 0;
+  let leadingPartialOnly = false;
+  if (start > 0 && data.length > 0 && data[0] !== 0x0a) {
+    const nl = data.indexOf(0x0a, 1);
+    if (nl === -1) { begin = data.length; leadingPartialOnly = true; } else { begin = nl + 1; }
+  } else if (start > 0) {
+    begin = 1;
+  }
+  const region = data.subarray(begin);
+  const lastNl = region.lastIndexOf(0x0a);
+  const scannedSize = lastNl >= 0
+    ? readStart + begin + lastNl + 1
+    : (leadingPartialOnly ? start : readStart + begin);
+  const lines = region.toString('utf8').split('\n');
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const at = boundaryAtOfLine(lines[i]);
+    if (at) return { boundaryAt: at, scannedSize, size };
+  }
+  return { boundaryAt: 0, scannedSize, size };
 }
 
 // Find the newest compaction recorded in the session transcript, as epoch ms (0 if none).
@@ -576,35 +647,7 @@ export async function detectLatestCompactBoundaryAt(transcriptPath, { tailBytes
     return 0;
   }
   try {
-    const stat = await fs.stat(transcriptPath);
-    if (!stat.isFile() || stat.size === 0) {
-      return 0;
-    }
-    const start = Math.max(0, stat.size - tailBytes);
-    const length = stat.size - start;
-    const buffer = Buffer.allocUnsafe(length);
-    const handle = await fs.open(transcriptPath, 'r');
-    let text;
-    try {
-      const { bytesRead } = await handle.read(buffer, 0, length, start);
-      text = buffer.toString('utf8', 0, bytesRead);
-    } finally {
-      await handle.close();
-    }
-    const lines = text.split('\n');
-    if (start > 0) lines.shift(); // a tail read can split the first line
-    for (let i = lines.length - 1; i >= 0; i -= 1) {
-      const line = lines[i];
-      if (!line.includes('compact_boundary')) continue;
-      try {
-        const entry = JSON.parse(line);
-        if (entry?.type === 'system' && entry?.subtype === 'compact_boundary') {
-          const at = Date.parse(entry.timestamp ?? '');
-          if (Number.isFinite(at)) return at;
-        }
-      } catch { /* not a usable boundary line */ }
-    }
-    return 0;
+    return (await scanCompactBoundary(transcriptPath, { tailBytes, fromOffset: 0 })).boundaryAt;
   } catch {
     return 0;
   }
@@ -616,28 +659,89 @@ export async function detectLatestCompactBoundaryAt(transcriptPath, { tailBytes
 // history that was already summarised away and the hard-cap gate bricks a healthy
 // session. Callers must persist when reset=true, or the reset would re-fire (and
 // zero the counter) on every call.
+//
+// The probe is incremental: it remembers how many bytes were already scanned
+// (`scannedSize`), so an unchanged transcript costs one stat and a grown one only reads the
+// delta. `probed: true` tells the caller to persist; it is raised only on a meaningful change
+// (new path, new boundary, full rescan, or >= persistDeltaBytes unpersisted bytes scanned).
 export async function syncCompactPressureStateWithTranscript(
   rawState = null,
   config = {},
   transcriptPath = '',
-  { now = Date.now(), probeTtlMs = TRANSCRIPT_BOUNDARY_PROBE_TTL_MS } = {},
+  { now = Date.now(), probeTtlMs = TRANSCRIPT_BOUNDARY_PROBE_TTL_MS, persistDeltaBytes = PROBE_PERSIST_DELTA_BYTES } = {},
 ) {
   const normalizedPath = typeof transcriptPath === 'string' ? transcriptPath.trim() : '';
   const previousProbe = normalizeTranscriptProbe(rawState?.transcriptBoundaryProbe);
-  // A process-persistent, session-scoped cache avoids rereading/parsing up to 4MB for every
+  const samePath = Boolean(previousProbe) && previousProbe.path === normalizedPath;
+  // A process-persistent, session-scoped cache avoids rereading/parsing the transcript for every
   // mutation during a tool burst. It keys on the path (not just time) so a resumed/new
   // transcript always scans immediately. The short TTL is deliberately only a performance
   // coalescing window; PreCompact remains the immediate source of truth.
-  const probeFresh = previousProbe
-    && previousProbe.path === normalizedPath
+  const probeFresh = samePath
     && now - previousProbe.checkedAt >= 0
     && now - previousProbe.checkedAt < probeTtlMs;
-  const boundaryAt = probeFresh
-    ? previousProbe.boundaryAt
-    : await detectLatestCompactBoundaryAt(normalizedPath);
-  const probe = probeFresh
-    ? previousProbe
-    : { path: normalizedPath, checkedAt: now, boundaryAt };
+
+  let boundaryAt;
+  let probe;
+  let probed;
+  if (probeFresh) {
+    boundaryAt = previousProbe.boundaryAt;
+    probe = previousProbe;
+    probed = false;
+  } else {
+    // `persistedScannedSize` is the scannedSize loaded from disk via rawState: the gate only
+    // persists when probed is true, so this bounds the delta a later process must re-read.
+    const persistedScannedSize = samePath ? previousProbe.scannedSize : null;
+    const fullScan = async () => {
+      const scan = await scanCompactBoundary(normalizedPath, { fromOffset: 0 });
+      return {
+        boundaryAt: scan.boundaryAt,
+        probe: { path: normalizedPath, checkedAt: now, boundaryAt: scan.boundaryAt, scannedSize: scan.scannedSize },
+        probed: true,
+      };
+    };
+    const incrementalScan = async () => {
+      const { size } = await fs.stat(normalizedPath);
+      if (size === persistedScannedSize) {
+        // Nothing new since the persisted probe: reuse, no read.
+        const reused = previousProbe.boundaryAt;
+        return {
+          boundaryAt: reused,
+          probe: { path: normalizedPath, checkedAt: now, boundaryAt: reused, scannedSize: persistedScannedSize },
+          probed: false,
+        };
+      }
+      if (size < persistedScannedSize) return fullScan(); // truncation/rotation
+      const scan = await scanCompactBoundary(normalizedPath, { fromOffset: persistedScannedSize });
+      const merged = scan.boundaryAt || previousProbe.boundaryAt;
+      return {
+        boundaryAt: merged,
+        probe: { path: normalizedPath, checkedAt: now, boundaryAt: merged, scannedSize: scan.scannedSize },
+        probed: merged !== previousProbe.boundaryAt
+          || scan.scannedSize - persistedScannedSize >= persistDeltaBytes,
+      };
+    };
+    let result = null;
+    if (persistedScannedSize !== null) {
+      // Any incremental failure retries one full scan, so the gate decides exactly as a full
+      // re-read would; only if that fails too do we fall back to the previous boundary.
+      try { result = await incrementalScan(); } catch { result = null; }
+    }
+    if (!result) {
+      try {
+        result = await fullScan();
+      } catch {
+        // stat/open/read failure: keep the previous boundary for the same path, else 0.
+        const kept = samePath ? previousProbe.boundaryAt : 0;
+        result = {
+          boundaryAt: kept,
+          probe: { path: normalizedPath, checkedAt: now, boundaryAt: kept, scannedSize: persistedScannedSize },
+          probed: !samePath,
+        };
+      }
+    }
+    ({ boundaryAt, probe, probed } = result);
+  }
   const accounted = finiteNumber(rawState?.lastCompactBoundaryAt, 0);
   if (!boundaryAt || boundaryAt <= accounted) {
     return {
@@ -645,7 +749,7 @@ export async function syncCompactPressureStateWithTranscript(
         ? { ...rawState, transcriptBoundaryProbe: probe }
         : rawState,
       reset: false,
-      probed: !probeFresh,
+      probed,
     };
   }
   return {
@@ -655,7 +759,7 @@ export async function syncCompactPressureStateWithTranscript(
       transcriptBoundaryProbe: probe,
     },
     reset: true,
-    probed: !probeFresh,
+    probed,
   };
 }
 

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

@@ -160,6 +160,7 @@ export async function sweepExecLedgerDir(dir, {
   maxFiles = LEDGER_MAX_FILES,
   maxEntries = LEDGER_SWEEP_MAX_ENTRIES,
   maxRemovals = LEDGER_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let dirents;
   try {
@@ -178,9 +179,15 @@ export async function sweepExecLedgerDir(dir, {
     if (dirent.isFile()) eligibleNames.push(dirent.name);
   }
   const entries = [];
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
     try {
       const stats = await fs.stat(path.join(dir, name));
@@ -258,7 +265,7 @@ export async function maybeSweepExecLedgerDir(dir, {
     ? Math.min(1, Math.max(0, probability))
     : ledgerSweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return { sampled: true, ...(await sweepExecLedgerDir(dir, options)) };
+  return { sampled: true, ...(await sweepExecLedgerDir(dir, { ...options, random })) };
 }
 
 function resumeIntentPath(projectRoot, sessionId) {

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

@@ -296,6 +296,13 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
       // (ask + exit 2). Under --emit-verdict the runner replays the direct
       // Claude contract (deny + exit 0), so children must NOT see it.
       ...(chainMarker ? { UKIT_HOOK_CHAIN_RUNNER: '1' } : {}),
+      // BUG-3 (TASK-003): the runner owns hook-latency rows for every chained
+      // step (see recordHookTiming below). This marker keeps hook-telemetry.sh
+      // unarmed in `.sh` children so they spawn no `--finish` node/sleep.
+      // Distinct from UKIT_HOOK_CHAIN_RUNNER, which is withheld under
+      // --emit-verdict; this one is set in both modes. Direct invocations
+      // (no runner) never see it and stay armed.
+      UKIT_HOOK_TELEMETRY_BY_RUNNER: '1',
     };
     const stepDeadlineMs = Math.min(childBudgetsMs[scriptIndex], remainingMs);
     // TASK-001: `.mjs` args run in-proc via runHook(ctx); `.sh` stays a child
@@ -350,21 +357,21 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
       elapsedMs: Date.now() - childStartedAt,
     });
 
-    // TASK-001 (FR-003): `.sh` children write their own hook-latency row via
-    // hook-telemetry.sh --finish; in-proc `.mjs` steps cannot — the runner
-    // emits the equivalent row per module step (hook = basename incl. `.mjs`).
-    if (scriptPath.endsWith('.mjs')) {
-      recordHookTiming({
-        projectRoot,
-        sessionId: payload?.session_id,
-        event: payload?.hook_event_name || null,
-        tool: payload?.tool_name || null,
-        toolUseId: payload?.tool_use_id || null,
-        hook: scriptName,
-        elapsedMs: Date.now() - childStartedAt,
-        outcome: failureKind,
-      });
-    }
+    // TASK-001 (FR-003) / TASK-003 (BUG-3): the runner is the single telemetry
+    // owner for every chained step. `.mjs` steps run in-proc and cannot write
+    // their own row; `.sh` children are told via UKIT_HOOK_TELEMETRY_BY_RUNNER
+    // not to spawn hook-telemetry.mjs --finish. One row per step, hook =
+    // basename incl. extension; elapsedMs includes bash start-up.
+    recordHookTiming({
+      projectRoot,
+      sessionId: payload?.session_id,
+      event: payload?.hook_event_name || null,
+      tool: payload?.tool_name || null,
+      toolUseId: payload?.tool_use_id || null,
+      hook: scriptName,
+      elapsedMs: Date.now() - childStartedAt,
+      outcome: failureKind,
+    });
 
     // B1 (TASK-001, SPEC §FR-001): under `--emit-verdict` a child that emits a
     // `hookSpecificOutput` permission decision owns the verdict even at exit 0

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

@@ -195,6 +195,7 @@ export async function sweepStalePayloadsAsync(dir, {
   now = Date.now,
   maxAgeMs = SWEEP_MAX_AGE_MS,
   maxEntries = SWEEP_MAX_ENTRIES,
+  random = Math.random,
 } = {}) {
   let names;
   try {
@@ -203,12 +204,18 @@ export async function sweepStalePayloadsAsync(dir, {
     return { sampled: true, scanned: 0, removed: 0 };
   }
   const cutoff = now() - maxAgeMs;
+  const eligibleNames = names.filter((name) => name.endsWith('.json') || name.endsWith('.tmp'));
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
   let removed = 0;
-  for (const name of names) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
-    if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
     const filePath = path.join(dir, name);
     try {
       if ((await fsp.stat(filePath)).mtimeMs < cutoff) {
@@ -234,7 +241,7 @@ export async function maybeSweepStalePayloadsAsync(dir, {
 } = {}) {
   const p = Number.isFinite(probability) ? Math.min(1, Math.max(0, probability)) : sweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return sweepStalePayloadsAsync(dir, { now, maxAgeMs, maxEntries });
+  return sweepStalePayloadsAsync(dir, { now, maxAgeMs, maxEntries, random });
 }
 
 // sweepStalePayloads(dir, {now, maxAgeMs, maxEntries}) -> {sampled, scanned, removed}
@@ -247,6 +254,7 @@ export function sweepStalePayloads(dir, {
   now = Date.now,
   maxAgeMs = SWEEP_MAX_AGE_MS,
   maxEntries = SWEEP_MAX_ENTRIES,
+  random = Math.random,
 } = {}) {
   let names;
   try {
@@ -255,12 +263,18 @@ export function sweepStalePayloads(dir, {
     return { sampled: true, scanned: 0, removed: 0 };
   }
   const cutoff = now() - maxAgeMs;
+  const eligibleNames = names.filter((name) => name.endsWith('.json') || name.endsWith('.tmp'));
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
   let removed = 0;
-  for (const name of names) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
-    if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
     const filePath = path.join(dir, name);
     try {
       if (fs.statSync(filePath).mtimeMs < cutoff) {
@@ -287,5 +301,5 @@ export function maybeSweepStalePayloads(dir, {
 } = {}) {
   const p = Number.isFinite(probability) ? Math.min(1, Math.max(0, probability)) : sweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return sweepStalePayloads(dir, { now, maxAgeMs, maxEntries });
+  return sweepStalePayloads(dir, { now, maxAgeMs, maxEntries, random });
 }

package/template_project/.claude/ukit/runtime/hook-telemetry.mjs

@@ -231,6 +231,7 @@ export function sweepTelemetryDir(dir, {
   maxFiles = TELEMETRY_MAX_FILES,
   maxEntries = TELEMETRY_SWEEP_MAX_ENTRIES,
   maxRemovals = TELEMETRY_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let names;
   try {
@@ -245,9 +246,15 @@ export function sweepTelemetryDir(dir, {
   // `entries.length` an under-count and `overflow` was always 0.
   const eligibleNames = names.filter((name) => name.endsWith('.jsonl'));
   const entries = [];
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
     try {
       const stats = fs.statSync(path.join(dir, name));
@@ -283,7 +290,7 @@ export function maybeSweepTelemetryDir(dir, {
     ? Math.min(1, Math.max(0, probability))
     : telemetrySweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return { sampled: true, ...sweepTelemetryDir(dir, options) };
+  return { sampled: true, ...sweepTelemetryDir(dir, { ...options, random }) };
 }
 
 // BUG-C23-10: a bare `catch {}` around the sweep swallowed every failure — a

package/template_project/.claude/ukit/runtime/hook-telemetry.sh

@@ -17,10 +17,21 @@
 # without adding a node spawn to the hot path — and trap
 # ukit_hook_telemetry_finish on EXIT themselves.
 #
+# BUG-3 (TASK-003): inside hook-chain-runner.mjs the runner is the single
+# telemetry owner — it times every step and writes the hook-latency row itself.
+# It exports UKIT_HOOK_TELEMETRY_BY_RUNNER=1 to each child; when that marker is
+# 1 this file stays unarmed (UKIT_TEL_ARMED=0) and arm/finish return at once —
+# no mktemp, no node, no sleep watchdog. Direct invocations (Codex direct hooks,
+# debug runs) carry no marker and behave exactly as before.
+#
 # Missing runtime (pre-install tree) simply leaves telemetry off: wrappers
 # source this file with `|| true` and the armed flag stays unset.
 
-UKIT_TEL_ARMED=1
+if [ "${UKIT_HOOK_TELEMETRY_BY_RUNNER:-}" = "1" ]; then
+  UKIT_TEL_ARMED=0
+else
+  UKIT_TEL_ARMED=1
+fi
 UKIT_TEL_HOOK="$(basename "${BASH_SOURCE[1]:-$0}")"
 UKIT_TEL_RUNTIME_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 UKIT_TEL_START_FILE=""
@@ -52,6 +63,7 @@ ukit_tel_file_ms() {
 # one mktemp; a `node -e` clock read would cost ~30ms to measure milliseconds.
 # Always returns 0 — an unarmed hook must behave exactly like an unmeasured one.
 ukit_hook_telemetry_arm() {
+  [ "${UKIT_TEL_ARMED:-}" = "1" ] || return 0
   UKIT_TEL_START_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-tel-start.XXXXXX" 2>/dev/null)" || {
     UKIT_TEL_START_FILE=""
     return 0
@@ -65,6 +77,7 @@ ukit_hook_telemetry_finish() {
   # captured it before its own conditionals could reset $?); $? is only the
   # fallback for direct debug invocation.
   local rc="${UKIT_TEL_RC:-$?}"
+  [ "${UKIT_TEL_ARMED:-}" = "1" ] || return 0
   command -v node >/dev/null 2>&1 || return 0
   # UKIT_INPUT_FILE is a plain shell variable (never exported), so the staged
   # payload path — and through it the envelope start mtime — is passed here

package/template_project/.claude/ukit/runtime/output-compression.mjs

@@ -455,6 +455,7 @@ export async function sweepTeeCache(dir, {
   maxFiles = TEE_MAX_FILES,
   maxEntries = TEE_SWEEP_MAX_ENTRIES,
   maxRemovals = TEE_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let dirents;
   try {
@@ -478,8 +479,17 @@ export async function sweepTeeCache(dir, {
   const cutoff = now() - maxAgeMs;
   const entries = [];
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  // Circular window at a random start so expired files beyond the first
+  // maxEntries readdir names are still reached (BUG-1: the head slice never
+  // age-pruned the tail). Non-finite random() falls back to start 0.
+  const L = eligibleNames.length;
+  const r = random();
+  const start = L > maxEntries
+    ? Math.min(L - 1, Math.max(0, Math.floor((Number.isFinite(r) ? r : 0) * L)))
+    : 0;
+  const windowSize = Math.min(maxEntries, L);
+  for (let i = 0; i < windowSize; i += 1) {
+    const name = eligibleNames[(start + i) % L];
     scanned += 1;
     try {
       const stats = await fs.stat(path.join(dir, name));
@@ -516,7 +526,7 @@ export async function maybeSweepTeeCache(dir, {
     ? Math.min(1, Math.max(0, probability))
     : teeSweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return sweepTeeCache(dir, options);
+  return sweepTeeCache(dir, { ...options, random });
 }
 
 async function persistRawOutput(projectRoot, {

package/template_project/.omp/hooks/pre/ukit-bridge.js

@@ -454,6 +454,7 @@ async function sweepHookErrorsDir(dir, {
   maxFiles = HOOK_ERROR_MAX_FILES,
   maxEntries = HOOK_ERROR_SWEEP_MAX_ENTRIES,
   maxRemovals = HOOK_ERROR_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let names;
   try {
@@ -468,9 +469,15 @@ async function sweepHookErrorsDir(dir, {
   // `entries.length` an under-count and `overflow` was always 0.
   const eligibleNames = names.filter((name) => name.endsWith('.jsonl'));
   const entries = [];
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
     try {
       const stats = await fs.promises.stat(path.join(dir, name));