@ngockhoale/ukit 2.4.2 → 2.5.0

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

@@ -25,16 +25,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; Node gets a path, never the payload.
   ukit_stage_hook_input 2097152 truncate || exit 0
 else
-  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
-  # advisory/fail-open behavior below alive with a capped payload file.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
@@ -80,12 +106,18 @@ const projectRoot = process.env.PROJECT_ROOT;
 const transcriptPath = typeof payload.transcript_path === 'string' ? payload.transcript_path.trim() : '';
 if (!transcriptPath) process.exit(0);
 
-function loadHardCap() {
-  try {
-    const raw = fs.readFileSync(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8');
-    const value = JSON.parse(raw)?.compact?.hardCapTokens;
-    if (typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0) return value;
-  } catch { /* fall through to the default */ }
+// 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'));
+} catch { /* fall through to the defaults */ }
+if (!runtimeConfig || typeof runtimeConfig !== 'object') runtimeConfig = {};
+
+// Absolute operator ceiling (compact.hardCapTokens). Negotiated capacity can only ever
+// tighten this, never raise it.
+function operatorHardCap() {
+  const value = runtimeConfig?.compact?.hardCapTokens;
+  if (typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0) return value;
   return 500_000;
 }
 
@@ -160,9 +192,89 @@ for (let i = start; i < entries.length; i += 1) {
 }
 
 const estimatedTokens = Math.round(contentChars / CHARS_PER_TOKEN);
-const hardCap = loadHardCap();
+
+// Latest assistant model in the live window — this is the model that must fit the NEXT
+// request, so capacity negotiation follows it. A mid-session gateway swap to a smaller
+// model tightens the cap immediately; the earlier model's window is never sticky.
+// (Hoisted above the ratio so both capacity negotiation and the swap note share it.)
+const RECENT_MODEL_WINDOW = 40;
+const recentModels = modelSequence.slice(-RECENT_MODEL_WINDOW);
+const currentModel = recentModels[recentModels.length - 1] || null;
+
+// Negotiated capacity (H22): derive the advisory cap from the best available evidence —
+// env override > config override > verified model table > conservative default — instead
+// of assuming one hard-coded 500k window. The source is surfaced in the warning lines
+// below (capacitySource=...) so a mis-negotiated cap is diagnosable at a glance. A
+// missing runtime helper (pre-install tree) keeps the shipped fallback behavior —
+// advisory and fail-open either way.
+async function loadCapacityResolver() {
+  try {
+    return await import(pathToFileURL(path.join(
+      process.env.SCRIPT_DIR || process.cwd(),
+      '..',
+      'ukit',
+      'runtime',
+      'context-capacity.mjs',
+    )).href);
+  } catch {
+    return null;
+  }
+}
+
+let hardCap = operatorHardCap();
+let capacitySource = 'default';
+let negotiatedCapacity = null;
+try {
+  const capacityModule = await loadCapacityResolver();
+  if (capacityModule && typeof capacityModule.resolveContextCapTokens === 'function') {
+    const resolved = capacityModule.resolveContextCapTokens({
+      env: process.env,
+      config: runtimeConfig,
+      modelMetadata: { model: currentModel },
+    });
+    hardCap = resolved.capTokens;
+    capacitySource = resolved.capacity?.source ?? 'default';
+    negotiatedCapacity = resolved.capacity ?? null;
+  }
+} catch { /* negotiation is advisory — the operator ceiling already applies */ }
 const ratio = estimatedTokens / hardCap;
 
+// Publish what this hook negotiated so the compact-threshold/hard-cap-gate path stops
+// assuming a 500k window: this is the only place with live evidence (env + config + the
+// transcript's assistant models). Without the record, automatic compact waits until 240k
+// and the fail-closed gate until 500k on a verified 200k route — after the provider already
+// rejected the request. Best-effort: an unwritable cache dir must never break the guard.
+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();
+    // Only rewrite when the evidence changed, so prompt caching sees a stable file.
+    if (!previous
+      || previous.tokens !== negotiatedCapacity.tokens
+      || previous.source !== negotiatedCapacity.source
+      || previous.model !== (currentModel ?? null)) {
+      const record = {
+        tokens: negotiatedCapacity.tokens,
+        source: negotiatedCapacity.source,
+        confidence: negotiatedCapacity.confidence,
+        model: currentModel ?? null,
+        updatedAt: Date.now(),
+      };
+      fs.writeFileSync(CAPACITY_RECORD_PATH, `${JSON.stringify(record)}\n`, 'utf8');
+    }
+  } catch { /* fail open: negotiation is advisory */ }
+}
+
+function readCapacityRecord() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CAPACITY_RECORD_PATH, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 // 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');
 
@@ -194,11 +306,9 @@ let persistedState = { ...guardState };
 // keep working through swaps, and on a tool error after a swap, re-check the tool and
 // call it again instead of stopping. Runs before the ratio early-exit because a swap
 // can happen at any context level.
