@ngockhoale/ukit 2.6.3 → 2.6.5

package/templates/.claude/ukit/index/post-edit-verify.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { analyzeTextBuffer, analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
@@ -7,9 +8,27 @@ import { classifySafePatchRisk, isSafePatchAdvisoryOnly, parseJsonInput, pathExi
 // Hook-context self-deadline (2.4.1 orphan-leak class): the post-edit-verify hook passes
 // UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
 // budget. Non-hook usage never sets it and is never self-killed.
+// SPEC §8: stdout is the only surface the hook consumer reliably shows the
+// user (stderr reaches the model). writeSync(1) because a same-tick
+// process.exit() can discard a buffered async write on a pipe.
+function emitSystemMessage(text) {
+  try {
+    fsSync.writeSync(1, `${JSON.stringify({ systemMessage: text })}\n`);
+  } catch { /* stdout already gone */ }
+}
+
 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();
+  setTimeout(() => {
+    // BUG-C23-04: deadline expiry abandons the configured post-edit verify — a
+    // degrade, and §8(ii) requires it be announced before the exit.
+    emitSystemMessage(
+      `UKit post-edit-verify exceeded its ${HOOK_DEADLINE_MS}ms hook deadline — `
+      + 'Safe Patch delta verification skipped this pass (likely stalled filesystem). '
+      + 'If this repeats, check the .ukit volume or raise UKIT_HOOK_DEADLINE_MS.',
+    );
+    process.exit(0);
+  }, HOOK_DEADLINE_MS).unref();
 }
 
 async function readStdin() {
@@ -220,6 +239,13 @@ async function main() {
       process.stderr.write('[ukit-safe-patch] advisoryOnly=true — change is already written; continue planned follow-up without stopping.\n');
       return;
     }
+    // BUG-C23-03: exit-2 blocks must pair the stderr reason with a stdout §8
+    // emission — stderr reaches the model, not reliably the user
+    // (precedent: context-hardcap-gate.sh, handoff-model-guard.sh).
+    // --json mode: the verdict JSON already written above IS the structured
+    // announcement (status+message fields); a second raw line would corrupt
+    // the machine-parseable stdout contract.
+    if (!json) emitSystemMessage(`[ukit-safe-patch] ${message}`);
     process.exit(2);
   }
 }
@@ -227,6 +253,12 @@ async function main() {
 if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
   main().catch((error) => {
     process.stderr.write(`[ukit-safe-patch] post-edit ERROR: ${error?.message || error}\n`);
+    // BUG-C23-01: stderr-only crash announces nothing to the user — §8 requires
+    // the paired stdout systemMessage before the non-zero exit.
+    emitSystemMessage(
+      `UKit post-edit-verify crashed before it could verify the edit (${error?.message || error}); `
+      + 'the Safe Patch check was skipped this pass. Run `ukit doctor` if this repeats.',
+    );
     process.exit(1);
   });
 }

package/templates/.claude/ukit/index/stale-spec-check.mjs

