@ngockhoale/ukit 2.6.3 → 2.6.5

package/src/core/memory/store.js

@@ -207,15 +207,22 @@ async function readProjectMemoryForId(runtimePaths, projectId) {
   return { filePath, memory };
 }
 
-async function appendSessionArchive(runtimePaths, projectId, archivedSessions) {
+const DEFAULT_MAX_ARCHIVED_SESSIONS = 50;
+
+async function appendSessionArchive(runtimePaths, projectId, archivedSessions, maxArchivedSessions) {
   if (!archivedSessions || archivedSessions.length === 0) {
     return;
   }
 
+  // Math.max(1, …): a fractional cap in (0,1) would floor to 0 and `slice(-0)`
+  // silently disables the bound — exactly the unbounded-growth class this caps.
+  const cap = Number.isFinite(maxArchivedSessions) && maxArchivedSessions > 0
+    ? Math.max(1, Math.floor(maxArchivedSessions))
+    : DEFAULT_MAX_ARCHIVED_SESSIONS;
   const archivePath = path.join(runtimePaths.projectsDir, `${sanitizeProjectId(projectId)}.archive.json`);
   const existing = (await readMemoryJson(archivePath)) ?? { sessions: [] };
   const sessions = Array.isArray(existing.sessions) ? existing.sessions : [];
-  await writeJson(archivePath, { sessions: [...sessions, ...archivedSessions] });
+  await writeJson(archivePath, { sessions: [...sessions, ...archivedSessions].slice(-cap) });
 }
 
 async function persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory) {
@@ -228,7 +235,7 @@ async function persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projec
   };
 
   const { projectMemory: hygienicMemory, archivedSessions } = runHygiene(memory, hygieneConfig);
-  await appendSessionArchive(runtimePaths, projectId, archivedSessions);
+  await appendSessionArchive(runtimePaths, projectId, archivedSessions, memoryConfig.maxArchivedSessions);
   await writeJson(filePath, hygienicMemory);
   return hygienicMemory;
 }

package/src/core/runInstallPipeline.js

@@ -7,7 +7,7 @@ import { detectProviders } from '../context/detectProviders.js';
 import { buildTemplateVariables } from '../render/buildVariables.js';
 import { buildInstallPlan } from './buildPlan.js';
 import { diffInstallPlan } from './diffPlan.js';
-import { applyDiffResults } from './applyPlan.js';
+import { applyDiffResults, pruneOldBackups } from './applyPlan.js';
 import { summarizeDiff, toDiffRows } from './report.js';
 import { writeInstallMetadata } from './metadata.js';
 import { cleanupLegacyPaths, migrateLegacyRuntimeRoot } from './migrateLegacy.js';
@@ -310,6 +310,15 @@ export async function runInstallPipeline({
       projectRoot: pathConfig.projectRoot,
     });
 
+    // BUG-C22-19: bound the .bak accumulation — every overwrite_with_backup write
+    // adds one and nothing removed them. Advisory: a prune failure must never
+    // fail the install.
+    try {
+      await pruneOldBackups(pathConfig.backupRoot);
+    } catch (pruneError) {
+      console.warn(`[UKit] Warning: backup pruning skipped — ${pruneError?.message ?? pruneError}`);
+    }
+
     // Only run migration cleanup on reinstalls. Fresh installs have no legacy
     // UKit files to migrate, so running cleanup risks deleting user files that
     // happen to share a legacy path name (e.g. .claude/skills/delivery.md).

package/src/core/runtimeConfig.js

@@ -164,6 +164,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       maxInjectionTokens: 1000,
       archiveAfterDays: 30,
       maxSessions: 20,
