@ngockhoale/ukit 2.5.1 → 2.6.2

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

@@ -39,7 +39,15 @@ if source "$HOOK_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 source "$HOOK_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
+  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 failclosed "context hard-cap gate"
+  fi
+  # BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+  ukit_input_degraded && ukit_emit_input_degraded failclosed "context hard-cap gate"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -66,10 +74,15 @@ 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' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so context hard-cap gate cannot prove it safe. UKit defers this to a human decision."}}'
+    echo "BLOCKED: context hard-cap gate could not inspect a truncated/stalled payload; deferred to human." >&2
+    exit 2
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
@@ -78,23 +91,12 @@ INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" HOOK_DIR="$HOOK_DIR"
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const fs = require('fs');
+const fsp = fs.promises;
 const path = require('path');
 const { pathToFileURL } = require('url');
 
-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 hookDir = process.env.HOOK_DIR;
-const toolName = payload?.tool_name || '';
 
 // Gate only mutating/costly tools. Everything else (Read, Grep, Glob, TodoWrite, ...)
 // stays free so the agent can still respond and tell the user to compact.
@@ -102,25 +104,34 @@ const toolName = payload?.tool_name || '';
 // matches NotebookEdit/MultiEdit -- an exact !== comparison would let those slip through
 // the gate while still firing the hook.
 const GATED_TOOLS = new Set(['Edit', 'Write', 'Bash', 'NotebookEdit', 'MultiEdit']);
-if (!GATED_TOOLS.has(toolName)) {
-  process.exit(0);
-}
 
-function readJsonSafe(filePath, fallback = null) {
+// Every fs access below is async on purpose: a synchronous read on a stalled mount
+// parks the event loop and the unref'd self-deadline above can never fire (C21-04).
+async function readJsonSafe(filePath, fallback = null) {
   try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return JSON.parse(await fsp.readFile(filePath, 'utf8'));
   } catch {
     return fallback;
   }
 }
 