-const RECENT_MODEL_WINDOW = 40;
 const SWAP_NOTE_COOLDOWN_MS = 60 * 60 * 1000;
-// modelSequence was collected in the single pass over entries above.
-const recentModels = modelSequence.slice(-RECENT_MODEL_WINDOW);
-const currentModel = recentModels[recentModels.length - 1] || null;
+// recentModels/currentModel were hoisted above for capacity negotiation; modelSequence
+// was collected in the single pass over entries.
 let previousModel = null;
 for (let i = recentModels.length - 2; i >= 0; i -= 1) {
   if (recentModels[i] !== currentModel) {
@@ -286,10 +396,10 @@ const run = readRunCursor();
 
 const lines_out = [];
 if (ratio >= 1) {
-  lines_out.push(`UKIT CONTEXT ALERT — live context ~${estimatedTokens.toLocaleString()} tokens, at/over the ${hardCap.toLocaleString()} cap (${pct}%).`);
+  lines_out.push(`UKIT CONTEXT ALERT — live context ~${estimatedTokens.toLocaleString()} tokens, at/over the ${hardCap.toLocaleString()} cap (${pct}%, capacitySource=${capacitySource}).`);
   lines_out.push('The next few turns risk "Your input exceeds the context window of this model".');
 } else {
-  lines_out.push(`UKIT CONTEXT WARNING — live context ~${estimatedTokens.toLocaleString()} tokens (${pct}% of the ${hardCap.toLocaleString()} cap).`);
+  lines_out.push(`UKIT CONTEXT WARNING — live context ~${estimatedTokens.toLocaleString()} tokens (${pct}% of the ${hardCap.toLocaleString()} cap, capacitySource=${capacitySource}).`);
 }
 
 if (estimatePartial) {

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

@@ -14,16 +14,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; 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.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT

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

@@ -22,16 +22,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; Node gets a path, never the payload.
   ukit_stage_hook_input 2097152 truncate || exit 0
 else
-  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
-  # advisory/fail-open behavior below alive with a capped payload file.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT

package/templates/.claude/hooks/post-edit-verify.sh

@@ -5,16 +5,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; 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.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT

package/templates/.claude/hooks/pre-edit-backup.sh

@@ -5,16 +5,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; 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.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT

package/templates/.claude/hooks/project-important.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# SessionStart hook: emit the deterministic PROJECT_IMPORTANT.md mandate envelope
+# once per context epoch (docs/PROJECT_IMPORTANT_SPEC.md §6, §7, §9).
+# ADVISORY ONLY — always exit 0. A missing runtime or a renderer failure degrades
+# to the frozen `unreadable` warning line, never a raw exception, never a blocked
+# session. No renderer logic lives here — the shared runtime module renders.
+
+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
+# Arm advisory latency telemetry when available; a missing runtime (pre-install
+# tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
+  trap ukit_cleanup_hook_input EXIT
+  # Bounded stdin (H01): the SessionStart payload is unused, but it still flows
+  # through the staging bound so a producer that never closes the pipe cannot
+  # hold this hook open (R4.5).
+  ukit_stage_hook_input 1048576 truncate || exit 0
+else
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline — read cap+1 in the background, bound the wait, never drain with an
+  # unconditional `cat`.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 1048577 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 1048577 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/project-important.mjs"
+UNREADABLE_WARNING='[UKit] PROJECT_IMPORTANT.md was not injected: the file could not be read. Run `ukit doctor`.'
+
+if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' "$UNREADABLE_WARNING"
+  exit 0
+fi
+
+# The wrapped runtime self-arms on UKIT_HOOK_DEADLINE_MS (SCRIPT_ARM/EXIT_ARM),
+# so a wedged read exits 0 inside the deadline instead of orphaning a node child.
+INPUT="$(cat "$UKIT_INPUT_FILE" 2>/dev/null)"
+OUTPUT=$(printf '%s' "$INPUT" | UKIT_PROJECT_ROOT="$PROJECT_ROOT" UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" 2>/dev/null)
+STATUS=$?
+
+if [ "$STATUS" -ne 0 ] || [ -z "$OUTPUT" ]; then
+  printf '%s\n' "$UNREADABLE_WARNING"
+  exit 0
+fi
+
+printf '%s\n' "$OUTPUT"
+exit 0

package/templates/.claude/hooks/protect-files.sh

@@ -5,16 +5,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; 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.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT

package/templates/.claude/hooks/record-execution.sh

@@ -5,17 +5,43 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): receipts can legitimately be large, so the staged file
   # is the transport and the shell var only mirrors the capped payload.
   ukit_stage_hook_input 33554432 temp-file || exit 0
 else
-  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
-  # wrapper's own fail-loud/advisory behavior below alive.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 33554433 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 33554432 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 33554433 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 33554433 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 33554432 ]; then
     truncate -s 33554432 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT