@ngockhoale/ukit 2.4.0 → 2.4.2

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

@@ -2,16 +2,37 @@
 # Hook: route prompt/tool signals to the smallest useful installed skill set.
 # Used from UserPromptSubmit and PreToolUse so end users do not need to name skills.
 
-INPUT=$(cat)
+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
+  trap ukit_cleanup_hook_input EXIT
+  # Bounded stdin (H01): stage before anything reads it; the shell var is capped,
+  # env passes only the staged-file path — never the payload.
+  ukit_stage_hook_input 2097152 truncate || exit 0
+else
+  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
+  # wrapper's own fail-loud/advisory behavior below alive.
+  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
+    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
+INPUT="$(cat "$UKIT_INPUT_FILE")"
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 
 # Internal orchestration envelopes are not user requests. Ignore them before routing or
 # compact-pressure bookkeeping so task results cannot replace the active completion contract.
 case "$INPUT" in
   *"<task-notification"*|*"<tool-result"*|*"<system-reminder"*|*"<local-command-caveat"*)
-    INTERNAL_ORCHESTRATION=$(INPUT="$INPUT" node -e '
+    INTERNAL_ORCHESTRATION=$(INPUT_FILE="$UKIT_INPUT_FILE" node -e '
+// wall-clock watchdog: never let a wedged parse outlive the hook (same arm as the router heredoc below)
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 try {
-  const payload = JSON.parse(process.env.INPUT || "{}");
+  const payload = JSON.parse(require("fs").readFileSync(process.env.INPUT_FILE || "", "utf8") || "{}");
   const candidates = [payload?.prompt, payload?.user_prompt, payload?.text, payload?.message, payload?.input]
     .filter((value) => typeof value === "string")
     .map((value) => value.trim());
@@ -44,6 +65,9 @@ esac
 case "$INPUT" in
   *".worktrees/"*)
     if printf '%s' "$INPUT" | node -e '
+// wall-clock watchdog: never let a wedged stdin read outlive the hook (same arm as the router heredoc below)
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const chunks = [];
 process.stdin.on("data", (c) => chunks.push(c));
 process.stdin.on("end", () => {
@@ -79,6 +103,9 @@ THRESHOLD_SCRIPT="$HOOK_DIR/../ukit/runtime/compact-threshold.mjs"
 case "$INPUT" in
   *'"agent_id"'*|*'"agent_type"'*)
     if printf '%s' "$INPUT" | node -e '
+// wall-clock watchdog: never let a wedged stdin read outlive the hook (same arm as the router heredoc below)
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const chunks = [];
 process.stdin.on("data", (c) => chunks.push(c));
 process.stdin.on("end", () => {
@@ -96,12 +123,23 @@ process.stdin.on("end", () => {
     ;;
 esac
 
-INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" STATE_FILE="$STATE_FILE" HOOK_DIR="$HOOK_DIR" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" STATE_FILE="$STATE_FILE" HOOK_DIR="$HOOK_DIR" node <<'NODE'
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { pathToFileURL } = require('url');
 
+// Wall-clock watchdog. This hook runs on the UserPromptSubmit/PreToolUse hot path but has
+// no host-side process-group kill: when indexed-context resolution hangs (a wedged import,
+// a stalled mount), the host kills only THIS bash wrapper, the node grandchild below is
+// reparented to launchd, and it spins forever. Verified: exactly one orphan leaked per run
+// of the router timeout test, 200+ accumulated over days. Self-exit at the deadline so a
+// hang can never outlive the hook. Advisory only — an early exit just drops the routing
+// hint, the same posture as a cache miss. Same watchdog task-watchdog.sh/handoff-resume.sh
+// already carry; keep this one aligned with them.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
 (async () => {
   const STOPWORDS = new Set([
     'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',
@@ -2555,7 +2593,8 @@ const { pathToFileURL } = require('url');
     return compactState;
   }
 
-  const rawInput = process.env.INPUT || '';
+  let rawInput = '';
+  try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
   const projectRoot = process.env.PROJECT_ROOT || process.cwd();
   const statePath = process.env.STATE_FILE || path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json');
   const routeCachePath = path.join(projectRoot, '.claude', 'ukit', 'route-cache.json');

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

@@ -2,7 +2,24 @@
 # PreToolUse hook: prevent stale/ambiguous risky Edit specs and whole-file risky Write.
 # Matched on: Edit|Write
 
-INPUT=$(cat)
+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
+  trap ukit_cleanup_hook_input EXIT
+  # Bounded stdin (H01): stage before anything reads it; the shell var is capped.
+  ukit_stage_hook_input 2097152 truncate || exit 0
+else
+  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
+  # wrapper's own fail-loud/advisory behavior below alive.
+  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
+    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
+INPUT="$(cat "$UKIT_INPUT_FILE")"
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 SCRIPT="$PROJECT_ROOT/.claude/ukit/index/stale-spec-check.mjs"
 
@@ -21,6 +38,8 @@ fi
 case "$INPUT" in
   *".worktrees/"*)
     if printf '%s' "$INPUT" | node -e '
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const chunks = [];
 process.stdin.on("data", (c) => chunks.push(c));
 process.stdin.on("end", () => {
@@ -42,4 +61,4 @@ process.stdin.on("end", () => {
     ;;
 esac
 
-printf '%s' "$INPUT" | node "$SCRIPT"
+printf '%s' "$INPUT" | UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT"

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

@@ -29,14 +29,30 @@
 #   PostToolUse  → advisory only (systemMessage); NEVER emits decision.
 #   anything else → exit 0 silently.
 
-INPUT="$(cat)"
-# Cap the payload before it reaches node's env: oversized stdin would exceed the
-# exec environment limit and node would never start. A truncated payload simply
-# fails JSON.parse inside node → {} → silent degrade exit 0 (documented posture).
-INPUT="${INPUT:0:65536}"
+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
+  trap ukit_cleanup_hook_input EXIT
+  # Bounded stdin (H01): the 64 KiB cap is preserved, but the payload now travels
+  # as a staged file path — never through the exec environment, so an oversized
+  # input can no longer stop node from starting (E2BIG) or stall the wrapper in
+  # `cat`. A truncated payload simply fails JSON.parse inside node → {} → silent
+  # degrade exit 0 (documented posture).
+  ukit_stage_hook_input 65536 truncate || exit 0
+else
+  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
+  # 64 KiB cap and the advisory degrade path alive.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  head -c 65537 > "$UKIT_INPUT_FILE" 2>/dev/null
+  cat >/dev/null 2>&1
+  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 65536 ]; then
+    truncate -s 65536 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 
-INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
 'use strict';
 
 const fsp = require('fs/promises');
@@ -50,10 +66,12 @@ 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 {}
 (async () => {
   const payload = (() => {
     try {
-      const parsed = JSON.parse(process.env.INPUT || '');
+      const parsed = JSON.parse(rawInput);
       return parsed && typeof parsed === 'object' ? parsed : {};
     } catch {
       return {};

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

@@ -2,13 +2,31 @@
 # PreToolUse hook: enforce routed verification execution policy so AI stays index-first
 # and does not jump to blanket verification when targeted evidence already exists.
 
-INPUT=$(cat)
+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
+  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.
+  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
+    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 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="$INPUT" 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" node <<'NODE'
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
@@ -35,11 +53,12 @@ function writeJsonAtomic(filePath, value) {
   }
 }
 
-// Sync sleep without burning CPU — the hook's flow calls process.exit right after
-// persistAttempt, so the critical section must complete synchronously.
-function sleepSync(ms) {
-  const buffer = new SharedArrayBuffer(4);
-  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+// 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) {
@@ -59,10 +78,12 @@ function readLockOwner(lockPath) {
     : null;
 }
 
-// mkdir-based lock, protocol-compatible with runtime token-utils withFileLock. Sync on
-// purpose (see sleepSync). Fail-open after 5s: this hook must never hang a PreToolUse
-// chain, and a lost progress entry only costs one repeated advisory.
-function withLockSync(lockPath, fn) {
+// 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();
@@ -100,11 +121,11 @@ function withLockSync(lockPath, fn) {
         }
       } catch {}
       if (Date.now() - startedAt > maxWaitMs) break;
-      sleepSync(3 + Math.floor(Math.random() * 9));
+      await sleep(3 + Math.floor(Math.random() * 9));
     }
   }
   try {
-    return fn();
+    return await fn();
   } finally {
     if (held) {
       const owner = readLockOwner(lockPath);
@@ -334,9 +355,15 @@ function advise(message) {
   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.
+(async () => {
+let rawInput = '';
+try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
 const payload = (() => {
   try {
-    return JSON.parse(process.env.INPUT || '{}');
+    return JSON.parse(rawInput || '{}');
   } catch {
     return {};
   }
@@ -402,14 +429,14 @@ const attemptedCommands = collectAttemptedCommands(progress, {
   maxAgeMs: STATE_FRESH_MS,
 });
 
-function persistAttempt(commandText) {
+async function persistAttempt(commandText) {
   const normalizedCommandText = normalizeCommand(commandText);
   attemptedCommands.add(normalizedCommandText);
   const now = Date.now();
   // 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.
-  withLockSync(`${progressPath}.lock`, () => {
+  await withLock(`${progressPath}.lock`, async () => {
     const current = readJson(progressPath, {});
     const mergedAttempts = new Set(collectAttemptedCommands(current, {
       currentFingerprint: state?.fingerprint || null,
@@ -463,7 +490,7 @@ const preferredText = formatCompactCommandList(preferredOrder, { separator: ' ->
 const missingPrimaryText = formatCompactCommandList(missingPrimary);
 
 if (isTargetedVerification) {
-  persistAttempt(command);
+  await persistAttempt(command);
   process.exit(0);
 }
 
@@ -498,15 +525,23 @@ if (policyMode === 'docs-light' && !explicitBroadRequested && isBroadTestCommand
 }
 
 if (isPrimaryCommand) {
-  persistAttempt(command);
+  await persistAttempt(command);
   process.exit(0);
 }
 
 if (isFallbackCommand || isVerificationCommand(command)) {
-  persistAttempt(command);
+  await persistAttempt(command);
 }
 
 process.exit(0);
+})().catch((err) => {
+  // 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`);
+  } catch {}
+  process.exit(0);
+});
 NODE
 
 exit $?

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

@@ -19,19 +19,52 @@
 # every unrelated prompt is the false-positive loop this version exists to kill.
 # A named path that does not resolve from the project root gets a short note only.
 
-INPUT=$(cat)
+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
+  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.
+  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
+    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 
-INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
+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 path = require('path');
-const { execFileSync } = require('child_process');
+const { spawn } = require('child_process');
 const { pathToFileURL } = require('url');
 
+// TASK-015: a self-deadline can only preempt work that yields to the event
+// loop. The extractor is spawned asynchronously with an abort timer armed
+// strictly BEFORE HOOK_DEADLINE_MS (so the deadline always wins), killed with
+// SIGKILL (no child can ignore it), and every live child is reaped on process
+// exit as a backstop. The old synchronous spawn blocked the loop and made the
+// unref'd watchdog above un-fireable — banned on this hot path.
+const liveChildren = new Set();
+process.on('exit', () => {
+  for (const child of liveChildren) {
+    try { child.kill('SIGKILL'); } catch {}
+  }
+});
+
+let rawInput = '';
+try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
 (async () => {
   const payload = (() => {
     try {
-      const parsed = JSON.parse(process.env.INPUT || '');
+      const parsed = JSON.parse(rawInput);
       return parsed && typeof parsed === 'object' ? parsed : {};
     } catch {
       return {};
@@ -70,8 +103,9 @@ const { pathToFileURL } = require('url');
   // whose receipt could never be accepted. Only a POSITIVE false short-circuits; null
   // (detection failed) still routes, matching the gate's fail-safe direction.
   //
-  // Cheaper than the old order, too: this replaces an execFileSync node spawn per prompt
-  // with one local import on the overwhelmingly common off-gateway path.
+  // Cheaper than the old order, too: this replaces a synchronous node spawn
+  // per prompt with one local import on the overwhelmingly common off-gateway
+  // path.
   if (unicMode === false) {
     process.exit(0);
   }
@@ -142,6 +176,56 @@ const { pathToFileURL } = require('url');
     return noSoft !== value ? noSoft : value;
   }
 
+  // TASK-015: async spawn, one settle path per child. The abort timer fires
+  // strictly before the hook deadline (min floor keeps it meaningful if the
+  // deadline is configured tiny) and is unref'd so it never holds the loop
+  // open by itself. Stdout capture is bounded; stream/child errors are absorbed
+  // so an abort racing a child exit settles exactly once with no unhandled
+  // rejection. Any failure degrades to a bounded diagnostic + advisory flow.
+  function runExtractorAsync(args) {
+    return new Promise((resolve, reject) => {
+      let child;
+      try {
+        child = spawn('node', args, { cwd: projectRoot, stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (err) {
+        reject(err);
+        return;
+      }
+      liveChildren.add(child);
+      let stdout = '';
+      let settled = false;
+      let abortTimer = null;
+      const settle = (err, text) => {
+        if (settled) return;
+        settled = true;
+        if (abortTimer) clearTimeout(abortTimer);
+        liveChildren.delete(child);
+        if (err) reject(err);
+        else resolve(text);
+      };
+      abortTimer = setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch {}
+        settle(new Error(`extractor killed at ${HOOK_DEADLINE_MS}ms hook deadline`));
+      }, Math.max(250, HOOK_DEADLINE_MS - 500));
+      abortTimer.unref();
+      child.stdout.on('error', () => {});
+      child.stderr.on('error', () => {});
+      child.stdout.on('data', (chunk) => {
+        if (stdout.length < 1000000) stdout += chunk; // bounded capture
+      });
+      child.on('error', (err) => settle(err));
+      child.on('close', (code) => {
+        if (code === 0) {
+          settle(null, stdout);
+        } else {
+          settle(new Error(code === null
+            ? 'extractor was killed before exiting'
+            : `extractor exited with code ${code}`));
+        }
+      });
+    });
+  }
+
   const urlMatches = promptText.match(URL_IMAGE_RE) || [];
   const textWithoutUrls = promptText.replace(URL_IMAGE_RE, ' ');
   const localMatches = textWithoutUrls.match(LOCAL_PATH_RE) || [];
@@ -166,15 +250,15 @@ const { pathToFileURL } = require('url');
       // handing off so the hook and the extractor agree on the ref string.
       args.push('--ref', stripPathNoise(ref));
     }
+    let out = null;
     try {
-      const out = execFileSync('node', args, {
-        cwd: projectRoot,
-        encoding: 'utf8',
-        timeout: 6000,
-      });
+      out = await runExtractorAsync(args);
       extractorJson = JSON.parse(out);
     } catch (err) {
-      process.stderr.write(`vision-router: extractor call skipped (${err?.message ?? err})\n`);
+      // Bounded diagnostic: the head of whatever the extractor emitted (if
+      // 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`);
     }
   }
 

package/templates/.claude/ukit/index/lib/index-core.mjs

@@ -118,7 +118,11 @@ const VIETNAMESE_TOKEN_ALIASES = new Map([
 
 // ── Build Index ──
 
-export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
+// Bumped only when the snapshot shape itself changes; consumers must reject
+// snapshots from a different version instead of trusting unknown fields.
+export const DISCOVERY_SNAPSHOT_VERSION = 1;
+
+export async function buildCodeIndex({ rootDir = process.cwd(), discoverySnapshot = null } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const indexDir = getIndexDir(absoluteRoot);
 
@@ -132,7 +136,13 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
     previousCodeFileRecords.map((item) => [item.filePath, { mtimeMs: Number(item.mtimeMs ?? -1), size: Number(item.size ?? -1) }]),
   );
 
-  const discoveredFiles = await discoverProjectFiles(absoluteRoot);
+  // Reuse the caller's discovery snapshot when it describes exactly this root
+  // under the current schema and snapshot version; anything else (foreign root,
+  // stale schema, wrong shape) is rejected and the repository is rediscovered
+  // once here. Keeps a stale-check + rebuild refresh at a single enumeration.
+  const discoveredFiles = isDiscoverySnapshotUsable(discoverySnapshot, absoluteRoot)
+    ? discoverySnapshot.files
+    : await discoverProjectFiles(absoluteRoot);
   const sourceFingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
   const styleFilePaths = discoveredFiles
     .map((entry) => {
@@ -2940,6 +2950,27 @@ async function discoverProjectFiles(rootDir) {
   return collectFiles([rootDir]);
 }
 
+function createDiscoverySnapshot(rootDir, files, fingerprint) {
+  // Frozen: the snapshot must stay byte-stable between the staleness inspection
+  // and the build that consumes it, and callers must not mutate shared state.
+  return Object.freeze({
+    snapshotVersion: DISCOVERY_SNAPSHOT_VERSION,
+    schemaVersion: INDEX_SCHEMA_VERSION,
+    rootDir,
+    fingerprint,
+    files: Object.freeze(files.slice()),
+  });
+}
+
+function isDiscoverySnapshotUsable(discoverySnapshot, absoluteRoot) {
+  return Boolean(discoverySnapshot)
+    && discoverySnapshot.snapshotVersion === DISCOVERY_SNAPSHOT_VERSION
+    && discoverySnapshot.schemaVersion === INDEX_SCHEMA_VERSION
+    && typeof discoverySnapshot.rootDir === 'string'
+    && path.resolve(discoverySnapshot.rootDir) === absoluteRoot
+    && Array.isArray(discoverySnapshot.files);
+}
+
 function runGit(rootDir, args) {
   const result = spawnSync('git', args, {
     cwd: rootDir,
@@ -3406,24 +3437,55 @@ export async function getIndexArtifactGeneratedAt({
   return parseArtifactGeneratedAt(artifact);
 }
 
+async function evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot }) {
+  const absoluteRoot = path.resolve(rootDir);
+  const metaArtifact = await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.meta);
+  const effectiveGeneratedAtMs = Number.isFinite(generatedAtMs)
+    ? generatedAtMs
+    : parseArtifactGeneratedAt(metaArtifact);
+
+  const staleWithoutEnumeration = effectiveGeneratedAtMs === null
+    || typeof maxAgeMs !== 'number'
+    || Number.isNaN(maxAgeMs)
+    || maxAgeMs < 0
+    || (now - effectiveGeneratedAtMs) >= maxAgeMs
+    || !metaArtifact?.sourceFingerprint;
+
+  // Legacy boolean callers (query-index, triage, verify-context) stop here and
+  // let buildCodeIndex do its own discovery when a rebuild is needed.
+  if (staleWithoutEnumeration && !enumerateForSnapshot) {
+    return { stale: true, snapshot: null };
+  }
+
+  // Exactly one enumeration per inspection. In the refresh flow this snapshot is
+  // handed to buildCodeIndex, so stale-check + rebuild enumerates the repository
+  // once instead of twice.
+  const discoveredFiles = await discoverProjectFiles(absoluteRoot);
+  const fingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
+
+  return {
+    stale: staleWithoutEnumeration
+      ? true
+      : !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, fingerprint),
+    snapshot: createDiscoverySnapshot(absoluteRoot, discoveredFiles, fingerprint),
+  };
+}
+
+export async function inspectIndexStaleness({
+  rootDir = process.cwd(),
+  maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  now = Date.now(),
+  generatedAtMs = null,
+} = {}) {
+  return evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot: true });
+}
+
 export async function isIndexStale({
   rootDir = process.cwd(),
   maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
   now = Date.now(),
   generatedAtMs = null,
 } = {}) {
-  const absoluteRoot = path.resolve(rootDir);
-  const metaArtifact = await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.meta);
-  const effectiveGeneratedAtMs = Number.isFinite(generatedAtMs)
-    ? generatedAtMs
-    : parseArtifactGeneratedAt(metaArtifact);
-  if (effectiveGeneratedAtMs === null) return true;
-  if (typeof maxAgeMs !== 'number' || Number.isNaN(maxAgeMs) || maxAgeMs < 0) return true;
-  if ((now - effectiveGeneratedAtMs) >= maxAgeMs) return true;
-  if (!metaArtifact?.sourceFingerprint) return true;
-  const currentSourceFingerprint = createSourceFingerprint(
-    absoluteRoot,
-    await discoverProjectFiles(absoluteRoot),
-  );
-  return !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, currentSourceFingerprint);
+  const { stale } = await evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot: false });
+  return stale;
 }

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

@@ -4,6 +4,14 @@ import { fileURLToPath } from 'node:url';
 import { analyzeTextBuffer, analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
 import { classifySafePatchRisk, isSafePatchAdvisoryOnly, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
 
+// 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.
+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();
+}
+
 async function readStdin() {
   return await new Promise((resolve) => {
     let raw = '';

package/templates/.claude/ukit/index/pre-edit-backup.mjs

@@ -4,6 +4,14 @@ import { analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs'
 import { classifySafePatchRisk, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
 import { fileURLToPath } from 'node:url';
 
+// Hook-context self-deadline (2.4.1 orphan-leak class): the pre-edit-backup 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.
+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();
+}
+
 async function readStdin() {
   return await new Promise((resolve) => {
     let raw = '';