+      maxArchivedSessions: 50,
       redactSecrets: true,
     },
     validation: {
@@ -362,6 +363,7 @@ export function validateRuntimeConfig(config) {
     pushPositiveNumberError(errors, config.memory.maxInjectionTokens, 'memory.maxInjectionTokens');
     pushPositiveNumberError(errors, config.memory.archiveAfterDays, 'memory.archiveAfterDays');
     pushPositiveNumberError(errors, config.memory.maxSessions, 'memory.maxSessions');
+    pushPositiveNumberError(errors, config.memory.maxArchivedSessions, 'memory.maxArchivedSessions');
     pushBooleanError(errors, config.memory.redactSecrets, 'memory.redactSecrets');
   }
 

package/src/core/status.js

@@ -143,7 +143,7 @@ export async function buildStatusReport(projectRoot) {
   const config = await loadRuntimeConfig(projectRoot);
   const compactHistory = normalizeCompactEntries(await readStatusJson(runtimePaths.compactHistoryPath));
   const compactSummary = buildCompactSummary(compactHistory);
-  const compactPressure = buildCompactPressureState(
+  const compactPressure = await buildCompactPressureState(
     await readStatusJson(runtimePaths.compactPressurePath),
     config,
   );

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

@@ -145,7 +145,7 @@ UKIT_RUNTIME_DIR="$SCRIPT_DIR/../ukit/runtime" node -e '
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 8000;
 const LOCK_STARTED_AT = Date.now();
 setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-const fs = require("fs");
+const fsp = require("fs").promises;
 const path = require("path");
 const { pathToFileURL } = require("url");
 
@@ -156,35 +156,44 @@ const rule = process.argv[4];
 const nowUtc = process.argv[5];
 const maxRules = Math.max(1, Number(process.argv[6]) || 150);
 
-function readJson(filePath, fallback) {
-  if (!fs.existsSync(filePath)) return fallback;
+async function pathExists(filePath) {
   try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    await fsp.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(filePath, fallback) {
+  if (!(await pathExists(filePath))) return fallback;
+  try {
+    return JSON.parse(await fsp.readFile(filePath, "utf8"));
   } catch {
     return fallback;
   }
 }
 
-function writeJsonAtomic(filePath, value) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+async function writeJsonAtomic(filePath, value) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
   const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
   try {
-    fs.writeFileSync(tempPath, JSON.stringify(value, null, 2) + "\n");
-    fs.renameSync(tempPath, filePath);
+    await fsp.writeFile(tempPath, JSON.stringify(value, null, 2) + "\n");
+    await fsp.rename(tempPath, filePath);
   } catch (error) {
     try {
-      fs.rmSync(tempPath, { force: true });
+      await fsp.rm(tempPath, { force: true });
     } catch {}
     throw error;
   }
 }
 
-function appendAudit(event, payload) {
-  fs.appendFileSync(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
+async function appendAudit(event, payload) {
+  await fsp.appendFile(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
 }
 
 async function applyMutation() {
-  const settings = readJson(settingsPath, {});
+  const settings = await readJson(settingsPath, {});
   if (!settings.permissions || typeof settings.permissions !== "object") {
     settings.permissions = {};
   }
@@ -192,7 +201,7 @@ async function applyMutation() {
     settings.permissions.allow = [];
   }
 
-  const usage = readJson(usagePath, {});
+  const usage = await readJson(usagePath, {});
   if (!usage.managedRules || typeof usage.managedRules !== "object") {
     usage.managedRules = {};
   }
@@ -203,7 +212,7 @@ async function applyMutation() {
   if (!allow.includes(rule)) {
     allow.push(rule);
     settingsChanged = true;
-    appendAudit("auto_add", { rule });
+    await appendAudit("auto_add", { rule });
   }
 
   const prevMeta = usage.managedRules[rule] || {};
@@ -227,27 +236,27 @@ async function applyMutation() {
         allow.splice(idx, 1);
         settingsChanged = true;
       }
-      appendAudit("auto_prune_cap", { rule: evictRule, maxRules });
+      await appendAudit("auto_prune_cap", { rule: evictRule, maxRules });
     }
   }
 
   if (settingsChanged) {
-    writeJsonAtomic(settingsPath, settings);
+    await writeJsonAtomic(settingsPath, settings);
   }
-  writeJsonAtomic(usagePath, usage);
+  await writeJsonAtomic(usagePath, usage);
 }
 
 (async () => {
   // The lock directory lives beside the usage file, so its parent must exist BEFORE
   // the lock is taken — a first-ever run in a fresh project would otherwise fail
   // mkdir with ENOENT.
-  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
-  fs.mkdirSync(path.dirname(usagePath), { recursive: true });
+  await fsp.mkdir(path.dirname(settingsPath), { recursive: true });
+  await fsp.mkdir(path.dirname(usagePath), { recursive: true });
 
   const runtimeDir = process.env.UKIT_RUNTIME_DIR || "";
   const lockModulePath = runtimeDir ? path.join(runtimeDir, "async-lock.mjs") : "";
   let lockModule = null;
-  if (lockModulePath && fs.existsSync(lockModulePath)) {
+  if (lockModulePath && (await pathExists(lockModulePath))) {
     try {
       lockModule = await import(pathToFileURL(lockModulePath).href);
     } catch {

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

@@ -17,9 +17,24 @@ node -e '
 // Deadline must exceed the bounded lock wait in this block (maxWaitMs = 5000) so the
 // watchdog can never fire while the mutation is still legally waiting for the lock.
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 8000;
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
+// SPEC §8: a failed prune abandons configured work — announce it (success stays silent).
+// Unpruned rules are harmless (stale entries simply never match again), so degrade is
+// advisory-only and still exits 0.
+function emitDegrade(reason) {
+  try {
+    process.stdout.write(JSON.stringify({
+      systemMessage: `UKit auto-prune-bash: ${reason}`,
+    }) + "\n");
+  } catch {}
+}
+
+setTimeout(() => {
+  emitDegrade("prune exceeded its deadline; stale Bash auto-allow rules were not pruned this session — the next session retries.");
+  process.exit(0);
+}, HOOK_DEADLINE_MS).unref();
 const crypto = require("crypto");
-const fs = require("fs");
+const fsp = require("fs").promises;
 const path = require("path");
 
 const settingsPath = process.argv[1];
@@ -29,30 +44,59 @@ const ttlDays = Math.max(1, Number(process.argv[4]) || 30);
 const nowUtc = process.argv[5];
 const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
 
-function readJson(filePath) {
+async function readJson(filePath) {
   try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return JSON.parse(await fsp.readFile(filePath, "utf8"));
   } catch {
     return null;
   }
 }
 
-function writeJsonAtomic(filePath, value) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+async function writeJsonAtomic(filePath, value) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
   const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
   try {
-    fs.writeFileSync(tempPath, JSON.stringify(value, null, 2) + "\n");
-    fs.renameSync(tempPath, filePath);
+    await fsp.writeFile(tempPath, JSON.stringify(value, null, 2) + "\n");
+    await fsp.rename(tempPath, filePath);
   } catch (error) {
     try {
-      fs.rmSync(tempPath, { force: true });
+      await fsp.rm(tempPath, { force: true });
     } catch {}
     throw error;
   }
 }
 
-function appendAudit(event, payload) {
-  fs.appendFileSync(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
+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
@@ -70,8 +114,8 @@ function isPidAlive(pid) {
   }
 }
 
-function readLockOwner(lockPath) {
-  const owner = readJson(path.join(lockPath, "owner"), null);
+async function readLockOwner(lockPath) {
+  const owner = await readJson(path.join(lockPath, "owner"));
   return owner && Number.isInteger(owner.pid) && typeof owner.token === "string"
     ? owner
     : null;
@@ -85,17 +129,17 @@ async function withLock(lockPath, fn) {
   let held = false;
   while (!held) {
     try {
-      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-      fs.mkdirSync(lockPath);
+      await fsp.mkdir(path.dirname(lockPath), { recursive: true });
+      await fsp.mkdir(lockPath);
       try {
-        fs.writeFileSync(path.join(lockPath, "owner"), JSON.stringify({
+        await fsp.writeFile(path.join(lockPath, "owner"), JSON.stringify({
           pid: process.pid,
           token: ownerToken,
           ts: Date.now(),
         }));
       } catch (error) {
         try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
+          await fsp.rm(lockPath, { recursive: true, force: true });
         } catch {}
         throw error;
       }
@@ -103,12 +147,12 @@ async function withLock(lockPath, fn) {
     } catch (error) {
       if (!error || error.code !== "EEXIST") return fn();
       try {
-        const stat = fs.statSync(lockPath);
+        const stat = await fsp.stat(lockPath);
         if (Date.now() - stat.mtimeMs > staleMs) {
-          const owner = readLockOwner(lockPath);
+          const owner = await readLockOwner(lockPath);
           if (!owner || !isPidAlive(owner.pid)) {
             try {
-              fs.rmSync(lockPath, { recursive: true, force: true });
+              await fsp.rm(lockPath, { recursive: true, force: true });
               continue;
             } catch {}
           }
@@ -122,10 +166,10 @@ async function withLock(lockPath, fn) {
     return await fn();
   } finally {
     if (held) {
-      const owner = readLockOwner(lockPath);
+      const owner = await readLockOwner(lockPath);
       if (owner?.token === ownerToken) {
         try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
+          await fsp.rm(lockPath, { recursive: true, force: true });
         } catch {}
       }
     }
@@ -133,8 +177,12 @@ async function withLock(lockPath, fn) {
 }
 
 withLock(`${usagePath}.lock`, async () => {
-  const settings = readJson(settingsPath);
-  const usage = readJson(usagePath);
+  // 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;
   if (!settings.permissions || typeof settings.permissions !== "object") return;
   if (!Array.isArray(settings.permissions.allow)) return;
@@ -155,20 +203,23 @@ withLock(`${usagePath}.lock`, async () => {
     }
     delete usage.managedRules[rule];
     prunedCount += 1;
-    appendAudit("auto_prune_ttl", { rule, ttlDays });
+    await appendAudit("auto_prune_ttl", { rule, ttlDays });
   }
 
   usage.lastPruneAt = nowUtc;
 
   if (changedSettings) {
-    writeJsonAtomic(settingsPath, settings);
+    await writeJsonAtomic(settingsPath, settings);
   }
-  writeJsonAtomic(usagePath, usage);
+  await writeJsonAtomic(usagePath, usage);
 
   if (prunedCount > 0) {
-    appendAudit("auto_prune_summary", { prunedCount, ttlDays });
+    await appendAudit("auto_prune_summary", { prunedCount, ttlDays });
   }
-}).catch(() => {});
-' "$SETTINGS_LOCAL" "$USAGE_FILE" "$AUDIT_FILE" "$TTL_DAYS" "$NOW_UTC" >/dev/null 2>&1 || true
+}).catch((error) => {
+  emitDegrade(`prune failed (${error?.message ?? error}); stale Bash auto-allow rules were not pruned this session — the next session retries.`);
+  process.exit(0);
+});
+' "$SETTINGS_LOCAL" "$USAGE_FILE" "$AUDIT_FILE" "$TTL_DAYS" "$NOW_UTC" 2>/dev/null || true
 
 exit 0

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

@@ -78,17 +78,57 @@ 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.
+  # Byte-append one marker per crash; a clean run deletes the file, so the count
+  # is consecutive crashes, not lifetime crashes. File-based (no node) so the
+  # breaker still works when node itself is what is crashing.
+  CRASH_FILE="$PROJECT_ROOT/.ukit/storage/cache/completion-gate-crash.streak"
+  mkdir -p "$(dirname "$CRASH_FILE")" 2>/dev/null
+  printf '.' >> "$CRASH_FILE" 2>/dev/null
+  STREAK="$(wc -c < "$CRASH_FILE" 2>/dev/null | tr -d '[:space:]')"
+  case "$STREAK" in ''|*[!0-9]*) STREAK=1 ;; esac
+  MAX_STREAK="$(sed -n 's/.*"stopGateMaxCrashStreaks"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$PROJECT_ROOT/.ukit/storage/config.json" 2>/dev/null | head -1)"
+  case "$MAX_STREAK" in ''|*[!0-9]*) MAX_STREAK=3 ;; esac
+  if [ "$STREAK" -gt "$MAX_STREAK" ]; then
+    # Loud release after the cap: the gate is broken, not the work — say so,
+    # name remediation, and let the session end instead of looping forever.
+    rm -f "$CRASH_FILE" 2>/dev/null
+    printf '%s\n' '{"systemMessage":"UKit stop coordinator released this stop after '"$MAX_STREAK"' consecutive infrastructure failures (the coordinator crashed every Stop — gate fail-closed cap reached). The completion gate is DOWN, not your work: run `ukit install` to repair, then re-send the task in a new message if the run must continue."}'
+    exit 0
+  fi
   # TASK-025: the Stop coordinator is the fail-closed blocker — a crash must not
   # release the stop. The reason is a fixed redacted string: crash detail (already
   # written to stderr by the coordinator) never leaks into the decision.
-  printf '%s\n' '{"decision":"block","reason":"UKit stop coordinator: infrastructure failure while evaluating this stop — the stop is blocked fail-closed (details withheld). Run: ukit install, then re-send the task in a new message."}'
+  printf '%s\n' '{"decision":"block","reason":"UKit stop coordinator: infrastructure failure while evaluating this stop — the stop is blocked fail-closed (crash streak '"$STREAK"'/'"$MAX_STREAK"'; details withheld). Run: ukit install, then re-send the task in a new message."}'
   exit 0
 fi
 
+# A clean coordinator run resets the consecutive-crash streak.
+rm -f "$PROJECT_ROOT/.ukit/storage/cache/completion-gate-crash.streak" 2>/dev/null
+
 if [ -n "$OUTPUT" ]; then
   printf '%s\n' "$OUTPUT"
 fi

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

@@ -89,7 +89,16 @@ fi
 
 INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" HOOK_DIR="$HOOK_DIR" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+// SPEC §8: a timed-out gate silently passes work it never evaluated — announce the
+// degrade (fail-open posture kept: still exit 0).
+setTimeout(() => {
+  try {
+    process.stdout.write(JSON.stringify({
+      systemMessage: `UKit context hard-cap gate: evaluation exceeded its ${HOOK_DEADLINE_MS}ms deadline; this tool call proceeded without the hard-cap check.`,
+    }) + '\n');
+  } catch {}
+  process.exit(0);
+}, HOOK_DEADLINE_MS).unref();
 const fs = require('fs');
 const fsp = fs.promises;
 const path = require('path');
@@ -179,6 +188,12 @@ async function readRunCursor() {
 
   const thresholdModulePath = path.join(hookDir, '..', 'ukit', 'runtime', 'compact-threshold.mjs');
   if (!(await pathExists(thresholdModulePath))) {
+    // SPEC §8: a missing runtime silently disables a fail-closed gate — announce.
+    try {
+      process.stdout.write(JSON.stringify({
+        systemMessage: 'UKit context hard-cap gate: compact-threshold runtime missing — gate skipped this pass; run: ukit install',
+      }) + '\n');
+    } catch {}
     process.exit(0);
     return;
   }
@@ -196,7 +211,7 @@ async function readRunCursor() {
   // bricks a healthy session at this cap. The transcript's own compact_boundary entries
   // are the reliable record of real compactions, so sync before deciding, and persist the
   // reset so it re-arms exactly once per boundary instead of disabling the gate.
-  let state = mod.buildCompactPressureState(rawState, sessionConfig);
+  let state = await mod.buildCompactPressureState(rawState, sessionConfig);
   try {
     const synced = await mod.syncCompactPressureStateWithTranscript(state, sessionConfig, payload.transcript_path);
     if (synced.reset || synced.probed) {
@@ -205,12 +220,12 @@ async function readRunCursor() {
       state = await mod.writeCompactPressureState(projectRoot, synced.state, sessionConfig);
     }
   } catch {
-    state = mod.buildCompactPressureState(rawState, sessionConfig);
+    state = await mod.buildCompactPressureState(rawState, sessionConfig);
   }
   // projectRoot is passed explicitly so the cap is negotiated from THIS project's
   // published capacity record rather than from whatever cwd the host happened to use —
   // the gate is fail-closed, so it must read the same evidence the guard wrote.
-  const thresholds = mod.buildCompactThresholds({ ...config, projectRoot });
+  const thresholds = await mod.buildCompactThresholds({ ...config, projectRoot });
 
   // The grace budget must survive parallel subagents hitting the cap in the same episode.
   // A read-modify-write of one JSON file under-counts (two processes both read used=3 and
@@ -387,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-model-guard.sh

@@ -83,7 +83,16 @@ fi
 
 INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+// SPEC §8: a timed-out gate silently passes work it never evaluated — announce the
+// degrade (fail-open posture kept: still exit 0).
+setTimeout(() => {
+  try {
+    process.stdout.write(JSON.stringify({
+      systemMessage: `UKit handoff-model-guard: evaluation exceeded its ${HOOK_DEADLINE_MS}ms deadline; this tool call proceeded without the model check.`,
+    }) + '\n');
+  } catch {}
+  process.exit(0);
+}, HOOK_DEADLINE_MS).unref();
 const fs = require('fs');
 const fsp = fs.promises;
 const path = require('path');

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

@@ -87,26 +87,29 @@ 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();
-
-let rawInput = '';
-try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
-const payload = (() => {
+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 {
-    const parsed = JSON.parse(rawInput);
-    return parsed && typeof parsed === 'object' ? parsed : {};
-  } catch {
-    return {};
-  }
-})();
+    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');
 const runtimePath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'execution-ledger.mjs');
-const source = typeof payload.source === 'string' ? payload.source : 'startup';
 
-async function emitOrdinaryResume() {
-  if (!fs.existsSync(runtimePath)) return false;
+async function emitOrdinaryResume(payload, source) {
+  let runtimeExists = false;
+  try { await fs.promises.access(runtimePath); runtimeExists = true; } catch {}
+  if (!runtimeExists) return false;
   try {
     const runtime = await import(pathToFileURL(runtimePath).href);
     const intent = await runtime.readResumeIntent(projectRoot, payload, { consume: true });
@@ -130,13 +133,25 @@ async function emitOrdinaryResume() {
 }
 
 (async () => {
+  // Async on purpose — a sync read on a stalled mount would block the watchdog timer.
+  let rawInput = '';
+  try { rawInput = await fs.promises.readFile(process.env.INPUT_FILE || '', 'utf8'); } catch {}
+  const payload = (() => {
+    try {
+      const parsed = JSON.parse(rawInput);
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  })();
+  const source = typeof payload.source === 'string' ? payload.source : 'startup';
+
   let text;
   try {
-    // Async on purpose — a sync read on a stalled mount would block the watchdog timer.
     text = await fs.promises.readFile(runPath, 'utf8');
   } catch {
     // No handoff cursor: an ordinary routed-task intent may still be resumable.
-    await emitOrdinaryResume();
+    await emitOrdinaryResume(payload, source);
     process.exit(0);
   }
 
@@ -146,7 +161,7 @@ async function emitOrdinaryResume() {
   // `done` and `blocked` are both terminal (blocked = closed with instructions, the
   // same posture stop-coordinator.mjs uses). Anything else means a step was in flight.
   if (!phase || /^(done|blocked)\b/i.test(phase)) {
-    await emitOrdinaryResume();
+    await emitOrdinaryResume(payload, source);
     process.exit(0);
   }
 

package/templates/.claude/hooks/post-edit-verify.sh

@@ -62,6 +62,7 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 SCRIPT="$PROJECT_ROOT/.claude/ukit/index/post-edit-verify.mjs"
 
 if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' '{"systemMessage":"UKit post-edit-verify: index script missing — run: ukit install"}'
   exit 0
 fi
 

package/templates/.claude/hooks/pre-edit-backup.sh

@@ -62,6 +62,7 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 SCRIPT="$PROJECT_ROOT/.claude/ukit/index/pre-edit-backup.mjs"
 
 if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' '{"systemMessage":"UKit pre-edit-backup: index script missing — run: ukit install"}'
   exit 0
 fi