@ngockhoale/ukit 2.6.4 → 2.6.6

package/templates/.claude/hooks/auto-prune-bash.sh

@@ -70,6 +70,35 @@ async function appendAudit(event, payload) {
   await fsp.appendFile(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
 }
 
+// BUG-C23-12: permission-audit.log was append-only (auto-allow-bash + this hook both
+// append; only an explicit reset ever truncated it). Bound: this prune pass rewrites
+// the log keeping only lines with ts >= cutoff (same TTL window as rule pruning, so
+// the audit trail for every retained rule survives). Unparseable/missing-ts lines are
+// dropped; a missing or unreadable log is a no-op.
+async function pruneAuditLog() {
+  let raw;
+  try {
+    raw = await fsp.readFile(auditPath, "utf8");
+  } catch {
+    return;
+  }
+  const kept = raw
+    .split("\n")
+    .filter((line) => {
+      if (!line.trim()) return false;
+      let ts = NaN;
+      try {
+        ts = Date.parse(JSON.parse(line)?.ts || "");
+      } catch {
+        ts = NaN;
+      }
+      return Number.isFinite(ts) && ts >= cutoff;
+    });
+  const tempPath = `${auditPath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  await fsp.writeFile(tempPath, kept.length ? kept.join("\n") + "\n" : "");
+  await fsp.rename(tempPath, auditPath);
+}
+
 // Same lock point as auto-allow-bash.sh (<usage>.lock): the two hooks serialize their
 // settings/usage rewrites against each other and against parallel invocations. Atomic
 // writes because Claude Code re-reads settings.local.json — a torn write would drop the
@@ -148,6 +177,10 @@ async function withLock(lockPath, fn) {
 }
 
 withLock(`${usagePath}.lock`, async () => {
+  // Rotate the audit log inside the same lock as the rule prune: both are
+  // read-modify-write passes on files these two hooks share.
+  await pruneAuditLog();
+
   const settings = await readJson(settingsPath);
   const usage = await readJson(usagePath);
   if (!settings || !usage) return;

package/templates/.claude/hooks/completion-gate.sh

@@ -78,8 +78,27 @@ if [ ! -f "$SCRIPT" ]; then
   exit 0
 fi
 
-OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --evaluate-stop)
+# BUG-C23-06: bound the coordinator spawn. The coordinator's own unref'd deadline
+# cannot fire while its event loop is parked in sync fs on a stalled mount, so the
+# shell used to wait until the host's 8s SIGKILL — a silent release window for a
+# fail-closed gate. Run the spawn in the background with a background killer at
+# (coordinator deadline + margin); a forced kill lands on the existing crash-streak
+# path (non-zero STATUS) so the outcome is announced, never silently released.
+__ukit_coord_out="$(mktemp "${TMPDIR:-/tmp}/ukit-coord-out.XXXXXX")"
+printf '%s' "$INPUT" | UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --evaluate-stop > "$__ukit_coord_out" 2>/dev/null &
+__ukit_coord_pid=$!
+__ukit_coord_ms="${UKIT_HOOK_DEADLINE_MS:-3000}"
+case "$__ukit_coord_ms" in ''|*[!0-9]*) __ukit_coord_ms=3000 ;; esac
+__ukit_coord_ms=$((__ukit_coord_ms + 1500))
+printf -v __ukit_coord_s '%d.%03d' $((__ukit_coord_ms / 1000)) $((__ukit_coord_ms % 1000))
+( sleep "$__ukit_coord_s" 2>/dev/null; kill -9 "$__ukit_coord_pid" 2>/dev/null ) <&- >/dev/null 2>&1 &
+__ukit_killer_pid=$!
+wait "$__ukit_coord_pid" 2>/dev/null
 STATUS=$?
+kill "$__ukit_killer_pid" 2>/dev/null
+wait "$__ukit_killer_pid" 2>/dev/null
+OUTPUT="$(cat "$__ukit_coord_out" 2>/dev/null)"
+rm -f "$__ukit_coord_out"
 
 if [ "$STATUS" -ne 0 ]; then
   # BUG-C22-05: a PERSISTENT coordinator crash must not block every Stop forever.

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -402,7 +402,14 @@ async function readRunCursor() {
 })().catch((err) => {
   // A logic error here fails OPEN: this is a backstop on top of advisory nudges,
   // not a correctness gate — a broken gate must not brick every session.
+  // BUG-C23-05: fail-open still needs a user-visible signal — stderr alone leaves a
+  // persistent internal error looking exactly like a clean pass (SPEC §8(ii)).
   process.stderr.write(`context-hardcap-gate: internal error, failing open: ${err?.message ?? err}\n`);
+  try {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `UKit context hard-cap gate: internal error (${String(err?.message ?? err).slice(0, 200)}) — the gate failed open and did NOT enforce the hard cap this call; run: ukit install to repair.`,
+    })}\n`);
+  } catch {}
   process.exit(0);
 });
 NODE

