@ngockhoale/ukit 2.4.2 → 2.5.0

package/templates/.claude/hooks/verification-guard.sh

@@ -5,16 +5,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; Node gets a path, never the payload.
   ukit_stage_hook_input 2097152 truncate || exit 0
 else
-  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
-  # advisory/fail-open behavior below alive with a capped payload file.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
@@ -24,30 +50,34 @@ STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
 ROUTE_CACHE_FILE="$PROJECT_ROOT/.claude/ukit/route-cache.json"
 PROGRESS_FILE="$PROJECT_ROOT/.claude/ukit/verification-progress.json"
 
-INPUT_FILE="$UKIT_INPUT_FILE" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" UKIT_RUNTIME_DIR="$SCRIPT_DIR/../ukit/runtime" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+const LOCK_STARTED_AT = Date.now();
 setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-const crypto = require('crypto');
-const fs = require('fs');
+// TASK-015 fix round 1: the awaitable fs surface. Every state/progress read and
+// the atomic progress mutation is awaited so the unref'd self-deadline above can
+// always preempt it; synchronous fs calls park the event loop instead.
+const fs = require('fs').promises;
 const path = require('path');
+const { pathToFileURL } = require('url');
 
-function readJson(filePath, fallback = null) {
+async function readJson(filePath, fallback = null) {
   try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
   } catch {
     return fallback;
   }
 }
 
-function writeJsonAtomic(filePath, value) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+async function writeJsonAtomic(filePath, value) {
+  await fs.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 fs.writeFile(tempPath, JSON.stringify(value, null, 2) + '\n');
+    await fs.rename(tempPath, filePath);
   } catch (error) {
     try {
-      fs.rmSync(tempPath, { force: true });
+      await fs.rm(tempPath, { force: true });
     } catch {}
     throw error;
   }
@@ -56,86 +86,26 @@ function writeJsonAtomic(filePath, value) {
 // TASK-015: lock waits poll asynchronously. The old blocking shared-memory
 // sleep froze the event loop, so the unref'd deadline timer above could never
 // fire while waiting — a contended lock held the hook past its own 3s
-// self-deadline. setTimeout-based sleeps keep the loop live.
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function isPidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error?.code === 'EPERM';
-  }
-}
-
-function readLockOwner(lockPath) {
-  const owner = readJson(path.join(lockPath, 'owner'), null);
-  return owner && Number.isInteger(owner.pid) && typeof owner.token === 'string'
-    ? owner
-    : null;
-}
-
-// mkdir-based lock, protocol-compatible with runtime token-utils withFileLock.
-// Async now (see sleep above): the single-syscall mkdir/stat/write critical
-// section stays synchronous, only the contention backoff awaits. Fail-open
-// after 5s: this hook must never hang a PreToolUse chain, and a lost progress
-// entry only costs one repeated advisory.
-async function withLock(lockPath, fn) {
-  const staleMs = 10000;
-  const maxWaitMs = 5000;
-  const startedAt = Date.now();
-  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
-  let held = false;
-  while (!held) {
-    try {
-      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-      fs.mkdirSync(lockPath);
+// self-deadline. TASK-028: the lock itself is the shared runtime async-lock
+// utility (same mkdir/owner protocol as token-utils withFileLock, jittered
+// async backoff, no blocking shared-memory wait), so this hook carries no
+// inline lock copy.
+let lockModulePromise = null;
+function loadLockModule() {
+  if (!lockModulePromise) {
+    lockModulePromise = (async () => {
+      const runtimeDir = process.env.UKIT_RUNTIME_DIR || '';
+      const modulePath = runtimeDir ? path.join(runtimeDir, 'async-lock.mjs') : '';
+      if (!modulePath) return null;
       try {
-        fs.writeFileSync(path.join(lockPath, 'owner'), JSON.stringify({
-          pid: process.pid,
-          token: ownerToken,
-          ts: Date.now(),
-        }));
-      } catch (error) {
-        try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
-        } catch {}
-        throw error;
+        await fs.access(modulePath);
+        return await import(pathToFileURL(modulePath).href);
+      } catch {
+        return null;
       }
-      held = true;
-    } catch (error) {
-      if (!error || error.code !== 'EEXIST') return fn();
-      try {
-        const stat = fs.statSync(lockPath);
-        if (Date.now() - stat.mtimeMs > staleMs) {
-          const owner = readLockOwner(lockPath);
-          if (!owner || !isPidAlive(owner.pid)) {
-            try {
-              fs.rmSync(lockPath, { recursive: true, force: true });
-              continue;
-            } catch {}
-          }
-        }
-      } catch {}
-      if (Date.now() - startedAt > maxWaitMs) break;
-      await sleep(3 + Math.floor(Math.random() * 9));
-    }
-  }
-  try {
-    return await fn();
-  } finally {
-    if (held) {
-      const owner = readLockOwner(lockPath);
-      if (owner?.token === ownerToken) {
-        try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
-        } catch {}
-      }
-    }
+    })();
   }
+  return lockModulePromise;
 }
 
 function normalizeCommand(value) {
@@ -351,23 +321,30 @@ function advise(message) {
   // ledger, context hard-cap, protected-file, and destructive-command guards; turning
   // a verification-order recommendation into an exit-2 refusal gave a stale opt-in env
   // variable a way to freeze a run before it could diagnose or land its current change.
-  fs.writeSync(1, `${message.replace(/^BLOCKED:/, 'ADVISORY:')}\n`);
+  process.stdout.write(`${message.replace(/^BLOCKED:/, 'ADVISORY:')}\n`);
   process.exit(0);
 }
 
-// TASK-015: the whole flow runs in an async IIFE so the lock acquire can be
-// awaited (async polling) before the policy checks; every path still ends in
-// exit 0 — this hook is advisory by design.
+// TASK-015 fix round 1: the whole flow runs in an async IIFE and every
+// deadline-scoped filesystem operation yields to the event loop. Synchronous
+// reads/writes park the loop and make the self-deadline un-fireable.
 (async () => {
-let rawInput = '';
-try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
-const payload = (() => {
-  try {
-    return JSON.parse(rawInput || '{}');
-  } catch {
-    return {};
+  const rawInput = await readTextSafe(process.env.INPUT_FILE || '');
+  const payload = (() => {
+    try {
+      return JSON.parse(rawInput || '{}');
+    } catch {
+      return {};
+    }
+  })();
+
+  async function readTextSafe(filePath) {
+    try {
+      return await fs.readFile(filePath, 'utf8');
+    } catch {
+      return '';
+    }
   }
-})();
 const command = normalizeCommand(payload?.tool_input?.command || payload?.command || '');
 if (!command) {
   process.exit(0);
@@ -375,8 +352,8 @@ if (!command) {
 
 const statePath = process.env.STATE_FILE;
 const progressPath = process.env.PROGRESS_FILE;
-const state = readJson(statePath, null);
-const routeCache = readJson(process.env.ROUTE_CACHE_FILE, null);
+const state = await readJson(statePath, null);
+const routeCache = await readJson(process.env.ROUTE_CACHE_FILE, null);
 const recommendation = state?.verificationRecommendation ?? null;
 const routeSummary = state?.routeSummary ?? null;
 const helpers = state?.helpers ?? null;
@@ -423,7 +400,7 @@ if (!policyMode && primaryCommands.length === 0 && fallbackCommands.length === 0
   process.exit(0);
 }
 
-const progress = readJson(progressPath, {});
+const progress = await readJson(progressPath, {});
 const attemptedCommands = collectAttemptedCommands(progress, {
   currentFingerprint: state?.fingerprint || null,
   maxAgeMs: STATE_FRESH_MS,
@@ -436,8 +413,8 @@ async function persistAttempt(commandText) {
   // Locked re-read + merge: parallel subagents record attempts concurrently, and a
   // stale-snapshot rewrite would silently drop their entries — the guard would then keep
   // advising instead of allowing, re-litigating verification order forever.
-  await withLock(`${progressPath}.lock`, async () => {
-    const current = readJson(progressPath, {});
+  const mutation = async () => {
+    const current = await readJson(progressPath, {});
     const mergedAttempts = new Set(collectAttemptedCommands(current, {
       currentFingerprint: state?.fingerprint || null,
       maxAgeMs: STATE_FRESH_MS,
@@ -457,13 +434,31 @@ async function persistAttempt(commandText) {
       .filter((entry, index, list) => (
         list.findLastIndex((candidate) => candidate.command === entry.command) === index
       ));
-    writeJsonAtomic(progressPath, {
+    await writeJsonAtomic(progressPath, {
       fingerprint: state?.fingerprint || null,
       updatedAt: now,
       attemptedCommands: [...mergedAttempts],
       recentAttempts,
     });
-  });
+  };
+  const lockModule = await loadLockModule();
+  if (lockModule && typeof lockModule.withAsyncLock === 'function') {
+    // TASK-028: the acquisition budget derives from the remaining hook deadline minus
+    // a cleanup reserve, capped at a short slice — a contended lock can never hold
+    // this hook near its own 3s deadline. On busy/abort the persist is SKIPPED, not
+    // written unlocked: the progress file is advisory and the next uncontended run
+    // re-records the attempt.
+    const deadlineMs = lockModule.lockBudgetMs({
+      hookDeadlineMs: HOOK_DEADLINE_MS,
+      startedAt: LOCK_STARTED_AT,
+    });
+    const outcome = await lockModule.withAsyncLock(progressPath, { deadlineMs }, mutation);
+    if (!outcome.ok) return;
+    return;
+  }
+  // Degraded install (runtime module missing): advisory progress file — keep the
+  // pre-utility unlocked persist so the advisory lane stays lively.
+  await mutation();
 }
 
 const isPrimaryCommand = primaryCommands.includes(command);
@@ -538,7 +533,7 @@ process.exit(0);
   // Advisory hook: an unexpected error (including a rejected lock) must never
   // turn into a non-zero exit — degrade to a bounded diagnostic and exit 0.
   try {
-    fs.writeSync(2, `verification-guard: unexpected error (${err?.message ?? err})\n`);
+    process.stderr.write(`verification-guard: unexpected error (${err?.message ?? err})\n`);
   } catch {}
   process.exit(0);
 });

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

@@ -22,16 +22,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; Node gets a path, never the payload.
   ukit_stage_hook_input 2097152 truncate || exit 0
 else
-  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
-  # advisory/fail-open behavior below alive with a capped payload file.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
@@ -41,7 +67,7 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 8000;
 setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-const fs = require('fs');
+const fs = require('fs').promises;
 const path = require('path');
 const { spawn } = require('child_process');
 const { pathToFileURL } = require('url');
@@ -59,9 +85,15 @@ process.on('exit', () => {
   }
 });
 
-let rawInput = '';
-try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
+// TASK-015 fix round 1: every hot-path fs call is awaited. A synchronous read
+// parks the event loop for the whole syscall, so the unref'd self-deadline above
+// could never fire while a project filesystem stalled.
+async function readTextSafe(filePath) {
+  try { return await fs.readFile(filePath, 'utf8'); } catch { return ''; }
+}
+
 (async () => {
+  const rawInput = await readTextSafe(process.env.INPUT_FILE || '');
   const payload = (() => {
     try {
       const parsed = JSON.parse(rawInput);
@@ -86,7 +118,7 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
   async function detectUnicModeSafe() {
     try {
       const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
-      if (!fs.existsSync(gatewayPath)) return null;
+      try { await fs.access(gatewayPath); } catch { return null; }
       const mod = await import(pathToFileURL(gatewayPath).href);
       if (typeof mod.detectUnicGateway !== 'function') return null;
       return !!mod.detectUnicGateway({ rootDir: projectRoot })?.unicMode;
@@ -135,7 +167,7 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
   // pair) and silently skips it. Kept here as a small inline copy rather than
   // a cross-file import — the contract is a few lines, the cost of drift is
   // small, and the hook must stay self-contained (no module resolution).
-  function stripPathNoise(raw) {
+  async function stripPathNoise(raw) {
     const value = String(raw ?? '').trim();
     if (!value) return value;
     const pairs = { '(': ')', '[': ']', '{': '}', '"': '"', "'": "'" };
@@ -168,7 +200,8 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
     for (const c of candidates) {
       if (!c) continue;
       try {
-        if (fs.existsSync(path.resolve(c))) return c;
+        await fs.access(path.resolve(c));
+        return c;
       } catch {
         // ignore
       }
@@ -236,7 +269,8 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
   // string inside the extractor.
   let extractorJson = null;
   const extractorPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'extract-image.mjs');
-  if (fs.existsSync(extractorPath)) {
+  try {
+    await fs.access(extractorPath);
     const args = [extractorPath, '--detect', '--mark-pending', '--json'];
     if (typeof payload?.transcript_path === 'string' && payload.transcript_path.trim()) {
       args.push('--session', payload.transcript_path.trim());
@@ -248,7 +282,7 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
       // Mirror extractor's resolveRefs input contract: the LLM sometimes leaves
       // trailing punctuation/quotes on a path named in a prompt. Clean before
       // handing off so the hook and the extractor agree on the ref string.
-      args.push('--ref', stripPathNoise(ref));
+      args.push('--ref', await stripPathNoise(ref));
     }
     let out = null;
     try {
@@ -260,6 +294,8 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
       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`);
     }
+  } catch {
+    // Missing extractor is a normal fail-open condition.
   }
 
   // TASK-006 contract: in --mark-pending --json mode `images[]` is the

package/templates/.claude/settings.json

@@ -208,11 +208,6 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\"",
             "timeout": 4
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\"",
-            "timeout": 4
           }
         ]
       }
@@ -231,6 +226,11 @@
     "SessionStart": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\"",
+            "timeout": 8
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\"",