@ngockhoale/ukit 2.4.2 → 2.4.3

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/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

package/templates/.claude/hooks/sensitive-data-guard.sh

@@ -11,7 +11,8 @@
 #   1. Read/Grep of secret files (.env*, *.pem, id_rsa, credentials.json, ...)
 #   2. Bash commands that dump secrets (cat .env, bare `env`, curl -u user:pass,
 #      URL-embedded credentials, any high-confidence token in the command text)
-#   3. UserPromptSubmit prompt text containing high-confidence secret patterns
+#   3. UserPromptSubmit prompt text containing high-confidence secret patterns;
+#      complete machine-generated envelopes are delivered with a redacted advisory
 #
 # FAIL-CLOSED on detection (exit 2). Never echoes the detected value — only a
 # redacted preview plus a truncated sha256 (12 hex chars: enough for the human
@@ -32,6 +33,10 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 # unknown overflow and never materializes it in a shell variable.
 # 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
   ukit_stage_hook_input 2097152 refuse
   STAGE_RC=$?
@@ -39,11 +44,34 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
     exit "$STAGE_RC"
   fi
 else
-  # Runtime helper missing (pre-install tree): same refuse posture, inline.
-  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")" || exit 2
-  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
+  # 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")"
+  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:]')"
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
+    # Fail-closed: an unstaged/oversized payload was never inspected
+    # (exit 2 blocks; 1 would be a non-blocking hook error).
     rm -f "$UKIT_INPUT_FILE"
     exit 2
   fi
@@ -289,9 +317,17 @@ if (findings.length === 0) {
 // ("Waiting for N background agents"). These envelopes flow with a redacted
 // advisory: labels + counts only, never values. Everything a human types —
 // and every other event/channel — stays fail-closed below.
-const MACHINE_ENVELOPE_RE = /^\s*<(?:task-notification|system-reminder|cross-session-message)\b/i;
+const MACHINE_ENVELOPE_RE = /^(?:task-notification|system-reminder|cross-session-message)$/i;
+function isCompleteMachineEnvelope(text) {
+  const trimmed = String(text || '').trim();
+  const opening = /^<([a-z-]+)(?:\s[^>]*)?>/i.exec(trimmed);
+  if (!opening || !MACHINE_ENVELOPE_RE.test(opening[1])) return false;
+  const tag = opening[1];
+  const closing = new RegExp(`</${tag}>$`, 'i');
+  return closing.test(trimmed);
+}
 const promptText = textChannels.length > 0 ? textChannels[0].text : null;
-if (event === 'UserPromptSubmit' && promptText && MACHINE_ENVELOPE_RE.test(promptText)) {
+if (event === 'UserPromptSubmit' && promptText && isCompleteMachineEnvelope(promptText)) {
   const labels = [...new Set(findings.map((f) => f.label))];
   process.stdout.write(`${JSON.stringify({
     systemMessage: `UKit sensitive-data gate: ${findings.length} secret-shaped value(s) inside a machine-generated notification (${labels.slice(0, 3).join('; ')}${labels.length > 3 ? '; …' : ''}). Delivered without blocking — treat as fixture/log plumbing, not a typed secret. Never repeat the values in your reply.`,

package/templates/.claude/hooks/skill-router.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): 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.
+  # 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