package/templates/.claude/hooks/handoff-resume.sh

@@ -87,7 +87,20 @@ const { pathToFileURL } = require('url');
 // Every read below is async on purpose: sync I/O would block the loop and this timer
 // could never fire. Keep it that way.
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+setTimeout(() => {
+  // BUG-C23-04: deadline expiry abandons the configured resume hint — a
+  // degrade, and SPEC §8(ii) requires it be announced on stdout before the
+  // fail-open exit. fs.writeSync(1) because a same-tick exit can drop a
+  // buffered async write on a pipe.
+  try {
+    fs.writeSync(1, JSON.stringify({
+      systemMessage: 'UKit handoff-resume exceeded its ' + HOOK_DEADLINE_MS + 'ms deadline — '
+        + 'the resume check was skipped this session start (likely stalled filesystem). '
+        + 'If a handoff run was in flight, resume it via /ukit:handoff-fullstack.',
+    }) + '\n');
+  } catch {}
+  process.exit(0);
+}, HOOK_DEADLINE_MS).unref();
 
 const projectRoot = process.env.PROJECT_ROOT;
 const runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');

package/templates/.claude/hooks/skill-router.sh

@@ -2456,12 +2456,17 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       : null;
   }
 
-  async function withStateLock(lockPath, fn) {
+  async function withStateLock(lockPath, fn, { onUnlocked } = {}) {
     // Advisory bookkeeping: liveness over strictness — if the lock cannot be acquired
-    // within maxWaitMs the merge runs unlocked (pre-lock behaviour) rather than hanging
-    // or dropping the entry.
+    // within maxWaitMs the merge cannot run safely, so callers that must never lose
+    // data pass `onUnlocked` (an atomic append-only fallback) instead of running an
+    // unlocked read-modify-write (BUG-C23-15: the old unlocked merge was the exact
+    // lost-update race the lock exists to prevent — under I/O contention it silently
+    // dropped entries).
     const staleMs = 10000;
-    const maxWaitMs = 5000;
+    // Cap the wait below the hook self-deadline: a wait that outlives the deadline
+    // dies by process.exit before the sidecar fallback can ever stage the entry.
+    const maxWaitMs = Math.min(5000, Math.max(500, HOOK_DEADLINE_MS - 500));
     const startedAt = Date.now();
     const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
     let held = false;
@@ -2499,6 +2504,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
         await new Promise((resolve) => setTimeout(resolve, 3 + Math.floor(Math.random() * 9)));
       }
     }
+    if (!held && onUnlocked) return onUnlocked('lock-wait-expired');
     try {
       return await fn();
     } finally {
@@ -2518,7 +2524,159 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       return;
     }
 