@@ -1,5 +1,6 @@
 import { analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
 import { fileURLToPath } from 'node:url';
+import fsSync from 'node:fs';
 import path from 'node:path';
 import {
   classifySafePatchRisk,
@@ -16,9 +17,27 @@ import {
 // Hook-context self-deadline (2.4.1 orphan-leak class): the stale-spec-guard hook passes
 // UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
 // budget. Non-hook usage never sets it and is never self-killed.
+// SPEC §8: stdout is the only surface the hook consumer reliably shows the
+// user (stderr reaches the model). writeSync(1) because a same-tick
+// process.exit() can discard a buffered async write on a pipe.
+function emitSystemMessage(text) {
+  try {
+    fsSync.writeSync(1, `${JSON.stringify({ systemMessage: text })}\n`);
+  } catch { /* stdout already gone */ }
+}
+
 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();
+  setTimeout(() => {
+    // BUG-C23-04: deadline expiry abandons the configured stale-spec check — a
+    // degrade, and §8(ii) requires it be announced before the exit.
+    emitSystemMessage(
+      `UKit stale-spec-check exceeded its ${HOOK_DEADLINE_MS}ms hook deadline — `
+      + 'Safe Patch spec verification skipped this pass (likely stalled filesystem). '
+      + 'If this repeats, check the .ukit volume or raise UKIT_HOOK_DEADLINE_MS.',
+    );
+    process.exit(0);
+  }, HOOK_DEADLINE_MS).unref();
 }
 
 function getToolName(payload = {}) {
@@ -198,6 +217,13 @@ async function main() {
       process.stderr.write('[ukit-safe-patch] advisoryOnly=true — continue with corrected old_string; do not stop and ask the user.\n');
       return;
     }
+    // BUG-C23-03: exit-2 blocks must pair the stderr reason with a stdout §8
+    // emission — stderr reaches the model, not reliably the user
+    // (precedent: context-hardcap-gate.sh, handoff-model-guard.sh).
+    // --json mode: the verdict JSON above IS the structured announcement —
+    // a second raw line would corrupt the parseable stdout contract
+    // (sibling parity: post-edit-verify.mjs).
+    if (!args.json) emitSystemMessage(`[ukit-safe-patch] ${message}`);
     process.exit(2);
   }
 }
@@ -205,6 +231,11 @@ async function main() {
 if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
   main().catch((error) => {
     process.stderr.write(`[ukit-safe-patch] ERROR: ${error?.message || error}\n`);
+    // Same stderr-only crash class as BUG-C23-01 — pair the §8 stdout emission.
+    emitSystemMessage(
+      `UKit stale-spec-check crashed before it could verify the edit (${error?.message || error}); `
+      + 'the Safe Patch spec check was skipped this pass. Run `ukit doctor` if this repeats.',
+    );
     process.exit(1);
   });
 }

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

@@ -456,13 +456,17 @@ export const CAPACITY_RECORD_SEGMENTS = ['.ukit', 'storage', 'cache', 'context-c
 // smaller verified window moves the advisory phases down with the cap they precede.
 export const SOFT_TO_CAP_RATIO = 0.3;
 
-export function readContextCapacityRecord(projectRoot) {
+// BUG-C22-01: async on purpose — every consumer of this module runs inside an
+// unref'd hook deadline (context-hardcap-gate.sh, skill-router's prompt CLI). A
+// synchronous readFileSync on a stalled .ukit mount parks the event loop so the
+// armed deadline can never fire (C21-04 class). Callers must await.
+export async function readContextCapacityRecord(projectRoot) {
   const root = projectRoot
     || process.env.CLAUDE_PROJECT_DIR
     || process.env.PROJECT_ROOT
     || process.cwd();
   try {
-    const parsed = JSON.parse(fsSync.readFileSync(path.join(root, ...CAPACITY_RECORD_SEGMENTS), 'utf8'));
+    const parsed = JSON.parse(await fs.readFile(path.join(root, ...CAPACITY_RECORD_SEGMENTS), 'utf8'));
     return parsed && typeof parsed === 'object' ? parsed : null;
   } catch {
     return null;
@@ -471,22 +475,25 @@ export function readContextCapacityRecord(projectRoot) {
 
 // Negotiated capacity: env override > config override > the model the guard last observed >
 // conservative fallback. Exported so the source twin and diagnostics read the same number.
-export function resolveCompactCapacity(config = {}) {
-  const record = readContextCapacityRecord(config?.projectRoot);
+export async function resolveCompactCapacity(config = {}, { record } = {}) {
+  // BUG-C23-09: callers that already read the capacity record (buildCompactThresholds)
+  // pass it in — a second serial fs.readFile on .ukit doubles the stalled-mount
+  // window on the hardcap hot path.
+  const resolvedRecord = record !== undefined ? record : await readContextCapacityRecord(config?.projectRoot);
   return resolveContextCapTokens({
     env: process.env,
     config,
-    modelMetadata: { model: record?.model },
+    modelMetadata: { model: resolvedRecord?.model },
   });
 }
 
-export function buildCompactThresholds(config = {}) {
+export async function buildCompactThresholds(config = {}) {
   const explicitSoftThreshold = finiteNumber(config?.compact?.tokenThreshold, 0);
   const shippedHardCap = positiveInteger(config?.compact?.hardCapTokens, 500_000);
   // Only tighten once a record exists: an install with no evidence yet (and every caller
   // that passes no project root) keeps the shipped tuning unchanged.
-  const record = readContextCapacityRecord(config?.projectRoot);
-  const negotiated = record ? resolveCompactCapacity(config) : null;
+  const record = await readContextCapacityRecord(config?.projectRoot);
+  const negotiated = record ? await resolveCompactCapacity(config, { record }) : null;
   const hardCapTokens = negotiated
     ? Math.max(1, Math.min(shippedHardCap, negotiated.capTokens))
     : shippedHardCap;
@@ -511,16 +518,16 @@ export function buildCompactThresholds(config = {}) {
 
 // Absolute, non-negotiable ceiling — separate from the soft/hard advisory phases above.
 // Crossing this means the advisory nudges were not followed; real compaction is mandatory.
-export function isHardCapExceeded(estimatedTotalTokens, config = {}) {
-  const { hardCapTokens } = buildCompactThresholds(config);
+export async function isHardCapExceeded(estimatedTotalTokens, config = {}) {
+  const { hardCapTokens } = await buildCompactThresholds(config);
   return finiteNumber(estimatedTotalTokens, 0) >= hardCapTokens;
 }
 
 // Called from the PreCompact hook path once real compaction has happened, so the
 // hard-cap gate unblocks on the next tool call instead of staying tripped forever.
-export function resetCompactPressureState(rawState = {}, config = {}) {
-  const current = buildCompactPressureState(rawState, config);
-  return buildCompactPressureState({
+export async function resetCompactPressureState(rawState = {}, config = {}) {
+  const current = await buildCompactPressureState(rawState, config);
+  return await buildCompactPressureState({
     ...current,
     updatedAt: Date.now(),
     sessionTokens: 0,
@@ -638,7 +645,7 @@ export async function syncCompactPressureStateWithTranscript(
   }
   return {
     state: {
-      ...resetCompactPressureState(rawState ?? {}, config),
+      ...(await resetCompactPressureState(rawState ?? {}, config)),
       lastCompactBoundaryAt: boundaryAt,
       transcriptBoundaryProbe: probe,
     },
@@ -647,7 +654,7 @@ export async function syncCompactPressureStateWithTranscript(
   };
 }
 
-function buildReleaseThresholds(thresholds = buildCompactThresholds()) {
+function buildReleaseThresholds(thresholds) {
   const softReleaseThreshold = Math.max(
     Math.min(thresholds.softThreshold, Math.round(thresholds.softThreshold * SOFT_RELEASE_RATIO)),
     1,
@@ -663,11 +670,12 @@ function buildReleaseThresholds(thresholds = buildCompactThresholds()) {
   };
 }
 
-export function resolveCompactPhase(
+export async function resolveCompactPhase(
   estimatedTotalTokens,
-  thresholds = buildCompactThresholds(),
+  thresholds = null,
   previousState = {},
 ) {
+  thresholds = thresholds ?? await buildCompactThresholds();
   const previousPhase = normalizePhase(previousState?.phase ?? previousState);
   const releaseThresholds = buildReleaseThresholds(thresholds);
   if (estimatedTotalTokens >= thresholds.hardThreshold) {
@@ -689,7 +697,7 @@ function resolvePhaseCooldownMs(phase) {
   return PHASE_COOLDOWN_MS[normalizePhase(phase)] ?? 0;
 }
 
-function resolvePlanDeltaThreshold(phase, thresholds = buildCompactThresholds()) {
+function resolvePlanDeltaThreshold(phase, thresholds) {
   return normalizePhase(phase) === 'hard'
     ? Math.max(60, Math.round(thresholds.hardThreshold * 0.14))
     : Math.max(40, Math.round(thresholds.softThreshold * 0.12));
@@ -821,9 +829,9 @@ function projectPressureDocument(sessions) {
   };
 }
 
-export function buildCompactPressureState(rawState = null, config = {}) {
+export async function buildCompactPressureState(rawState = null, config = {}) {
   rawState = resolvePressureRecord(rawState, config);
-  const thresholds = buildCompactThresholds(config);
+  const thresholds = await buildCompactThresholds(config);
   const rawSoftThreshold = finiteNumber(rawState?.softThreshold, 0);
   const rawHardThreshold = finiteNumber(rawState?.hardThreshold, 0);
   if (!finiteNumber(config?.compact?.tokenThreshold, 0) && rawSoftThreshold > 0) {
@@ -872,7 +880,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
     estimatedContextTokens,
     sessionTokens,
     estimatedTotalTokens,
-    phase: resolveCompactPhase(estimatedTotalTokens, thresholds, rawState),
+    phase: await resolveCompactPhase(estimatedTotalTokens, thresholds, rawState),
     taskMode,
     cooldownUntil: finiteNumber(rawState?.cooldownUntil, 0),
     lastCompactBoundaryAt: finiteNumber(rawState?.lastCompactBoundaryAt, 0),
@@ -888,14 +896,14 @@ export function buildCompactPressureState(rawState = null, config = {}) {
   };
 }
 
-export function registerPromptPressure(state, {
+export async function registerPromptPressure(state, {
   promptText = '',
   routingContext = {},
   previousContext = null,
   routeSummary = null,
   timestamp = Date.now(),
 } = {}, config = {}) {
-  const current = buildCompactPressureState(state, config);
+  const current = await buildCompactPressureState(state, config);
   const normalizedPrompt = String(promptText || routingContext?.lastExplicitUserPromptText || '').trim();
   if (!normalizedPrompt) {
     return current;
@@ -916,7 +924,7 @@ export function registerPromptPressure(state, {
       })
     : current.recentPrompts;
 
-  return buildCompactPressureState({
+  return await buildCompactPressureState({
     ...current,
     updatedAt: timestamp,
     routingContext,
@@ -936,7 +944,7 @@ export function registerPromptPressure(state, {
   }, config);
 }
 
-export function registerOutputPressure(state, {
+export async function registerOutputPressure(state, {
   command = '',
   profile = 'generic',
   summary = '',
@@ -946,7 +954,7 @@ export function registerOutputPressure(state, {
   exitCode = null,
   timestamp = Date.now(),
 } = {}, config = {}) {
-  const current = buildCompactPressureState(state, config);
+  const current = await buildCompactPressureState(state, config);
   const normalizedSummary = summarizeOutputText(summary, command);
   if (!normalizedSummary) {
     return current;
@@ -968,7 +976,7 @@ export function registerOutputPressure(state, {
     keyBuilder: (candidate) => `${candidate.command ?? ''}|${candidate.summary ?? ''}`,
   });
 
-  return buildCompactPressureState({
+  return await buildCompactPressureState({
     ...current,
     updatedAt: timestamp,
     recentOutputs,
@@ -982,8 +990,8 @@ export function registerOutputPressure(state, {
   }, config);
 }
 
-export function registerThresholdCompactPlan(state, plan, config = {}) {
-  const current = buildCompactPressureState(state, config);
+export async function registerThresholdCompactPlan(state, plan, config = {}) {
+  const current = await buildCompactPressureState(state, config);
   if (!plan?.active) {
     return current;
   }
@@ -999,7 +1007,7 @@ export function registerThresholdCompactPlan(state, plan, config = {}) {
     lines: plan.lines,
   });
   if (current.latestPlan?.fingerprint === fingerprint) {
-    return buildCompactPressureState({
+    return await buildCompactPressureState({
       ...current,
       updatedAt: now,
       latestPlan: {
@@ -1017,7 +1025,7 @@ export function registerThresholdCompactPlan(state, plan, config = {}) {
   const materialChange = isMaterialThresholdPlanChange(current.latestPlan, plan, thresholds);
 
   if (withinCooldown && !materialChange) {
-    return buildCompactPressureState({
+    return await buildCompactPressureState({
       ...current,
       updatedAt: now,
       latestPlan: {
@@ -1052,7 +1060,7 @@ export function registerThresholdCompactPlan(state, plan, config = {}) {
     ? Math.min(current.sessionTokens, decayTarget)
     : current.sessionTokens;
 
-  return buildCompactPressureState({
+  return await buildCompactPressureState({
     ...current,
     updatedAt: now,
     sessionTokens: decayedSessionTokens,
@@ -1073,7 +1081,7 @@ export function registerThresholdCompactPlan(state, plan, config = {}) {
   }, config);
 }
 
-export function buildThresholdCompactPlan({
+export async function buildThresholdCompactPlan({
   state,
   config = {},
   routeState = {},
@@ -1081,8 +1089,8 @@ export function buildThresholdCompactPlan({
   dynamicLines = [],
   maxTokens = 280,
 } = {}) {
-  const normalizedState = buildCompactPressureState(state, config);
-  const thresholds = buildCompactThresholds(config);
+  const normalizedState = await buildCompactPressureState(state, config);
+  const thresholds = await buildCompactThresholds(config);
   const phase = normalizedState.phase;
   if (phase === 'monitor') {
     return {
@@ -1205,7 +1213,7 @@ export function buildThresholdCompactPlan({
 
 export async function readCompactPressureState(projectRoot, config = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  return buildCompactPressureState(await readJson(runtimePaths.compactPressurePath, null), config);
+  return await buildCompactPressureState(await readJson(runtimePaths.compactPressurePath, null), config);
 }
 
 // All compact-pressure mutations share one lock on the state file: without it,
@@ -1225,9 +1233,9 @@ async function mutateCompactPressureState(projectRoot, mutator, config = {}) {
   return withFileLock(runtimePaths.compactPressurePath, async () => {
     const sessions = readPressureDocument(await readJson(runtimePaths.compactPressurePath, null));
     const { id, record } = pickPressureSession(sessions, normalizeSessionId(config?.sessionId));
-    const current = buildCompactPressureState(record, scopedConfig);
-    const next = mutator(current);
-    const normalized = buildCompactPressureState(next, scopedConfig);
+    const current = await buildCompactPressureState(record, scopedConfig);
+    const next = await mutator(current);
+    const normalized = await buildCompactPressureState(next, scopedConfig);
     sessions[id] = { ...normalized, updatedAt: Date.now() };
     await writeJson(runtimePaths.compactPressurePath, projectPressureDocument(sessions));
     return normalized;
@@ -1240,7 +1248,7 @@ export async function writeCompactPressureState(projectRoot, state, config = {})
   return withFileLock(runtimePaths.compactPressurePath, async () => {
     const sessions = readPressureDocument(await readJson(runtimePaths.compactPressurePath, null));
     const { id } = pickPressureSession(sessions, normalizeSessionId(config?.sessionId));
-    const normalized = buildCompactPressureState(state, scopedConfig);
+    const normalized = await buildCompactPressureState(state, scopedConfig);
     sessions[id] = { ...normalized, updatedAt: Date.now() };
     await writeJson(runtimePaths.compactPressurePath, projectPressureDocument(sessions));
     return normalized;
@@ -1306,6 +1314,28 @@ function extractPrompt(payload = {}) {
 }
 
 async function runCli() {
+  // BUG-C22-15: this CLI is spawned unbounded by skill-router.sh — every read it
+  // does (config, pressure record, transcript tail, capacity record) sits on the
+  // .ukit/transcript filesystem, so a stalled mount used to hang the child forever
+  // (the shell `|| true` swallows exit codes, not time, and the host SIGKILLs
+  // silently). Arm a self-deadline so ALL invokers get a bounded, announced exit.
+  const CLI_DEADLINE_MS = Number.parseInt(process.env.UKIT_COMPACT_CLI_DEADLINE_MS || '', 10) || 4000;
+  const cliDeadline = setTimeout(() => {
+    // BUG-C23-02: fsSync.writeSync(1, …), never process.stdout.write — on a pipe
+    // (this CLI is always piped) a same-tick process.exit() can discard the
+    // buffered async write, and the bare text line wasn't §8 JSON anyway.
+    try {
+      fsSync.writeSync(1, `${JSON.stringify({
+        systemMessage:
+          `[ukit-skill-router] compact-threshold prompt CLI exceeded its ${CLI_DEADLINE_MS}ms deadline — `
+          + 'pressure bookkeeping skipped this pass (likely stalled filesystem). The hook continues unharmed; '
+          + 'if this repeats, check the .ukit volume or raise UKIT_COMPACT_CLI_DEADLINE_MS.',
+      })}\n`);
+    } catch { /* stdout already gone */ }
+    process.exit(0);
+  }, CLI_DEADLINE_MS);
+  cliDeadline.unref();
+
   const mode = String(process.argv[2] ?? '').trim();
   if (!mode) {
     return;

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

@@ -149,17 +149,25 @@ export async function sweepExecLedgerDir(dir, {
   maxEntries = LEDGER_SWEEP_MAX_ENTRIES,
   maxRemovals = LEDGER_SWEEP_MAX_REMOVALS,
 } = {}) {
-  let names;
+  let dirents;
   try {
-    names = await fs.readdir(dir);
+    dirents = await fs.readdir(dir, { withFileTypes: true });
   } catch {
     return { scanned: 0, removed: 0 };
   }
   const cutoff = now() - maxAgeMs;
   const countCapCutoff = now() - LEDGER_COUNT_CAP_MIN_AGE_MS;
+  // BUG-C22-12: eligible count comes from the dirents (one bounded readdir, no
+  // per-name stat) so the count cap is enforceable even though
+  // maxFiles > maxEntries — capping `scanned` first made `entries.length` an
+  // under-count and `overflow` was always 0.
+  const eligibleNames = [];
+  for (const dirent of dirents) {
+    if (dirent.isFile()) eligibleNames.push(dirent.name);
+  }
   const entries = [];
   let scanned = 0;
-  for (const name of names) {
+  for (const name of eligibleNames) {
     if (scanned >= maxEntries) break;
     scanned += 1;
     try {
@@ -169,9 +177,9 @@ export async function sweepExecLedgerDir(dir, {
   }
   entries.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
   // Overflow counts eligible FILES only — foreign entries (`.lock` dirs, other
-  // state files sharing the dir) inflate `names.length` and would evict real
+  // state files sharing the dir) inflate the dir listing and would evict real
   // ledgers while the dir is actually under the cap.
-  const overflow = Math.max(0, entries.length - maxFiles);
+  const overflow = Math.max(0, eligibleNames.length - maxFiles);
   let removed = 0;
   for (const entry of entries) {
     if (removed >= maxRemovals) break;
@@ -196,6 +204,23 @@ export async function sweepExecLedgerDir(dir, {
 
 // Sampled gate — by default only ~1 in 16 ledger mutations pays for a bounded
 // sweep at all. Advisory: a sweep failure must never lose a ledger event.
+// BUG-C23-10: a bare `catch {}` around the sweep swallowed every failure — a
+// persistent EACCES/ENOSPC meant silent non-convergence of the exec-ledger dir
+// bound. Announce the first failure and then every 25th, C22 rate-limit
+// posture. writeSync(1) because a same-tick exit can drop a buffered write.
+let sweepFailureCount = 0;
+export function noteSweepFailure(error) {
+  sweepFailureCount += 1;
+  if (sweepFailureCount !== 1 && sweepFailureCount % 25 !== 0) return null;
+  const message =
+    `UKit execution-ledger: dir sweep failed (${sweepFailureCount} failure(s) so far) — `
+    + `the committed event is safe but the backlog bound may lag. Cause: ${error?.message || error}`;
+  try {
+    fsSync.writeSync(1, `${JSON.stringify({ systemMessage: message })}\n`);
+  } catch { /* stdout already gone */ }
+  return message;
+}
+
 export async function maybeSweepExecLedgerDir(dir, {
   probability,
   random = Math.random,
@@ -1178,7 +1203,8 @@ export async function recordLedgerEvent(event, {
   if (outcome.ok) {
     // Sampled bounded dir sweep (BUG-C21-11): runs outside the ledger lock so a
     // contended acquisition never pays sweep latency. Advisory — never throws.
-    try { await maybeSweepExecLedgerDir(path.dirname(target)); } catch { /* advisory */ }
+    // BUG-C23-10: a persistent failure is still surfaced as a bounded degrade.
+    try { await maybeSweepExecLedgerDir(path.dirname(target)); } catch (error) { noteSweepFailure(error); }
     return outcome.value;
   }
 
@@ -1701,6 +1727,11 @@ function isDirectRun() {
   const selfPath = fileURLToPath(import.meta.url);
   const resolved = path.resolve(argvPath);
   if (selfPath === resolved) return true;
+  // BUG-C22-01: a stalled mount must not park the event loop during `await import`
+  // — importing this module inside an armed hook deadline used to run realpathSync
+  // here for EVERY importer. Skip fs entirely when the basename cannot match (any
+  // importer argv like reinject-context.mjs differs from execution-ledger.mjs).
+  if (path.basename(selfPath) !== path.basename(resolved)) return false;
   try {
     return fsSync.realpathSync(selfPath) === fsSync.realpathSync(resolved);
   } catch {

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

@@ -17,13 +17,20 @@
 //
 // The clamps are intentionally generous (up to 120s) because they are an
 // explicit operator/test affordance, not a default: an unconfigured chain still
-// resolves to the 10s/4s/16s defaults that keep a PreToolUse call inside omp's
-// own handler budget.
+// resolves to the 10s/12s/52s defaults documented below.
+//
+// BUG-C22-25: the child fallback MUST cover a child's own internal worst case —
+// every staged .sh hook stages stdin (UKIT_HOOK_STAGE_MS default 2000) then arms
+// a node deadline of 3000-8000ms, so a child legitimately needs up to ~10s. The
+// old 4000ms fallback killed legal hooks mid-evaluation (recorded
+// failureKind:'timeout'; on tool_call chains the killed script can be a
+// FAIL_CLOSED gate). 12000 = 2000 stage + 8000 deadline + 2000 margin. The
+// ceiling fallback scales with it: 4 chained children × 12000 + 4000 slack.
 
 export const CHAIN_BUDGET_SPECS = {
   base: { name: 'UKIT_HOOK_CHAIN_BASE_MS', fallback: 10000, min: 500, max: 60000 },
-  child: { name: 'UKIT_HOOK_CHILD_BUDGET_MS', fallback: 4000, min: 100, max: 60000 },
-  ceiling: { name: 'UKIT_HOOK_CHAIN_CEILING_MS', fallback: 16000, min: 500, max: 120000 },
+  child: { name: 'UKIT_HOOK_CHILD_BUDGET_MS', fallback: 12000, min: 100, max: 60000 },
+  ceiling: { name: 'UKIT_HOOK_CHAIN_CEILING_MS', fallback: 52000, min: 500, max: 120000 },
 };
 
 // Margin the outer timeout adds on top of the runner's own budget: enough to

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

@@ -153,12 +153,16 @@ export function sweepTelemetryDir(dir, {
     return { scanned: 0, removed: 0 };
   }
   const cutoff = now() - maxAgeMs;
+  // BUG-C22-11: eligible count is computed from the full name listing (bounded
+  // by the single readdir, no per-name stat) so the count cap is enforceable
+  // even though maxFiles > maxEntries — capping `scanned` first made
+  // `entries.length` an under-count and `overflow` was always 0.
+  const eligibleNames = names.filter((name) => name.endsWith('.jsonl'));
   const entries = [];
   let scanned = 0;
-  for (const name of names) {
+  for (const name of eligibleNames) {
     if (scanned >= maxEntries) break;
     scanned += 1;
-    if (!name.endsWith('.jsonl')) continue;
     try {
       const stats = fs.statSync(path.join(dir, name));
       if (stats.isFile()) entries.push({ name, mtimeMs: stats.mtimeMs });
@@ -168,7 +172,7 @@ export function sweepTelemetryDir(dir, {
   // Overflow counts eligible FILES only — foreign entries (non-matching names,
   // dirs) inflate `names.length` and would evict real entries while the dir is
   // actually under the cap.
-  const overflow = Math.max(0, entries.length - maxFiles);
+  const overflow = Math.max(0, eligibleNames.length - maxFiles);
   let removed = 0;
   for (const entry of entries) {
     if (removed >= maxRemovals) break;
@@ -196,6 +200,22 @@ export function maybeSweepTelemetryDir(dir, {
   return { sampled: true, ...sweepTelemetryDir(dir, options) };
 }
 
+// BUG-C23-10: a bare `catch {}` around the sweep swallowed every failure — a
+// persistent EACCES/ENOSPC meant silent non-convergence of the dir bound.
+// Announce the first failure and then every 25th, C22 rate-limit posture.
+let sweepFailureCount = 0;
+export function noteSweepFailure(error) {
+  sweepFailureCount += 1;
+  if (sweepFailureCount !== 1 && sweepFailureCount % 25 !== 0) return null;
+  const message =
+    `UKit hook-telemetry: latency dir sweep failed (${sweepFailureCount} failure(s) so far) — `
+    + `the appended row is safe but the backlog bound may lag. Cause: ${error?.message || error}`;
+  try {
+    fs.writeSync(1, `${JSON.stringify({ systemMessage: message })}\n`);
+  } catch { /* stdout already gone */ }
+  return message;
+}
+
 export function appendTelemetryRow(projectRoot, sessionId, row, options = {}) {
   try {
     if (!row || typeof row !== 'object') return false;
@@ -207,7 +227,7 @@ export function appendTelemetryRow(projectRoot, sessionId, row, options = {}) {
     fs.appendFileSync(filePath, line, 'utf8');
     // Sampled bounded dir sweep (BUG-C21-10): advisory — a sweep failure must
     // never alter the row this call just appended.
-    try { maybeSweepTelemetryDir(dir); } catch { /* advisory */ }
+    try { maybeSweepTelemetryDir(dir); } catch (error) { noteSweepFailure(error); }
     return true;
   } catch {
     // Advisory: an unwritable or corrupt telemetry target must never alter a