@ngockhoale/ukit 2.6.2 → 2.6.4

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,30 @@ 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");
 }
 
 // Same lock point as auto-allow-bash.sh (<usage>.lock): the two hooks serialize their
@@ -70,8 +85,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 +100,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 +118,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 +137,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 +148,8 @@ async function withLock(lockPath, fn) {
 }
 
 withLock(`${usagePath}.lock`, async () => {
-  const settings = readJson(settingsPath);
-  const usage = readJson(usagePath);
+  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 +170,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

@@ -82,13 +82,34 @@ OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="
 STATUS=$?
 
 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

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

@@ -89,24 +89,14 @@ const { pathToFileURL } = require('url');
 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 = (() => {
-  try {
-    const parsed = JSON.parse(rawInput);
-    return parsed && typeof parsed === 'object' ? parsed : {};
-  } catch {
-    return {};
-  }
-})();
-
 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 +120,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 +148,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
 

package/templates/.claude/hooks/reset-compact-pressure.sh

@@ -29,9 +29,23 @@ 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: this hook is the documented escape hatch for a stuck compact gate, so a
+// failure must be announced — a silent failure leaves the gate bricked with no hint.
+function emitDegrade(reason) {
+  try {
+    process.stdout.write(JSON.stringify({
+      systemMessage: `UKit reset-compact-pressure: ${reason}`,
+    }) + "\n");
+  } catch {}
+}
+
+setTimeout(() => {
+  emitDegrade("reset exceeded its deadline; the compact-pressure record may still be stale — restarting the session retries the reset.");
+  process.exit(0);
+}, HOOK_DEADLINE_MS).unref();
 const crypto = require("crypto");
-const fs = require("fs");
+const fsp = require("fs").promises;
 const path = require("path");
 
 function isPidAlive(pid) {
@@ -44,9 +58,9 @@ function isPidAlive(pid) {
   }
 }
 
-function readLockOwner(lockPath) {
+async function readLockOwner(lockPath) {
   try {
-    const owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner"), "utf8"));
+    const owner = JSON.parse(await fsp.readFile(path.join(lockPath, "owner"), "utf8"));
     return Number.isInteger(owner?.pid) && typeof owner.token === "string" ? owner : null;
   } catch {
     return null;
@@ -61,16 +75,16 @@ async function withLock(lockPath, fn) {
   let held = false;
   while (!held) {
     try {
-      fs.mkdirSync(lockPath);
+      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;
       }
@@ -78,12 +92,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 {}
           }
@@ -97,10 +111,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 {}
       }
     }
@@ -120,17 +134,17 @@ process.stdin.on("end", () => {
   const sessionId = typeof payload.session_id === "string" ? payload.session_id.trim() : "";
   const pressurePath = process.argv[1];
 
-  withLock(`${pressurePath}.lock`, () => {
-    const raw = (() => {
+  withLock(`${pressurePath}.lock`, async () => {
+    const raw = await (async () => {
       try {
-        return JSON.parse(fs.readFileSync(pressurePath, "utf8"));
+        return JSON.parse(await fsp.readFile(pressurePath, "utf8"));
       } catch {
         return null;
       }
     })();
     if (!raw || typeof raw !== "object") {
       try {
-        fs.rmSync(pressurePath, { force: true });
+        await fsp.rm(pressurePath, { force: true });
       } catch {}
       return;
     }
@@ -139,7 +153,7 @@ process.stdin.on("end", () => {
     // the documented escape hatch for a bricked gate, and it must stay one.
     if (!sessionId || !raw.sessions || typeof raw.sessions !== "object") {
       try {
-        fs.rmSync(pressurePath, { force: true });
+        await fsp.rm(pressurePath, { force: true });
       } catch {}
       return;
     }
@@ -150,7 +164,7 @@ process.stdin.on("end", () => {
       .sort(([, a], [, b]) => (b?.updatedAt ?? 0) - (a?.updatedAt ?? 0))[0]?.[1] ?? null;
     const tempPath = `${pressurePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
     try {
-      fs.writeFileSync(
+      await fsp.writeFile(
         tempPath,
         JSON.stringify({
           ...(newest && typeof newest === "object" ? newest : {}),
@@ -159,15 +173,18 @@ process.stdin.on("end", () => {
           sessions,
         }, null, 2) + "\n",
       );
-      fs.renameSync(tempPath, pressurePath);
+      await fsp.rename(tempPath, pressurePath);
     } catch (error) {
       try {
-        fs.rmSync(tempPath, { force: true });
+        await fsp.rm(tempPath, { force: true });
       } catch {}
       throw error;
     }
-  }).catch(() => {});
+  }).catch((error) => {
+    emitDegrade(`reset failed (${error?.message ?? error}); the compact-pressure record may still be stale — restarting the session retries the reset.`);
+    process.exit(0);
+  });
 });
-' "$PRESSURE_FILE" >/dev/null 2>&1 || true
+' "$PRESSURE_FILE" 2>/dev/null || true
 
 exit 0

package/templates/.claude/hooks/stale-spec-guard.sh

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