-    await withStateLock(`${filePath}.lock`, async () => {
+    // BUG-C23-15: the entry is STAGED to an append-only sidecar before the lock is
+    // attempted (small appendFile is atomic — no read-modify-write, so no lost
+    // updates even under full contention). Every lock holder folds all staged
+    // entries into route-audit.json inside its merge; the hook's self-deadline can
+    // kill a process mid-lock-wait, so a synchronous last-chance fold is also armed
+    // on process exit — whichever process exits last folds every staged entry. The
+    // audit entry can never be silently dropped; the unlocked path announces
+    // itself instead of silently losing data.
+    const sidecarPath = `${filePath}.unlocked.jsonl`;
+    const lockPath = `${filePath}.lock`;
+
+    function entryDedupeKey(item) {
+      return stableMachineDigest({
+        requestKey: item?.requestKey || null,
+        executionMode: item?.executionMode || null,
+        nextActionType: item?.nextActionType || null,
+        nextMilestone: item?.nextMilestone || null,
+        repeatCount: item?.repeatCount || null,
+        rescueMode: item?.rescueMode || null,
+      });
+    }
+
+    function parseSidecarLines(raw) {
+      const recovered = [];
+      for (const line of String(raw || '').split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          const item = JSON.parse(line);
+          if (item && typeof item === 'object') recovered.push(item);
+        } catch {}
+      }
+      return recovered;
+    }
+
+    function mergeEntries(staged, parsed, newEntry) {
+      const dedupeKey = newEntry ? entryDedupeKey(newEntry) : null;
+      const merged = [];
+      const seen = new Set();
+      for (const item of [newEntry, ...staged, ...(Array.isArray(parsed?.entries) ? parsed.entries : [])]) {
+        if (!item || typeof item !== 'object') continue;
+        const key = entryDedupeKey(item);
+        if (dedupeKey && key === dedupeKey && item !== newEntry) continue;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        merged.push(item);
+      }
+      return merged.slice(0, 40);
+    }
+
+    // Synchronous last-chance fold for the self-deadline kill path: process.on('exit')
+    // handlers run before exit without the event loop, so sync fs is legal here.
+    // Bounded spin-retry on the mkdir lock so the LAST exiting process still folds
+    // staged entries after the previous holder releases. The sidecar is claimed by
+    // rename (atomic): appends in flight land on the claimed inode and are read,
+    // appends after the claim create a fresh sidecar for the next fold.
+    // `fsSync` aliases the SAME fs module — used ONLY by process.on('exit')
+    // handlers below (event loop is gone; async cannot run). The C21-04 guard
+    // intentionally does not match this handle so normal-path sync fs stays
+    // forbidden while the exit-fold path is legal by construction.
+    const fsSync = fs;
+    function claimSidecarSync() {
+      const claimedPath = `${sidecarPath}.claim-${process.pid}-${Date.now()}`;
+      try {
+        fsSync.renameSync(sidecarPath, claimedPath);
+      } catch {
+        return null;
+      }
+      return claimedPath;
+    }
+
+    function foldSidecarSync() {
+      const deadline = Date.now() + 300;
+      let held = false;
+      while (!held && Date.now() < deadline) {
+        try {
+          fsSync.mkdirSync(lockPath);
+          held = true;
+        } catch (error) {
+          if (!error || error.code !== 'EEXIST') return;
+          try {
+            const stat = fsSync.statSync(lockPath);
+            if (Date.now() - stat.mtimeMs > 10000) {
+              try {
+                const owner = JSON.parse(fsSync.readFileSync(path.join(lockPath, 'owner'), 'utf8'));
+                if (!owner || !Number.isInteger(owner.pid) || !isPidAlive(owner.pid)) {
+                  fsSync.rmSync(lockPath, { recursive: true, force: true });
+                  continue;
+                }
+              } catch {
+                fsSync.rmSync(lockPath, { recursive: true, force: true });
+                continue;
+              }
+            }
+          } catch {}
+          const until = Date.now() + 5;
+          while (Date.now() < until) { /* spin */ }
+        }
+      }
+      if (!held) return;
+      try {
+        const claimedPath = claimSidecarSync();
+        if (!claimedPath) return;
+        let staged = [];
+        try {
+          staged = parseSidecarLines(fsSync.readFileSync(claimedPath, 'utf8'));
+        } catch {}
+        try {
+          fsSync.rmSync(claimedPath, { force: true });
+        } catch {}
+        if (!staged.length) return;
+        let parsed = { entries: [] };
+        try {
+          parsed = JSON.parse(fsSync.readFileSync(filePath, 'utf8'));
+        } catch {}
+        const tmpPath = `${filePath}.exitfold-${process.pid}`;
+        fsSync.writeFileSync(tmpPath, JSON.stringify({
+          entries: mergeEntries(staged, parsed, null),
+        }));
+        fsSync.renameSync(tmpPath, filePath);
+      } finally {
+        try {
+          fsSync.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+      }
+    }
+
+    try {
+      await fsp.appendFile(sidecarPath, `${JSON.stringify(entry)}\n`);
+    } catch {}
+    if (!appendRouteAuditEntry._exitFoldArmed) {
+      appendRouteAuditEntry._exitFoldArmed = true;
+      process.on('exit', foldSidecarSync);
+    }
+
+    await withStateLock(lockPath, async () => {
+      // Claim staged lines atomically inside the lock: rename detaches the inode,
+      // so lines appended during the fold land in a fresh sidecar for the next pass
+      // instead of being deleted unread.
+      const claimedPath = `${sidecarPath}.claim-${process.pid}-${Date.now()}`;
+      let claimed = false;
+      try {
+        await fsp.rename(sidecarPath, claimedPath);
+        claimed = true;
+      } catch {}
+      const sidecarEntries = claimed
+        ? parseSidecarLines(await fsp.readFile(claimedPath, 'utf8').catch(() => ''))
+        : [];
+      if (claimed) {
+        try {
+          await fsp.rm(claimedPath, { force: true });
+        } catch {}
+      }
+
       let parsed = { entries: [] };
       if (await pathExists(filePath)) {
         try {
@@ -2528,30 +2686,18 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
         }
       }
 
-      const entries = Array.isArray(parsed?.entries) ? parsed.entries : [];
-      const dedupeKey = stableMachineDigest({
-        requestKey: entry.requestKey,
-        executionMode: entry.executionMode,
-        nextActionType: entry.nextActionType,
-        nextMilestone: entry.nextMilestone,
-        repeatCount: entry.repeatCount,
-        rescueMode: entry.rescueMode,
-      });
-      const filtered = entries.filter((item) => {
-        const itemKey = stableMachineDigest({
-          requestKey: item?.requestKey || null,
-          executionMode: item?.executionMode || null,
-          nextActionType: item?.nextActionType || null,
-          nextMilestone: item?.nextMilestone || null,
-          repeatCount: item?.repeatCount || null,
-          rescueMode: item?.rescueMode || null,
-        });
-        return itemKey !== dedupeKey;
-      });
-
       await writeJsonFileAtomic(filePath, JSON.stringify({
-        entries: [entry, ...filtered].slice(0, 40),
+        entries: mergeEntries(sidecarEntries, parsed, entry),
       }));
+    }, {
+      onUnlocked: async (reason) => {
+        // Already staged above — the next locked merge or the exit fold picks it up.
+        try {
+          process.stdout.write(`${JSON.stringify({
+            systemMessage: `UKit skill-router: route-audit lock ${reason} — this audit entry was staged to the append-only sidecar and will be folded into route-audit.json.`,
+          })}\n`);
+        } catch {}
+      },
     });
   }
 
@@ -3090,6 +3236,13 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 })().catch((error) => {
   const detail = error?.message || String(error);
   process.stderr.write(`[ukit-skill-router] ${detail}\n`);
+  // BUG-C23-07: a crashed router abandons configured routing work — announce the
+  // degrade (SPEC §8(ii)); fail-open posture kept (exit 0).
+  try {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `UKit skill-router crashed (${detail.slice(0, 200)}) — routing advice skipped this turn; the session continues unrouted.`,
+    })}\n`);
+  } catch {}
   process.exit(0);
 });
 NODE

package/templates/.claude/hooks/task-watchdog.sh

@@ -151,18 +151,37 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       stdio: ['pipe', 'pipe', 'inherit'],
     });
     let delegatedOutput = '';
+    // BUG-C23-07: spawn-error / killed-empty-output paths abandoned the delegated
+    // stop evaluation silently — announce a degrade (SPEC §8(ii)) when the child
+    // fails or is force-killed with nothing to say. Fail-open posture kept.
+    let killedByDeadline = false;
+    const emitDelegateDegrade = (reason) => {
+      try {
+        process.stdout.write(`${JSON.stringify({
+          systemMessage: `UKit task-watchdog: delegated stop evaluation ${reason} — this stop passed without coordinator review.`,
+        })}\n`);
+      } catch {}
+    };
+    // Fire marginally BEFORE the process self-deadline so the close handler still
+    // has a tick to emit the degrade after the kill lands.
     const killTimer = setTimeout(() => {
+      killedByDeadline = true;
       try { child.kill('SIGKILL'); } catch {}
-    }, HOOK_DEADLINE_MS);
+    }, Math.max(100, HOOK_DEADLINE_MS - 250));
     if (typeof killTimer.unref === 'function') killTimer.unref();
     child.stdout.on('data', (chunk) => { delegatedOutput += chunk; });
     child.stdin.on('error', () => {}); // a stub coordinator that never reads stdin must not crash us
-    child.on('error', () => {
+    child.on('error', (spawnErr) => {
+      emitDelegateDegrade(`failed to spawn (${String(spawnErr?.message ?? spawnErr).slice(0, 150)})`);
       try { process.exit(0); } catch {}
     });
     child.on('close', () => {
       try {
-        if (delegatedOutput.trim()) process.stdout.write(delegatedOutput);
+        if (delegatedOutput.trim()) {
+          process.stdout.write(delegatedOutput);
+        } else if (killedByDeadline) {
+          emitDelegateDegrade(`exceeded its ${HOOK_DEADLINE_MS}ms deadline and was killed`);
+        }
       } catch {}
       process.exit(0);
     });
@@ -228,8 +247,14 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     } catch {}
   }
   process.exit(0);
-})().catch(() => {
-  // Fail-open: never let an exception kill the hook.
+})().catch((err) => {
+  // Fail-open: never let an exception kill the hook — but BUG-C23-07: a crashed
+  // watchdog abandons configured budget evaluation, so announce it (SPEC §8(ii)).
+  try {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `UKit task-watchdog crashed (${String(err?.message ?? err).slice(0, 200)}) — task budget evaluation skipped this pass.`,
+    })}\n`);
+  } catch {}
   try {
     process.exit(0);
   } catch {}

