@ngockhoale/ukit 2.7.4 → 2.7.6

package/templates/.claude/hooks/block-dangerous.sh

@@ -1,8 +1,17 @@
 #!/bin/bash
 # PreToolUse hook: Block dangerous bash commands
 # Matched on: Bash
+#
+# C40 TASK-003: this script is a THIN WRAPPER. The single source of truth for
+# command extraction, quoted-span scrub, the pattern table, the rm allowlist
+# and every verdict byte is block-dangerous.mjs (SPEC §14 — one implementation
+# of a fail-closed gate; this shell keeps staging, the degraded-input salvage
+# path, telemetry, and the env contract so direct/debug invocation and
+# git-revert rollback keep working).
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_DIR="$SCRIPT_DIR"
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$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
@@ -75,228 +84,20 @@ else
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
-if [ "${UKIT_SALVAGE_ACTIVE:-0}" = "1" ]; then
-  # TASK-003: degraded path already recovered a COMPLETE command — skip the
-  # normal extraction (the staged prefix would not parse anyway).
-  COMMAND="$UKIT_SALVAGED_COMMAND"
-else
-INPUT="$(cat "$UKIT_INPUT_FILE")"
-# jq is not installed on stock macOS. Keep jq as the low-latency normal path, but use
-# UKit's required Node runtime as a fallback so its absence cannot silently disable the gate.
-if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
-  COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
-else
-  COMMAND=$(printf '%s' "$INPUT" | node -e '
-const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-const chunks = [];
-process.stdin.on("data", (chunk) => chunks.push(chunk));
-process.stdin.on("end", () => {
-  try {
-    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
-    process.stdout.write(typeof payload?.tool_input?.command === "string" ? payload.tool_input.command : "");
-  } catch {}
-});
-' 2>/dev/null)
-fi
-fi
-
-if [ -z "$COMMAND" ]; then
-  exit 0
-fi
 
-# A command like `grep "rm -rf" file.sh` or `echo "rm -rf /"` merely mentions the
-# text of a dangerous pattern as data — it does not execute it. Naively substring-matching
-# the raw command line false-positives on any search/print of that text. Scrub quoted
-# spans before pattern-matching, but ONLY when the invoked command is a pure text tool
-# AND its output cannot reach a shell (no piping into bash/sh/zsh/eval/xargs), since
-# `echo "rm -rf /" | bash` really does execute the quoted text.
-SAFE_TEXT_CMD_REGEX='^(grep|egrep|fgrep|rg|ag|awk|sed|echo|printf|cat)$'
-PIPE_TO_SHELL_REGEX='\|[[:space:]]*(bash|sh|zsh|eval|xargs)([[:space:]]|$)'
-
-CMD_HEAD=$(echo "$COMMAND" | sed -E 's/^[[:space:]]*//' | awk '{print $1}' | xargs -I{} basename {} 2>/dev/null)
-
-SCAN_COMMAND="$COMMAND"
-if echo "$CMD_HEAD" | grep -qE "$SAFE_TEXT_CMD_REGEX" && ! echo "$COMMAND" | grep -qE "$PIPE_TO_SHELL_REGEX"; then
-  SCAN_COMMAND=$(printf '%s' "$COMMAND" | sed -E "s/'[^']*'/'Q'/g; s/\"[^\"]*\"/\"Q\"/g")
+# Delegate to the module: identical env contract the bash glue consumed.
+# realpath parity (TASK-013): the pre-port gate failed closed when the system
+# `realpath` was unavailable; the module resolves in-proc via Node, so the
+# wrapper forwards the dependency signal — no realpath binary -> canonical
+# containment cannot be proven -> allowlist targets defer, never allow.
+command -v realpath >/dev/null 2>&1 || UKIT_REALPATH_MISSING=1
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" UKIT_SALVAGE_ACTIVE="${UKIT_SALVAGE_ACTIVE:-0}" UKIT_SALVAGED_COMMAND="${UKIT_SALVAGED_COMMAND:-}" UKIT_REALPATH_MISSING="${UKIT_REALPATH_MISSING:-0}" node "$HOOK_DIR/block-dangerous.mjs"
+NODE_RC=$?
+# BUG-C21-03 parity (fail-closed): a node crash means the payload was never
+# fully inspected — announce + block, never a silent non-blocking hook error.
+if [ "$NODE_RC" -ne 0 ] && [ "$NODE_RC" -ne 2 ]; then
+  printf '%s\n' '{"systemMessage":"UKit dangerous-command gate crashed before finishing its scan; blocked fail-closed rather than pass an uninspected payload. Run `ukit install` if this repeats."}'
+  echo "BLOCKED: dangerous-command gate crashed (exit $NODE_RC); payload never inspected (fail-closed)." >&2
+  exit 2
 fi
-
-# Dangerous patterns to block
-DANGEROUS_PATTERNS=(
-  "rm -rf /"
-  "rm -rf ~"
-  "rm -rf \\.?\\.([[:space:]]|$)"
-  "git push --force"
-  "git push -f "
-  "git reset --hard"
-  "git clean -fd"
-  "git checkout \."
-  "git restore \."
-  "> /dev/sda"
-  "mkfs\."
-  ":(){ :|:& };:"
-  "dd if=/dev/"
-)
-
-# Dangerous detections surface as a structured decision (stdout JSON). TASK-223:
-# emission is centralized in ukit_emit_permission_decision — exit 0 on the direct
-# host (where a non-zero exit would discard the JSON as a bare "hook error"),
-# exit 2 inside the omp chain (whose bridge only parses stdout on code 2).
-# Probe verdict (2026-09-20, spec step 4): this repo runs
-# permissions.defaultMode=bypassPermissions, where an exit-0 `ask` auto-approves —
-# dead for refusals. So the direct host gets `deny` (a proper denied surface, still
-# fail-closed); the omp chain keeps `ask` (the host boundary prompts the human).
-# The raw command and the matched pattern are NEVER echoed — arguments and comments can
-# carry secrets, and the pattern text itself restates the dangerous command.
-emit_dangerous_decision() {
-  REASON="$1"
-  if command -v ukit_emit_permission_decision >/dev/null 2>&1; then
-    if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
-      ukit_emit_permission_decision ask "$REASON"
-    else
-      ukit_emit_permission_decision deny "$REASON"
-    fi
-  fi
-  # Helper unavailable (pre-install tree): keep the safe inline parity — the
-  # direct host gets deny + exit 0, the chain gets ask + exit 2.
-  if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then
-    printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
-    echo "BLOCKED: $REASON" >&2
-    exit 2
-  fi
-  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"$REASON\"}}"
-  echo "BLOCKED: $REASON" >&2
-  exit 0
-}
-
-for pattern in "${DANGEROUS_PATTERNS[@]}"; do
-  if echo "$SCAN_COMMAND" | grep -qE "$pattern"; then
-    emit_dangerous_decision "Dangerous command pattern detected; it could cause irreversible damage. UKit defers this to a human decision."
-  fi
-done
-
-# Handle rm commands: allow safe cleanup targets only, defer everything else to a human.
-# Direct rm invocations are parsed per shell segment (`;`, `&`, `|` split) with per-target
-# allowlist evaluation: split flags (`rm -r -f`, `rm --force -r`) register, and one
-# allowlisted word can never legitimise a sibling target (`rm -rf dist /`). A whole-command
-# fallback still catches rm inside wrapped/quoted contexts (`bash -c "rm -r -f /x"`) and
-# flags placed after targets (`rm src -rf`), where segment parsing cannot see rm as a head.
-SAFE_DELETE_REGEX='(^|[[:space:]])(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/|[[:space:]]|$)'
-UNSAFE_TARGET_REGEX='(^|[[:space:]])(/|~|\.\.?($|/)|\.($|/))'
-SAFE_ONE_TARGET_REGEX='^(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/.*)?$'
-UNSAFE_ONE_TARGET_REGEX='^(/.*|~|~/.*|\.\.|\.\./.*|\.)$'
-RM_WORD_REGEX=$'(^|[;&|[:space:]"\x27])rm([[:space:]"\x27]|$)'
-
-# TASK-013 / SPEC §10: canonical-path containment for the name allowlist. A
-# target that passes SAFE_ONE_TARGET_REGEX must ALSO resolve inside
-# realpath(projectRoot) — a `dist` symlinked outside the project (or a `..`
-# segment) downgrades the segment to the generic verdict, never allow.
-#
-# ukit_canonical_path mirrors GNU `realpath -m` semantics portably:
-#   1. `realpath -m` (GNU/coreutils) when supported;
-#   2. ONE documented fallback — stock macOS `realpath` cannot resolve
-#      nonexistent paths, so resolve the deepest existing ancestor and append
-#      the lexical remainder (equivalent for containment);
-#   3. `realpath` itself absent → empty output → fail closed (unresolved-
-#      generic), never silently allow.
-ukit_canonical_path() {
-  __u_p="$1"
-  __u_out=$(realpath -m -- "$__u_p" 2>/dev/null) && [ -n "$__u_out" ] && { printf '%s' "$__u_out"; return 0; }
-  __u_rest=""
-  while [ -n "$__u_p" ] && [ "$__u_p" != "/" ] && [ ! -e "$__u_p" ] && [ ! -L "$__u_p" ]; do
-    __u_rest="/${__u_p##*/}${__u_rest}"
-    __u_p="${__u_p%/*}"
-  done
-  [ -z "$__u_p" ] && __u_p="/"
-  __u_out=$(realpath -- "$__u_p" 2>/dev/null) || return 1
-  printf '%s%s' "$__u_out" "$__u_rest"
-}
-
-# Project-root canonical prefix, resolved once before the segment loop. Targets
-# are interpreted relative to the project root (the host's rm cwd), not the
-# hook's own cwd. An unresolvable root fails closed: no allowlist target can
-# prove containment against an unknown root.
-UKIT_PROJECT_ROOT_CANON=$(ukit_canonical_path "${CLAUDE_PROJECT_DIR:-$PWD}")
-
-RM_VERDICT_UNSAFE=0
-RM_VERDICT_GENERIC=0
-RM_DIRECT_SEEN=0
-set -f
-while IFS= read -r segment; do
-  [ -n "$segment" ] || continue
-  seg_head=$(printf '%s' "$segment" | sed -E 's/^[[:space:]]*//' | awk '{print $1}' | xargs -I{} basename {} 2>/dev/null)
-  [ "$seg_head" = "rm" ] || continue
-  seg_flags=$(printf '%s' "$segment" | awk '{for(i=2;i<=NF;i++){if($i=="--")break;if($i ~ /^-/)printf "%s\n",$i;else break}}')
-  seg_has_r=0
-  seg_has_f=0
-  for flag in $seg_flags; do
-    case "$flag" in
-      --recursive) seg_has_r=1 ;;
-      --force) seg_has_f=1 ;;
-      --*) ;;
-      -*) case "$flag" in *[rR]*) seg_has_r=1 ;; esac
-          case "$flag" in *f*) seg_has_f=1 ;; esac ;;
-    esac
-  done
-  [ "$seg_has_r" -eq 1 ] && [ "$seg_has_f" -eq 1 ] || continue
-  RM_DIRECT_SEEN=1
-  seg_targets=$(printf '%s' "$segment" | awk '{saw=0;for(i=2;i<=NF;i++){if(!saw){if($i=="--"){saw=1;continue}if($i ~ /^-/)continue;saw=1;printf "%s\n",$i}else if($i !~ /^-/)printf "%s\n",$i}}')
-  seg_all_safe=1
-  seg_any_unsafe=0
-  for target in $seg_targets; do
-    # Strip ONE trailing slash so `dist/` matches the allowlist — but never shrink a
-    # bare `/` (or `~`) to an empty string, which would silently dodge the unsafe check.
-    if [ "${#target}" -gt 1 ]; then target="${target%/}"; fi
-    if printf '%s' "$target" | grep -qE "$UNSAFE_ONE_TARGET_REGEX"; then
-      seg_any_unsafe=1
-      seg_all_safe=0
-    elif printf '%s' "$target" | grep -qE "$SAFE_ONE_TARGET_REGEX"; then
-      # Containment gate (TASK-013): the allowlisted NAME is not enough — the
-      # canonical target must live inside the canonical project root. `..`
-      # segments and unresolvable/missing realpath fail closed to generic.
-      case "$target" in
-        *..*) seg_all_safe=0 ;;
-        *)
-          case "$target" in /*) __t_abs="$target" ;; *) __t_abs="$UKIT_PROJECT_ROOT_CANON/$target" ;; esac
-          __t_canon=$(ukit_canonical_path "$__t_abs")
-          if [ -z "$UKIT_PROJECT_ROOT_CANON" ] || [ -z "$__t_canon" ]; then
-            seg_all_safe=0
-          else
-            case "$__t_canon" in
-              "$UKIT_PROJECT_ROOT_CANON"/*) : ;;
-              *) seg_all_safe=0 ;;
-            esac
-          fi
-          ;;
-      esac
-    else
-      seg_all_safe=0
-    fi
-  done
-  if [ "$seg_any_unsafe" -eq 1 ]; then RM_VERDICT_UNSAFE=1
-  elif [ "$seg_all_safe" -eq 0 ]; then RM_VERDICT_GENERIC=1
-  fi
-done <<SEGMENTS
-$(printf '%s' "$SCAN_COMMAND" | tr ';&|' '\n\n\n')
-SEGMENTS
-set +f
-
-if [ "$RM_DIRECT_SEEN" -eq 0 ] && echo "$SCAN_COMMAND" | grep -qE "$RM_WORD_REGEX" \
-  && echo "$SCAN_COMMAND" | grep -qE "(^|[[:space:]])--recursive|(^|[[:space:]])-[a-zA-Z]*[rR]" \
-  && echo "$SCAN_COMMAND" | grep -qE "(^|[[:space:]])--force|(^|[[:space:]])-[a-zA-Z]*f"; then
-  # Unsafe wins over the allowlist here: a safe word elsewhere in the line must never
-  # legitimise an absolute/home/parent target we can also see.
-  if echo "$SCAN_COMMAND" | grep -qE "$UNSAFE_TARGET_REGEX"; then
-    RM_VERDICT_UNSAFE=1
-  elif ! echo "$SCAN_COMMAND" | grep -qE "$SAFE_DELETE_REGEX"; then
-    RM_VERDICT_GENERIC=1
-  fi
-fi
-
-if [ "$RM_VERDICT_UNSAFE" -eq 1 ]; then
-  emit_dangerous_decision "Unsafe delete target detected; recursive force-delete could cause irreversible damage. UKit defers this to a human decision."
-elif [ "$RM_VERDICT_GENERIC" -eq 1 ]; then
-  emit_dangerous_decision "Recursive force-delete outside safe cleanup targets (dist/build/coverage/.next/.nuxt/.turbo/tmp/.cache/node_modules) is destructive. UKit defers this to a human decision."
-fi
-
-exit 0
+exit "$NODE_RC"

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

@@ -0,0 +1,141 @@
+// record-execution.mjs — C40 TASK-004 dual-mode port of record-execution.sh
+// (SPEC §FR-004, §8): persist session-scoped source/write/verification receipts
+// through ukit/runtime/execution-ledger.mjs.
+//
+//   * `runHook(ctx)` — in-proc chain step. ctx = { payload, payloadText,
+//     projectRoot, env, deadlineMs, signal } -> { code, stdout, stderr }.
+//     ADVISORY: always code 0. A missing/failed runtime announces the same
+//     "runtime script failed — run: ukit install" systemMessage the .sh emits —
+//     loud, never a silent pass. In-proc mode collapses the .sh's separate
+//     "missing" vs "failed" branches into the "failed" message (an import that
+//     cannot find the module IS a failed runtime; deliberate parity note).
+//   * `isDirectRun()` CLI mode — the .sh thin wrapper execs
+//     `node record-execution.mjs` with the env contract INPUT_FILE,
+//     PROJECT_ROOT, UKIT_HOOK_DEADLINE_MS, UKIT_HARNESS (`--record` accepted
+//     for symmetry with the ledger's own CLI).
+//
+// Sweep-failure routing (FR-004): while this step runs it installs
+// setLedgerMessageEmitter so a sampled exec-ledger dir-sweep failure lands in
+// the returned stdout instead of fd 1 (which would corrupt the runner's
+// verdict channel). The emitter is always reset in `finally`.
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+export const hookFailClosed = false;
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_LEDGER_PATH = path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'execution-ledger.mjs');
+
+// Byte-pinned parity with the .sh's `STATUS != 0` branch.
+const RUNTIME_FAILED =
+  '{"systemMessage":"UKit record execution: runtime script failed — run: ukit install"}\n';
+
+function parsePayload(rawInput) {
+  try {
+    const parsed = JSON.parse(rawInput);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Shared advisory body for both modes. `rawInput` that fails to parse is a
+// silent pass — identical to the .sh piping garbage into `node … --record`,
+// which JSON.parse-falls back to `{}` and early-returns on the missing
+// tool_name.
+async function record({ rawInput, projectRoot, env, signal, deadlineMs }) {
+  const payload = parsePayload(rawInput) ?? {};
+  const ledgerPath = env.UKIT_EXECUTION_LEDGER_PATH || DEFAULT_LEDGER_PATH;
+  let ledger;
+  try {
+    ledger = await import(pathToFileURL(ledgerPath).href);
+  } catch {
+    return { code: 0, stdout: RUNTIME_FAILED, stderr: '' };
+  }
+  if (typeof ledger.recordExecutionReceipt !== 'function') {
+    return { code: 0, stdout: RUNTIME_FAILED, stderr: '' };
+  }
+
+  const emitted = [];
+  const emit = (line) => emitted.push(line);
+  if (typeof ledger.setLedgerMessageEmitter === 'function') {
+    ledger.setLedgerMessageEmitter(emit);
+  }
+  try {
+    await ledger.recordExecutionReceipt({
+      projectRoot,
+      payload,
+      toolName: payload.tool_name,
+      harness: env.UKIT_HARNESS || 'claude-code',
+      signal,
+      deadlineMs,
+    });
+  } catch {
+    return { code: 0, stdout: RUNTIME_FAILED, stderr: '' };
+  } finally {
+    if (typeof ledger.setLedgerMessageEmitter === 'function') {
+      ledger.setLedgerMessageEmitter(null);
+    }
+  }
+  return { code: 0, stdout: emitted.join(''), stderr: '' };
+}
+
+// --- SPEC §8 chain-step entry ------------------------------------------------
+export async function runHook(ctx) {
+  const env = (ctx && ctx.env) || {};
+  const projectRoot = (ctx && ctx.projectRoot) || env.PROJECT_ROOT || process.cwd();
+  let rawInput;
+  try {
+    rawInput =
+      typeof (ctx && ctx.payloadText) === 'string' && ctx.payloadText.length > 0
+        ? ctx.payloadText
+        : JSON.stringify((ctx && ctx.payload) ?? {});
+  } catch {
+    rawInput = '{}';
+  }
+  return record({
+    rawInput,
+    projectRoot,
+    env,
+    signal: ctx && ctx.signal,
+    deadlineMs: ctx && ctx.deadlineMs,
+  });
+}
+
+// --- direct-run CLI mode (the .sh thin wrapper's target) ---------------------
+export function isDirectRun() {
+  try {
+    const invoked = process.argv[1] ? fs.realpathSync(process.argv[1]) : '';
+    const self = fs.realpathSync(fileURLToPath(import.meta.url));
+    return invoked === self;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const env = process.env;
+  let rawInput = '';
+  try {
+    rawInput = await fsp.readFile(env.INPUT_FILE || '', 'utf8');
+  } catch {
+    // No staged payload — silent advisory pass, same as an unreadable INPUT.
+  }
+  const projectRoot = env.PROJECT_ROOT || process.cwd();
+  const verdict = await record({ rawInput, projectRoot, env });
+  if (verdict.stdout) process.stdout.write(verdict.stdout);
+  process.exit(0);
+}
+
+if (isDirectRun()) {
+  main().catch(() => {
+    // Advisory hook: even a catastrophic error exits 0 with the loud message.
+    try {
+      process.stdout.write(RUNTIME_FAILED);
+    } catch { /* stdout already gone */ }
+    process.exit(0);
+  });
+}

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

@@ -1,8 +1,17 @@
 #!/bin/bash
 # PostToolUse hook: persist session-scoped source/write/verification receipts.
 # ADVISORY ONLY — always exit 0. A missing or failing runtime must be loud, not a silent pass.
+#
+# C40 TASK-004 (SPEC §FR-004, §14): thin wrapper — stdin staging + env, then
+# delegate to record-execution.mjs (single source of truth, shared with the
+# in-proc chain step). The .sh used to distinguish "runtime script missing"
+# from "runtime script failed"; the in-proc contract collapses both into the
+# "failed" systemMessage, so this wrapper now emits "failed" for any non-zero
+# node exit (a missing .mjs is a failed runtime too).
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_DIR="$SCRIPT_DIR"
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$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
@@ -58,19 +67,14 @@ else
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
-INPUT="$(cat "$UKIT_INPUT_FILE")"
-PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
-
-if [ ! -f "$SCRIPT" ]; then
-  printf '%s\n' '{"systemMessage":"UKit record execution: runtime script missing — run: ukit install"}'
-  exit 0
-fi
 
-OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --record)
+OUTPUT=$(INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" UKIT_HARNESS="${UKIT_HARNESS:-claude-code}" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$HOOK_DIR/record-execution.mjs")
 STATUS=$?
 
 if [ "$STATUS" -ne 0 ]; then
+  # In-proc parity (SPEC §FR-004): the old "runtime script missing" branch is
+  # folded into "failed" — an .mjs that is absent or crashed is the same
+  # failed-runtime condition, and the module emits this exact line itself.
   printf '%s\n' '{"systemMessage":"UKit record execution: runtime script failed — run: ukit install"}'
   exit 0
 fi
@@ -78,3 +82,4 @@ fi
 if [ -n "$OUTPUT" ]; then
   printf '%s\n' "$OUTPUT"
 fi
+exit 0