+async function pathExists(filePath) {
+  try {
+    await fsp.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // An unfinished handoff run — same cursor file the resume hook and the advisory
-// context guard read. `Phase: done` (or no file) means there is nothing in flight.
-function readRunCursor() {
+// context guard read. `Phase: done` and `Phase: blocked` are both terminal (the
+// same posture stop-coordinator.mjs uses); only other phases mean a run is in flight.
+async function readRunCursor() {
   try {
-    const text = fs.readFileSync(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const text = await fsp.readFile(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
     const runPhase = (text.match(/^Phase:\s*(.+)$/m)?.[1] || '').trim();
-    if (!runPhase || /^done\b/i.test(runPhase)) return null;
+    if (!runPhase || /^(done|blocked)\b/i.test(runPhase)) return null;
     return {
       phase: runPhase,
       cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
@@ -131,7 +142,22 @@ function readRunCursor() {
 }
 
 (async () => {
-  const config = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), {}) || {};
+  let rawInput = '';
+  try { rawInput = await fsp.readFile(process.env.INPUT_FILE || '', 'utf8'); } catch {}
+  const payload = (() => {
+    try {
+      const parsed = JSON.parse(rawInput);
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  })();
+  const toolName = payload?.tool_name || '';
+  if (!GATED_TOOLS.has(toolName)) {
+    process.exit(0);
+  }
+
+  const config = await readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), {}) || {};
   // Session-scoped pressure bookkeeping: the gate decides for THIS session's record, so a
   // sibling session starting (SessionStart reset) or compacting never trips or clears
   // this gate for the wrong session.
@@ -152,18 +178,18 @@ function readRunCursor() {
   }
 
   const thresholdModulePath = path.join(hookDir, '..', 'ukit', 'runtime', 'compact-threshold.mjs');
-  if (!fs.existsSync(thresholdModulePath)) {
+  if (!(await pathExists(thresholdModulePath))) {
     process.exit(0);
     return;
   }
 
   const mod = await import(pathToFileURL(thresholdModulePath).href);
   const ledgerModulePath = path.join(hookDir, '..', 'ukit', 'runtime', 'execution-ledger.mjs');
-  const ledgerMod = fs.existsSync(ledgerModulePath)
+  const ledgerMod = (await pathExists(ledgerModulePath))
     ? await import(pathToFileURL(ledgerModulePath).href)
     : null;
   const pressurePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'compact-pressure.json');
-  const rawState = readJsonSafe(pressurePath, null);
+  const rawState = await readJsonSafe(pressurePath, null);
 
   // A compaction the PreCompact hook missed (SDK/VSCode auto-compact) leaves the tracked
   // counter counting history that was already summarised away — the exact failure that
@@ -205,9 +231,9 @@ function readRunCursor() {
   const gracePath = path.join(graceDir, graceBaseName);
   const slotPath = (n) => path.join(graceDir, `${graceBaseName}.${n}`);
   const slotPattern = new RegExp(`^${graceBaseName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.(\\d+)$`);
-  const readSlots = () => {
+  const readSlots = async () => {
     try {
-      return fs.readdirSync(graceDir)
+      return (await fsp.readdir(graceDir))
         .map((name) => slotPattern.exec(name))
         .filter(Boolean)
         .map((m) => Number(m[1]))
@@ -216,21 +242,21 @@ function readRunCursor() {
       return [];
     }
   };
-  const clearGrace = () => {
-    try { fs.rmSync(gracePath, { force: true }); } catch { /* advisory only */ }
-    for (const n of readSlots()) {
-      try { fs.rmSync(slotPath(n), { force: true }); } catch { /* advisory only */ }
+  const clearGrace = async () => {
+    try { await fsp.rm(gracePath, { force: true }); } catch { /* advisory only */ }
+    for (const n of await readSlots()) {
+      try { await fsp.rm(slotPath(n), { force: true }); } catch { /* advisory only */ }
     }
   };
 
   if (state.estimatedTotalTokens < thresholds.hardCapTokens) {
     // Back under the cap — the episode is over, so the next one starts with a full budget.
-    clearGrace();
+    await clearGrace();
     process.exit(0);
     return;
   }
 
-  const run = readRunCursor();
+  const run = await readRunCursor();
   let ordinaryTask = null;
   if (!run && ledgerMod) {
     try {
@@ -252,10 +278,10 @@ function readRunCursor() {
       ? configuredGraceCalls
       : 10;
 
-    let slots = readSlots();
+    let slots = await readSlots();
     let startedAtTokens = null;
     for (const n of slots) {
-      const data = readJsonSafe(slotPath(n), null);
+      const data = await readJsonSafe(slotPath(n), null);
       if (data && Number.isFinite(data.startedAtTokens)) {
         startedAtTokens = Math.max(startedAtTokens ?? -Infinity, data.startedAtTokens);
       }
@@ -264,7 +290,7 @@ function readRunCursor() {
     // real compaction/shed happened. Advancing the cursor alone must NOT top the budget up,
     // otherwise a long run gets unlimited grace and the ceiling stops meaning anything.
     if (startedAtTokens !== null && state.estimatedTotalTokens < startedAtTokens) {
-      clearGrace();
+      await clearGrace();
       slots = [];
       startedAtTokens = null;
     }
@@ -278,12 +304,17 @@ function readRunCursor() {
       let used = 0;
       let counterFailed = false;
       try {
-        fs.mkdirSync(graceDir, { recursive: true });
+        await fsp.mkdir(graceDir, { recursive: true });
         for (let n = spent + 1; n <= graceCalls; n += 1) {
           try {
-            const fd = fs.openSync(slotPath(n), 'wx');
-            fs.writeSync(fd, JSON.stringify({ startedAtTokens, used: n, ts: Date.now() }));
-            fs.closeSync(fd);
+            // Exclusive-create via 'wx' keeps the EEXIST race semantics of the old
+            // openSync('wx') claim: the sentinel exists exactly once per spent call.
+            const handle = await fsp.open(slotPath(n), 'wx');
+            try {
+              await handle.writeFile(JSON.stringify({ startedAtTokens, used: n, ts: Date.now() }));
+            } finally {
+              await handle.close();
+            }
             used = n;
             break;
           } catch (err) {
@@ -297,7 +328,7 @@ function readRunCursor() {
       if (used === 0 && counterFailed) used = spent + 1;
       if (used > 0 && used <= graceCalls) {
         try {
-          fs.writeFileSync(gracePath, JSON.stringify({ startedAtTokens, used }));
+          await fsp.writeFile(gracePath, JSON.stringify({ startedAtTokens, used }));
           if (ordinaryTask && ledgerMod && used === 1) {
             await ledgerMod.writeResumeIntent(projectRoot, payload);
           }

package/templates/.claude/hooks/context-window-guard.sh

@@ -31,7 +31,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; Node gets a 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 "context-window 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 "context-window 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
@@ -58,10 +66,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 context-window 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
@@ -92,7 +104,9 @@ import { pathToFileURL } from 'node:url';
 const CHARS_PER_TOKEN = 4;
 
 let rawInput = '';
-try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
+// All fs access in this block is async on purpose: a synchronous read on a stalled
+// mount parks the event loop and the unref'd self-deadline above can never fire.
+try { rawInput = await fs.promises.readFile(process.env.INPUT_FILE || '', 'utf8'); } catch {}
 const payload = (() => {
   try {
     const parsed = JSON.parse(rawInput);
@@ -109,7 +123,7 @@ if (!transcriptPath) process.exit(0);
 // Operator config is read once; a missing/corrupt file just means the defaults.
 let runtimeConfig = {};
 try {
-  runtimeConfig = JSON.parse(fs.readFileSync(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8'));
+  runtimeConfig = JSON.parse(await fs.promises.readFile(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8'));
 } catch { /* fall through to the defaults */ }
 if (!runtimeConfig || typeof runtimeConfig !== 'object') runtimeConfig = {};
 
@@ -247,8 +261,8 @@ const ratio = estimatedTokens / hardCap;
 const CAPACITY_RECORD_PATH = path.join(projectRoot, '.ukit', 'storage', 'cache', 'context-capacity.json');
 if (negotiatedCapacity) {
   try {
-    fs.mkdirSync(path.dirname(CAPACITY_RECORD_PATH), { recursive: true });
-    const previous = readCapacityRecord();
+    await fs.promises.mkdir(path.dirname(CAPACITY_RECORD_PATH), { recursive: true });
+    const previous = await readCapacityRecord();
     // Only rewrite when the evidence changed, so prompt caching sees a stable file.
     if (!previous
       || previous.tokens !== negotiatedCapacity.tokens
@@ -261,14 +275,14 @@ if (negotiatedCapacity) {
         model: currentModel ?? null,
         updatedAt: Date.now(),
       };
-      fs.writeFileSync(CAPACITY_RECORD_PATH, `${JSON.stringify(record)}\n`, 'utf8');
+      await fs.promises.writeFile(CAPACITY_RECORD_PATH, `${JSON.stringify(record)}\n`, 'utf8');
     }
   } catch { /* fail open: negotiation is advisory */ }
 }
 
-function readCapacityRecord() {
+async function readCapacityRecord() {
   try {
-    const parsed = JSON.parse(fs.readFileSync(CAPACITY_RECORD_PATH, 'utf8'));
+    const parsed = JSON.parse(await fs.promises.readFile(CAPACITY_RECORD_PATH, 'utf8'));
     return parsed && typeof parsed === 'object' ? parsed : null;
   } catch {
     return null;
@@ -278,22 +292,22 @@ function readCapacityRecord() {
 // Debounce/state file shared by the context warning and the gateway model-swap note.
 const GUARD_STATE_PATH = path.join(projectRoot, '.ukit', 'storage', 'cache', 'context-guard-state.json');
 
-function readGuardState() {
+async function readGuardState() {
   try {
-    return JSON.parse(fs.readFileSync(GUARD_STATE_PATH, 'utf8'));
+    return JSON.parse(await fs.promises.readFile(GUARD_STATE_PATH, 'utf8'));
   } catch {
     return { lastPhase: null, lastActionAt: 0, lastSwapModel: null, lastSwapNoteAt: 0 };
   }
 }
 
-function writeGuardState(state) {
+async function writeGuardState(state) {
   try {
-    fs.mkdirSync(path.dirname(GUARD_STATE_PATH), { recursive: true });
-    fs.writeFileSync(GUARD_STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    await fs.promises.mkdir(path.dirname(GUARD_STATE_PATH), { recursive: true });
+    await fs.promises.writeFile(GUARD_STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
   } catch { /* best-effort only; never block the prompt over this */ }
 }
 
-const guardState = readGuardState();
+const guardState = await readGuardState();
 let persistedState = { ...guardState };
 
 // ── Gateway model-swap note ──
@@ -322,12 +336,12 @@ if (swapDetected && persistedState.lastSwapModel !== currentModel) {
   const withinSwapCooldown = (Date.now() - Number(persistedState.lastSwapNoteAt || 0)) < SWAP_NOTE_COOLDOWN_MS;
   if (!withinSwapCooldown) {
     persistedState.lastSwapNoteAt = Date.now();
-    writeGuardState(persistedState);
+    await writeGuardState(persistedState);
     process.stdout.write(
       `UKIT GATEWAY — routine backend model swap ("${currentModel}" after "${previousModel}"): keep working, do not restart or re-plan; if a tool call errors after a swap, re-check the tool (providers differ) and simply call it again — never stop over it.\n`,
     );
   } else {
-    writeGuardState(persistedState);
+    await writeGuardState(persistedState);
   }
 }
 
@@ -344,7 +358,7 @@ const boundaryAgeMs = boundaryTs !== null ? Date.now() - boundaryTs : null;
 const justCompacted = boundaryAgeMs !== null && boundaryAgeMs >= 0 && boundaryAgeMs < POST_COMPACT_WINDOW_MS;
 if (justCompacted && ratio >= POST_COMPACT_RATIO && persistedState.lastPostCompactBoundary !== String(boundaryTs)) {
   persistedState.lastPostCompactBoundary = String(boundaryTs);
-  writeGuardState(persistedState);
+  await writeGuardState(persistedState);
   process.stdout.write(
     [
       `UKIT POST-COMPACT CHECK — compaction ~${Math.max(1, Math.round(boundaryAgeMs / 60000))} min ago, but live context is still ~${estimatedTokens.toLocaleString()} tokens (${Math.round(ratio * 100)}% of the ${hardCap.toLocaleString()} cap).`,
@@ -378,11 +392,11 @@ const withinCooldown = guardState.lastPhase === phase
 // resumable, and a mid-cycle halt is what used to strand a cycle for days. The right
 // directive during a run is "shed context at the next wave boundary and keep going" —
 // compaction is requested once, at the cycle boundary, by the command's Final Report.
-function readRunCursor() {
+async function readRunCursor() {
   try {
-    const text = fs.readFileSync(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const text = await fs.promises.readFile(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
     const runPhase = (text.match(/^Phase:\s*(.+)$/m)?.[1] || '').trim();
-    if (!runPhase || /^done\b/i.test(runPhase)) return null;
+    if (!runPhase || /^(done|blocked)\b/i.test(runPhase)) return null;
     return {
       phase: runPhase,
       cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
@@ -392,7 +406,7 @@ function readRunCursor() {
   }
 }
 
-const run = readRunCursor();
+const run = await readRunCursor();
 
 const lines_out = [];
 if (ratio >= 1) {
@@ -418,7 +432,7 @@ if (withinCooldown) {
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch. Keep concurrency at or below handoff.maxParallelAgents and keep returns short; do not widen the batch while this warning stands.`);
   }
-  writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
+  await writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
 } else {
   lines_out.push('ACTION THIS TURN, before starting new investigation/subagents/pipeline phases:');
   lines_out.push('1) LAND ONE THING: pick the smallest in-flight item you can finish end-to-end in ≤3 tool calls (edit + verify), complete exactly that one, and report it done. Do not open anything new.');
@@ -428,7 +442,7 @@ if (withinCooldown) {
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch — each teammate carries its own context window, and every finished report is injected back here, so running many at once is the fastest way to overflow this session. Avoid spawning more until context drops back under the cap.`);
   }
-  writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
+  await writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
 }
 
 process.stdout.write(`${lines_out.join('\n')}\n`);

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -20,7 +20,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 "handoff model-tier 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 "handoff model-tier 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
@@ -47,10 +55,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 handoff model-tier 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
@@ -73,11 +85,22 @@ 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();
 const fs = require('fs');
+const fsp = fs.promises;
 const path = require('path');
 
+// BUG-C21-04: every fs call in this deadline-guarded block is async — a sync
+// read on a stalled mount parks the event loop and the deadline can never fire.
+void (async () => {
+async function pathExists(filePath) {
+  try { await fsp.access(filePath); return true; } catch { return false; }
+}
+async function readTextSafe(filePath) {
+  try { return await fsp.readFile(filePath, 'utf8'); } catch { return ''; }
+}
+
+let raw = '';
+try { raw = await fsp.readFile(process.env.INPUT_FILE || '', 'utf8'); } catch {}
 const payload = (() => {
-  let raw = '';
-  try { raw = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
   try { return JSON.parse(raw || '{}'); } catch { return {}; }
 })();
 const projectRoot = process.env.PROJECT_ROOT;
@@ -137,8 +160,8 @@ if (toolName === 'Write' || toolName === 'Edit') {
   const taskMatch = relPath.match(/^docs\/AI_HANDOFF\/tasks\/(TASK-\d+)\.md$/);
   if (!isPlan && !taskMatch) process.exit(0);
 
-  const fileExists = fs.existsSync(filePath);
-  const currentContent = fileExists ? fs.readFileSync(filePath, 'utf8') : '';
+  const fileExists = await pathExists(filePath);
+  const currentContent = fileExists ? await readTextSafe(filePath) : '';
 
   function resultingContent() {
     if (toolName === 'Write') {
@@ -176,11 +199,35 @@ if (toolName === 'Write' || toolName === 'Edit') {
     const hasReviewerVerdict = /## Reviewer Verdict/.test(newVisible);
     const isFreshTaskFile = !fileExists;
     if (isFreshTaskFile) {
-      const planContent = fs.existsSync(planPath) ? fs.readFileSync(planPath, 'utf8') : '';
+      const planContent = (await pathExists(planPath)) ? await readTextSafe(planPath) : '';
       const plannerModel = extractField(stripHtmlComments(planContent), 'PLANNER_MODEL');
       if (!plannerModel || tierOf(plannerModel) !== 'smart') {
         block(`Cannot create ${taskId}.md — PLAN.md has no valid smart-tier PLANNER_MODEL yet. Run planning via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) first.`);
       }
+
+      // Spec gate (handoff-fullstack v2): tasks are decomposed FROM a detailed spec, so a
+      // fresh task file requires docs/AI_HANDOFF/SPEC.md to exist and to differ from the
+      // shipped template. Disable per project: handoff.fullstack.specRequired=false.
+      let specRequired = true;
+      try {
+        const cfg = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/config.json'), 'utf8'));
+        if (cfg?.handoff?.fullstack?.specRequired === false) specRequired = false;
+      } catch {}
+      if (specRequired) {
+        let specOk = false;
+        try {
+          const specPath = path.join(projectRoot, 'docs/AI_HANDOFF/SPEC.md');
+          const specText = await fsp.readFile(specPath, 'utf8');
+          let templateText = null;
+          try {
+            templateText = await fsp.readFile(path.join(projectRoot, 'templates/docs/AI_HANDOFF/SPEC.md'), 'utf8');
+          } catch {}
+          specOk = specText.length > 500 && specText !== templateText;
+        } catch {}
+        if (!specOk) {
+          block(`Cannot create ${taskId}.md — docs/AI_HANDOFF/SPEC.md is missing or still the untouched template. handoff-create must write a detailed spec (15 sections) before tasks are created.`);
+        }
+      }
     }
 
     // A section already on disk only counts as validated when its model is real —
@@ -274,17 +321,17 @@ if (toolName === 'Bash') {
 
   const activePath = path.join(projectRoot, 'docs/AI_HANDOFF/ACTIVE.md');
   const indexPath = path.join(projectRoot, 'docs/AI_HANDOFF/INDEX.md');
-  if (!fs.existsSync(activePath) || !fs.existsSync(indexPath)) process.exit(0); // no handoff cycle here
+  if (!(await pathExists(activePath)) || !(await pathExists(indexPath))) process.exit(0); // no handoff cycle here
 
-  const taskIds = [...fs.readFileSync(indexPath, 'utf8').matchAll(/TASK-\d+/g)]
+  const taskIds = [...(await fsp.readFile(indexPath, 'utf8')).matchAll(/TASK-\d+/g)]
     .map((m) => m[0])
     .filter((v, i, a) => a.indexOf(v) === i);
 
   const problems = [];
   for (const taskId of taskIds) {
     const taskPath = path.join(projectRoot, `docs/AI_HANDOFF/tasks/${taskId}.md`);
-    if (!fs.existsSync(taskPath)) continue;
-    const text = stripHtmlComments(fs.readFileSync(taskPath, 'utf8'));
+    if (!(await pathExists(taskPath))) continue;
+    const text = stripHtmlComments(await fsp.readFile(taskPath, 'utf8'));
     if (!text.includes('## Reviewer Verdict')) continue; // not yet reviewed, not this push's concern
 
     // A documented, human-approved exception (e.g. an opus-tier executor escalation left no
@@ -314,6 +361,7 @@ if (toolName === 'Bash') {
 }
 
 process.exit(0);
+})();
 NODE
 
 exit $?

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

@@ -28,7 +28,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; Node gets a 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 "handoff-resume"
+  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 "handoff-resume"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -55,10 +63,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 handoff-resume: 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
@@ -131,8 +143,9 @@ async function emitOrdinaryResume() {
   const field = (name) => (text.match(new RegExp(`^${name}:\\s*(.+)$`, 'm'))?.[1] || '').trim();
 
   const phase = field('Phase');
-  // `done` means the last cycle finished cleanly. Anything else means a step was in flight.
-  if (!phase || /^done\b/i.test(phase)) {
+  // `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();
     process.exit(0);
   }

package/templates/.claude/hooks/post-edit-verify.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 "post-edit-verify"
+  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 "post-edit-verify"
 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 post-edit-verify: 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