@ngockhoale/ukit 2.6.0 → 2.6.3

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

@@ -12,7 +12,15 @@ 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; the shell var is capped,
   # env passes only the staged-file path — never the payload.
-  ukit_stage_hook_input 2097152 truncate || exit 0
+  ukit_stage_hook_input 2097152 truncate
+  __ukit_main_stage_rc=$?
+  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+    # Infra failure during staging (mktemp/truncate): payload was never
+    # inspected — announce the degrade (SPEC §8), never a silent pass.
+    ukit_emit_input_degraded advisory "skill-router"
+  fi
+# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+ukit_input_degraded && ukit_emit_input_degraded advisory "skill-router"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -39,10 +47,14 @@ else
   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
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
+    # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
+    # must be announced, never silently acted on — same shape as the helper
+    # path's ukit_emit_input_degraded.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+    printf '%s\n' '{"systemMessage":"UKit skill-router: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input."}'
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
@@ -57,8 +69,11 @@ case "$INPUT" in
 // 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();
+// BUG-C21-04: the staged read is async — a sync read on a stalled mount parks
+// the event loop and the deadline above could never fire.
+require("fs").promises.readFile(process.env.INPUT_FILE || "", "utf8").then((rawInput) => {
 try {
-  const payload = JSON.parse(require("fs").readFileSync(process.env.INPUT_FILE || "", "utf8") || "{}");
+  const payload = JSON.parse(rawInput || "{}");
   const candidates = [payload?.prompt, payload?.user_prompt, payload?.text, payload?.message, payload?.input]
     .filter((value) => typeof value === "string")
     .map((value) => value.trim());
@@ -73,6 +88,7 @@ try {
 } catch {
   process.stdout.write("0");
 }
+}).catch(() => process.stdout.write("0"));
 ' 2>/dev/null)
     if [ "$INTERNAL_ORCHESTRATION" = "1" ]; then
       exit 0
@@ -92,8 +108,11 @@ 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)
+// BUG-C21-06 class: the deadline must NOT exit 0 — the wrapper reads exit 0 as
+// "worktree match → skip routing", so a stalled pre-check would silently drop
+// the router. Non-zero falls through to the normal hook path below.
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+setTimeout(() => process.exit(1), HOOK_DEADLINE_MS).unref();
 const chunks = [];
 process.stdin.on("data", (c) => chunks.push(c));
 process.stdin.on("end", () => {
@@ -130,8 +149,10 @@ 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)
+// BUG-C21-06 class: deadline exit(0) reads as "subagent → skip routing"; a
+// stalled pre-check must fall through instead. Exit non-zero on expiry.
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+setTimeout(() => process.exit(1), HOOK_DEADLINE_MS).unref();
 const chunks = [];
 process.stdin.on("data", (c) => chunks.push(c));
 process.stdin.on("end", () => {
@@ -173,30 +194,39 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     'cần', 'và', 'là', 'cho', 'một', 'những', 'dùng',
   ]);
 
-  function readJson(filePath, fallback = null) {
+  // BUG-C21-04: every fs call in this deadline-guarded block is async — a sync
+  // read/stat/scan on a stalled mount parks the event loop and the unref'd
+  // deadline above can never fire (orphan node grandchild).
+  const fsp = fs.promises;
+
+  async function pathExists(filePath) {
+    try { await fsp.access(filePath); return true; } catch { return false; }
+  }
+
+  async function readJson(filePath, fallback = null) {
     try {
-      return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      return JSON.parse(await fsp.readFile(filePath, 'utf8'));
     } catch {
       return fallback;
     }
   }
 
-  function ensureDir(filePath) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  async function ensureDir(filePath) {
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
   }
 
-  function writeJsonFileAtomic(filePath, text) {
+  async function writeJsonFileAtomic(filePath, text) {
     // tmp+rename: readers see old-or-new, never a torn/half file. A truncated
     // skill-router-state.json parses as `{}` downstream and completion-gate.sh then
     // releases a premature Stop with no message — the mid-run silent-stop class.
-    ensureDir(filePath);
+    await ensureDir(filePath);
     const tempPath = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
     try {
-      fs.writeFileSync(tempPath, text);
-      fs.renameSync(tempPath, filePath);
+      await fsp.writeFile(tempPath, text);
+      await fsp.rename(tempPath, filePath);
     } catch (error) {
       try {
-        fs.rmSync(tempPath, { force: true });
+        await fsp.rm(tempPath, { force: true });
       } catch {}
       throw error;
     }
@@ -249,14 +279,14 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     };
   }
 
-  function loadRuntimeConfig(projectRoot) {
+  async function loadRuntimeConfig(projectRoot) {
     const runtimePaths = buildRuntimePaths(projectRoot);
-    const raw = readJson(runtimePaths.configPath, {});
+    const raw = await readJson(runtimePaths.configPath, {});
     return deepMerge(defaultRuntimeConfig(), raw && typeof raw === 'object' ? raw : {});
   }
 
-  function readIndexGeneratedAtMs(projectRoot) {
-    const artifact = readJson(path.join(projectRoot, '.cache', 'index', 'files.json'), null);
+  async function readIndexGeneratedAtMs(projectRoot) {
+    const artifact = await readJson(path.join(projectRoot, '.cache', 'index', 'files.json'), null);
     const generatedAtRaw = String(artifact?.generatedAt || '').trim();
     if (!generatedAtRaw) {
       return null;
@@ -268,7 +298,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 
   async function loadRouteCatalog(projectRoot) {
     const routeCatalogPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'route-catalog.mjs');
-    if (!fs.existsSync(routeCatalogPath)) {
+    if (!(await pathExists(routeCatalogPath))) {
       return [];
     }
 
@@ -289,7 +319,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     ].filter(Boolean);
 
     for (const indexCorePath of candidatePaths) {
-      if (!fs.existsSync(indexCorePath)) {
+      if (!(await pathExists(indexCorePath))) {
         continue;
       }
 
@@ -312,8 +342,8 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     };
   }
 
-  function existsSkill(projectRoot, relativePath) {
-    return fs.existsSync(path.join(projectRoot, relativePath));
+  async function existsSkill(projectRoot, relativePath) {
+    return pathExists(path.join(projectRoot, relativePath));
   }
 
   function scoreSkillRouteEntry(entry, routeSignals = {}) {
@@ -793,7 +823,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     };
 
     const indexCorePath = path.join(projectRoot, '.claude', 'ukit', 'index', 'lib', 'index-core.mjs');
-    if (!fs.existsSync(indexCorePath)) {
+    if (!(await pathExists(indexCorePath))) {
       return recommendation;
     }
 
@@ -824,18 +854,18 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     }
   }
 
-  function readProjectPackage(projectRoot) {
+  async function readProjectPackage(projectRoot) {
     return readJson(path.join(projectRoot, 'package.json'), null);
   }
 
-  function readProjectVerificationFingerprint(projectRoot) {
+  async function readProjectVerificationFingerprint(projectRoot) {
     let pkg = null;
     const entries = [];
 
     try {
       const packageJsonPath = path.join(projectRoot, 'package.json');
-      const raw = fs.readFileSync(packageJsonPath, 'utf8');
-      const stat = fs.statSync(packageJsonPath);
+      const raw = await fsp.readFile(packageJsonPath, 'utf8');
+      const stat = await fsp.stat(packageJsonPath);
       pkg = JSON.parse(raw);
       entries.push({
         filePath: 'package.json',
@@ -859,9 +889,9 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
           'bun.lockb',
           'bun.lock',
         ];
-    entries.push(...trackedFiles.map((relativePath) => {
+    entries.push(...(await Promise.all(trackedFiles.map(async (relativePath) => {
       try {
-        const stat = fs.statSync(path.join(projectRoot, relativePath));
+        const stat = await fsp.stat(path.join(projectRoot, relativePath));
         return {
           filePath: relativePath,
           size: stat.size,
@@ -874,7 +904,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
           mtimeMs: null,
         };
       }
-    }));
+    }))));
 
     return {
       pkg,
@@ -894,8 +924,8 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     return null;
   }
 
-  function detectProjectId(projectRoot) {
-    const pkg = readJson(path.join(projectRoot, 'package.json'), null);
+  async function detectProjectId(projectRoot) {
+    const pkg = await readJson(path.join(projectRoot, 'package.json'), null);
     if (typeof pkg?.name === 'string' && pkg.name.trim()) {
       return pkg.name.trim();
     }
@@ -903,10 +933,10 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     return path.basename(projectRoot);
   }
 
-  function readDirectoryJsonItems(dirPath) {
+  async function readDirectoryJsonItems(dirPath) {
     let entries = [];
     try {
-      entries = fs.readdirSync(dirPath, { withFileTypes: true });
+      entries = await fsp.readdir(dirPath, { withFileTypes: true });
     } catch {
       return [];
     }
@@ -918,7 +948,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       }
 
       const fullPath = path.join(dirPath, entry.name);
-      const content = readJson(fullPath, null);
+      const content = await readJson(fullPath, null);
       if (content && typeof content === 'object') {
         items.push({
           fileName: entry.name,
@@ -931,11 +961,11 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     return items.sort((left, right) => left.fileName.localeCompare(right.fileName));
   }
 
-  function listMemoryItems(projectRoot) {
+  async function listMemoryItems(projectRoot) {
     const runtimePaths = buildRuntimePaths(projectRoot);
-    const userMemory = readJson(runtimePaths.userMemoryPath, null) ?? { preferences: {}, rules: [] };
-    const projectMemories = readDirectoryJsonItems(runtimePaths.projectsDir);
-    const sessionMemories = readDirectoryJsonItems(runtimePaths.sessionsDir);
+    const userMemory = (await readJson(runtimePaths.userMemoryPath, null)) ?? { preferences: {}, rules: [] };
+    const projectMemories = await readDirectoryJsonItems(runtimePaths.projectsDir);
+    const sessionMemories = await readDirectoryJsonItems(runtimePaths.sessionsDir);
 
     return [
       {
@@ -1051,7 +1081,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     return `[user] rules: ${rules || 'n/a'}`;
   }
 
-  function buildPreviousContextSnapshot({
+  async function buildPreviousContextSnapshot({
     projectRoot,
     routingContext = {},
     config = defaultRuntimeConfig(),
@@ -1070,8 +1100,8 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       return null;
     }
 
-    const projectId = detectProjectId(projectRoot);
-    const items = listMemoryItems(projectRoot);
+    const projectId = await detectProjectId(projectRoot);
+    const items = await listMemoryItems(projectRoot);
     const queryTokens = tokenizeMemoryText(taskQuery);
     const rankedItems = items
       .filter((item) => item.type !== 'user')
@@ -1113,13 +1143,13 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     };
   }
 
-  function detectPackageManager(projectRoot, pkg) {
+  async function detectPackageManager(projectRoot, pkg) {
     const declared = getDeclaredPackageManager(pkg);
     if (declared) return declared;
 
-    if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
-    if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
-    if (fs.existsSync(path.join(projectRoot, 'bun.lockb')) || fs.existsSync(path.join(projectRoot, 'bun.lock'))) return 'bun';
+    if (await pathExists(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (await pathExists(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
+    if (await pathExists(path.join(projectRoot, 'bun.lockb')) || await pathExists(path.join(projectRoot, 'bun.lock'))) return 'bun';
     return 'npm';
   }
 
@@ -1141,7 +1171,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     return [packageManager, scriptName, ...safeArgs].join(' ');
   }
 
-  function buildVerificationRecommendation({
+  async function buildVerificationRecommendation({
     projectRoot,
     selectedIds,
     contextRecommendation,
@@ -1150,9 +1180,9 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     taskType,
     pkg = null,
   }) {
-    const resolvedPkg = pkg || readProjectPackage(projectRoot) || {};
+    const resolvedPkg = pkg || (await readProjectPackage(projectRoot)) || {};
     const scripts = typeof resolvedPkg.scripts === 'object' && resolvedPkg.scripts ? resolvedPkg.scripts : {};
-    const packageManager = detectPackageManager(projectRoot, resolvedPkg);
+    const packageManager = await detectPackageManager(projectRoot, resolvedPkg);
     const preview = contextRecommendation?.preview || {};
     const relatedTests = [...new Set([
       ...(Array.isArray(preview.relatedTests) ? preview.relatedTests : []),
@@ -2419,8 +2449,8 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     }
   }
 
-  function readLockOwner(lockPath) {
-    const owner = readJson(path.join(lockPath, 'owner'), null);
+  async function readLockOwner(lockPath) {
+    const owner = await readJson(path.join(lockPath, 'owner'), null);
     return owner && Number.isInteger(owner.pid) && typeof owner.token === 'string'
       ? owner
       : null;
@@ -2437,16 +2467,16 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     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;
         }
@@ -2454,12 +2484,12 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       } 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 {}
             }
@@ -2473,10 +2503,10 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       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 {}
         }
       }
@@ -2488,11 +2518,11 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       return;
     }
 
-    await withStateLock(`${filePath}.lock`, () => {
+    await withStateLock(`${filePath}.lock`, async () => {
       let parsed = { entries: [] };
-      if (fs.existsSync(filePath)) {
+      if (await pathExists(filePath)) {
         try {
-          parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+          parsed = JSON.parse(await fsp.readFile(filePath, 'utf8'));
         } catch {
           parsed = { entries: [] };
         }
@@ -2519,7 +2549,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
         return itemKey !== dedupeKey;
       });
 
-      writeJsonFileAtomic(filePath, JSON.stringify({
+      await writeJsonFileAtomic(filePath, JSON.stringify({
         entries: [entry, ...filtered].slice(0, 40),
       }));
     });
@@ -2620,7 +2650,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
   }
 
   let rawInput = '';
-  try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
+  try { rawInput = await fsp.readFile(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');
@@ -2638,7 +2668,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
   const sessionId = sessionCandidate === undefined || sessionCandidate === null
     ? null
     : String(sessionCandidate).trim() || null;
-  const storedPrevious = readJson(statePath, {});
+  const storedPrevious = await readJson(statePath, {});
   // Route state is project-local, while hook ledgers are session-local. Do not let a
   // differently-bound snapshot become the contract for a new session.
   const previous = sessionId
@@ -2646,7 +2676,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       ? storedPrevious
       : {})
     : storedPrevious;
-  const runtimeConfig = loadRuntimeConfig(projectRoot);
+  const runtimeConfig = await loadRuntimeConfig(projectRoot);
 
   const promptText = extractPrompt(payload);
   const commandText = payload.tool_input?.command || payload.command || '';
@@ -2667,10 +2697,18 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 
   const catalog = await loadRouteCatalog(projectRoot);
 
-  const active = catalog
+  const scoredCatalog = catalog
     .map((entry) => scoreSkillRouteEntry(entry, routeSignals))
-    .filter((entry) => entry.score > 0 && existsSkill(projectRoot, entry.path))
-    .filter((entry) => shouldKeepRouteEntryForIntent(entry, intentMode));
+    .filter((entry) => entry.score > 0);
+  const active = [];
+  for (const entry of scoredCatalog) {
+    if (await existsSkill(projectRoot, entry.path)) {
+      active.push(entry);
+    }
+  }
+  const keptActive = active.filter((entry) => shouldKeepRouteEntryForIntent(entry, intentMode));
+  active.length = 0;
+  active.push(...keptActive);
 
   const now = Date.now();
   const debounceMs = 10 * 60 * 1000;
@@ -2723,7 +2761,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       taskType: '',
       ...((informationalNoTargetPrompt || deliveryOnlyNoRoute) ? { executionMode: 'informational' } : {}),
     };
-    const previousContext = buildPreviousContextSnapshot({
+    const previousContext = await buildPreviousContextSnapshot({
       projectRoot,
       routingContext,
       config: runtimeConfig,
@@ -2745,12 +2783,12 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       process.exit(0);
     }
 
-    ensureDir(statePath);
+    await ensureDir(statePath);
     // A no-route prompt (short nudge, informational question) must not wipe the last full
     // route: completion-gate.sh reads routeSummary/requestKey from this state to decide
     // whether a Stop is premature. Downgrading to a route-less state here silently disarms
     // the gate mid-task, so carry the previous route forward until a real route replaces it.
-    writeJsonFileAtomic(statePath, JSON.stringify({
+    await writeJsonFileAtomic(statePath, JSON.stringify({
       ...(sessionId ? { sessionId } : {}),
       fingerprint,
       ts: now,
@@ -2825,17 +2863,17 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     routingContext,
     useIndexedContext,
   })
-    ? buildPreviousContextSnapshot({
+    ? await buildPreviousContextSnapshot({
         projectRoot,
         routingContext,
         config: runtimeConfig,
       })
     : null;
   const indexGeneratedAtMs = useIndexedContext
-    ? readIndexGeneratedAtMs(projectRoot)
+    ? await readIndexGeneratedAtMs(projectRoot)
     : null;
   const projectVerification = useIndexedContext
-    ? readProjectVerificationFingerprint(projectRoot)
+    ? await readProjectVerificationFingerprint(projectRoot)
     : null;
   const requestKey = buildRouteRequestKey({
     commandNamespace: '.claude',
@@ -2870,11 +2908,11 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     routeSummary: compactRouteSummary(provisionalRouteSummary),
   };
   provisionalState.fingerprint = buildRouteStateFingerprint(provisionalState);
-  ensureDir(statePath);
-  writeJsonFileAtomic(statePath, JSON.stringify(provisionalState));
+  await ensureDir(statePath);
+  await writeJsonFileAtomic(statePath, JSON.stringify(provisionalState));
 
   let cacheUtils = null;
-  if (fs.existsSync(cacheUtilsPath)) {
+  if (await pathExists(cacheUtilsPath)) {
     try {
       cacheUtils = await import(pathToFileURL(cacheUtilsPath).href);
     } catch {
@@ -2931,8 +2969,8 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       process.exit(0);
     }
 
-    ensureDir(statePath);
-    writeJsonFileAtomic(statePath, JSON.stringify(reusedState));
+    await ensureDir(statePath);
+    await writeJsonFileAtomic(statePath, JSON.stringify(reusedState));
     await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
       state: reusedState,
     }));
@@ -2965,7 +3003,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       })
     : null;
   const verificationRecommendation = useIndexedContext
-    ? buildVerificationRecommendation({
+    ? await buildVerificationRecommendation({
         projectRoot,
         selectedIds,
         contextRecommendation,
@@ -3004,7 +3042,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     process.exit(0);
   }
 
-  ensureDir(statePath);
+  await ensureDir(statePath);
   const helpers = compactHelpers({
     verificationRecommendation,
     routeSummary,
@@ -3021,7 +3059,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     ...(helpers ? { helpers } : {}),
     routeSummary: compactRouteSummary(routeSummary),
   };
-  writeJsonFileAtomic(statePath, JSON.stringify(sharedState));
+  await writeJsonFileAtomic(statePath, JSON.stringify(sharedState));
   await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
     routingContext,
     routeSummary,

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

@@ -11,7 +11,15 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 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; the shell var is capped.
-  ukit_stage_hook_input 2097152 truncate || exit 0
+  ukit_stage_hook_input 2097152 truncate
+  __ukit_main_stage_rc=$?
+  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+    # Infra failure during staging (mktemp/truncate): payload was never
+    # inspected — announce the degrade (SPEC §8), never a silent pass.
+    ukit_emit_input_degraded advisory "stale-spec guard"
+  fi
+# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+ukit_input_degraded && ukit_emit_input_degraded advisory "stale-spec guard"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -38,10 +46,14 @@ else
   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
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
+    # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
+    # must be announced, never silently acted on — same shape as the helper
+    # path's ukit_emit_input_degraded.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+    printf '%s\n' '{"systemMessage":"UKit stale-spec guard: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input."}'
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
@@ -65,7 +77,11 @@ 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();
+// BUG-C21-06: the deadline path must NOT exit 0 — the wrapper treats exit 0 as
+// "worktree match → skip the guard", which silently dropped the stale-spec
+// check whenever the pre-check stalled. Non-zero falls THROUGH to the real
+// check below (documented fail-open posture), never a silent skip.
+setTimeout(() => process.exit(1), HOOK_DEADLINE_MS).unref();
 const chunks = [];
 process.stdin.on("data", (c) => chunks.push(c));
 process.stdin.on("end", () => {

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

@@ -40,7 +40,15 @@ source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   # 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
+  ukit_stage_hook_input 65536 truncate
+  __ukit_main_stage_rc=$?
+  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+    # Infra failure during staging (mktemp/truncate): payload was never
+    # inspected — announce the degrade (SPEC §8), never a silent pass.
+    ukit_emit_input_degraded advisory "task-watchdog"
+  fi
+# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+ukit_input_degraded && ukit_emit_input_degraded advisory "task-watchdog"
 else
   # 64 KiB cap and the advisory degrade path alive.
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
@@ -68,10 +76,14 @@ else
   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 65536 ]; then
-    truncate -s 65536 "$UKIT_INPUT_FILE" 2>/dev/null
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 65536 ]; then
+    # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
+    # must be announced, never silently acted on — same shape as the helper
+    # path's ukit_emit_input_degraded.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+    printf '%s\n' '{"systemMessage":"UKit task-watchdog: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input."}'
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
@@ -97,9 +109,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 () => {
+  // BUG-C21-04: the staged-payload read must be async too — a sync
+  // readFileSync on a stalled mount parks the event loop and the deadline
+  // above can never fire (orphan node grandchild).
+  let rawInput = '';
+  try { rawInput = await fsp.readFile(process.env.INPUT_FILE || '', 'utf8'); } catch {}
   const payload = (() => {
     try {
       const parsed = JSON.parse(rawInput);