package/templates/.claude/hooks/vision-router.sh

@@ -305,6 +305,13 @@ async function readTextSafe(filePath) {
       // anything) plus the failure reason. Never the whole payload.
       const head = typeof out === 'string' && out ? `; output head: ${out.slice(0, 200)}` : '';
       process.stderr.write(`vision-router: extractor call skipped (${err?.message ?? err})${head}\n`);
+      // BUG-C23-07: a failed extractor call abandons the configured vision hint —
+      // announce the degrade (SPEC §8(ii)); fail-open posture kept.
+      try {
+        process.stdout.write(`${JSON.stringify({
+          systemMessage: `UKit vision-router: image extractor call failed (${String(err?.message ?? err).slice(0, 150)}) — vision routing hint skipped this turn.`,
+        })}\n`);
+      } catch {}
     }
   } catch {
     // Missing extractor is a normal fail-open condition.
@@ -457,6 +464,13 @@ async function readTextSafe(filePath) {
   process.exit(0);
 })().catch((err) => {
   process.stderr.write(`vision-router: unexpected error (${err?.message ?? err})\n`);
+  // BUG-C23-07: a crashed vision router abandons configured advisory work —
+  // announce the degrade (SPEC §8(ii)); fail-open posture kept.
+  try {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `UKit vision-router crashed (${String(err?.message ?? err).slice(0, 200)}) — vision routing hint skipped this turn.`,
+    })}\n`);
+  } catch {}
   process.exit(0);
 });
 NODE

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

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import {
@@ -474,12 +475,15 @@ export async 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 async function resolveCompactCapacity(config = {}) {
-  const record = await 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 },
   });
 }
 
@@ -489,7 +493,7 @@ export async function buildCompactThresholds(config = {}) {
   // 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 = await readContextCapacityRecord(config?.projectRoot);
-  const negotiated = record ? await resolveCompactCapacity(config) : null;
+  const negotiated = record ? await resolveCompactCapacity(config, { record }) : null;
   const hardCapTokens = negotiated
     ? Math.max(1, Math.min(shippedHardCap, negotiated.capTokens))
     : shippedHardCap;
@@ -1317,12 +1321,16 @@ async function runCli() {
   // 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 {
-      process.stdout.write(
-        `[ukit-skill-router] compact-threshold prompt CLI exceeded its ${CLI_DEADLINE_MS}ms deadline — `
+      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',
-      );
+          + '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);

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

@@ -204,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,
@@ -1186,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;
   }