@ngockhoale/ukit 2.7.4 → 2.7.5

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

@@ -126,359 +126,7 @@ else
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
 
-INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" SCRIPT_PATH="$SCRIPT_PATH" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" UKIT_SALVAGE_ACTIVE="${UKIT_SALVAGE_ACTIVE:-0}" UKIT_SALVAGED_EVENT="${UKIT_SALVAGED_EVENT:-}" UKIT_SALVAGED_TOOL_NAME="${UKIT_SALVAGED_TOOL_NAME:-}" UKIT_SALVAGED_FIELD_NAME="${UKIT_SALVAGED_FIELD_NAME:-}" UKIT_SALVAGED_FIELD_VALUE="${UKIT_SALVAGED_FIELD_VALUE:-}" node <<'NODE'
-const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
-// BUG-C21-03 (chosen posture: FAIL-CLOSED, parity with the staging refusal):
-// a wedged scan must never pass an uninspected payload. The deadline emits a
-// redacted §8 degrade reason and exits 2 — never a silent exit-0 pass.
-setTimeout(() => {
-  try {
-    process.stdout.write(`${JSON.stringify({
-      systemMessage: 'UKit sensitive-data gate timed out before finishing its scan; blocked fail-closed rather than pass an uninspected payload.',
-    })}\n`);
-  } catch {}
-  try {
-    // stderr mirror: piped stdout is async and process.exit() can truncate the
-    // pending write — without this the block can arrive with no visible reason.
-    process.stderr.write('BLOCKED (sensitive data gate): scan timed out; blocked fail-closed rather than pass an uninspected payload.\n');
-  } catch {}
-  process.exit(2);
-}, HOOK_DEADLINE_MS).unref();
-const fs = require('fs');
-const fsp = fs.promises;
-const path = require('path');
-const { createHash } = require('crypto');
-
-// BUG-C21-04: every fs call below is async — a sync read on a stalled mount
-// parks the event loop and the deadline above could never fire.
-void (async () => {
-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' && !Array.isArray(parsed) ? parsed : {};
-  } catch {
-    return {};
-  }
-})();
-
-// TASK-003: on the degraded path the staged prefix cannot parse, so the shell
-// handed us the provably-COMPLETE salvaged fields — reconstruct just enough
-// payload for the normal channel scan below.
-if (process.env.UKIT_SALVAGE_ACTIVE === '1' && process.env.UKIT_SALVAGED_EVENT) {
-  payload.hook_event_name = process.env.UKIT_SALVAGED_EVENT;
-  if (process.env.UKIT_SALVAGED_EVENT === 'PreToolUse' && process.env.UKIT_SALVAGED_TOOL_NAME) {
-    payload.tool_name = process.env.UKIT_SALVAGED_TOOL_NAME;
-    payload.tool_input = {};
-    if (process.env.UKIT_SALVAGED_FIELD_NAME) {
-      payload.tool_input[process.env.UKIT_SALVAGED_FIELD_NAME] = process.env.UKIT_SALVAGED_FIELD_VALUE;
-    }
-  } else if (process.env.UKIT_SALVAGED_EVENT === 'UserPromptSubmit') {
-    payload.prompt = process.env.UKIT_SALVAGED_FIELD_VALUE;
-  }
-}
-
-const projectRoot = process.env.PROJECT_ROOT || process.cwd();
-
-async function readJsonSafe(filePath, fallback) {
-  try {
-    return JSON.parse(await fsp.readFile(filePath, 'utf8'));
-  } catch {
-    return fallback;
-  }
-}
-
-const config = await readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), null);
-if (config && config.security && config.security.sensitiveDataGate === false) {
-  process.exit(0);
-}
-
-const allowlist = (await readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'security', 'allowlist.json'), null)) || {};
-const allowedValueHashes = new Set(
-  Array.isArray(allowlist.values) ? allowlist.values.filter((v) => typeof v === 'string') : [],
-);
-const allowedPaths = Array.isArray(allowlist.paths) ? allowlist.paths.filter((p) => typeof p === 'string') : [];
-
-function sha256(value) {
-  return createHash('sha256').update(value).digest('hex');
-}
-
-function pathAllowed(filePath) {
-  const normalized = String(filePath).replace(/\\/g, '/').trim();
-  let relative = normalized;
-  try {
-    relative = path.relative(projectRoot, normalized);
-  } catch {
-    // keep normalized
-  }
-  return allowedPaths.some((allowed) => allowed === normalized || allowed === relative);
-}
-
-// --- high-confidence secret value scan (TASK-039: shared runtime module) ---
-// The token-pattern definitions and matching live in the shared runtime
-// module ukit/runtime/sensitive-value-scanner.mjs (manifest requires:
-// ukit-runtime-scripts) — there is deliberately NO local pattern copy here, so
-// the hook and the PROJECT_IMPORTANT renderer can never drift apart. File/path
-// classification and Bash command shapes stay in this hook.
-// Leak-safety: the scanner returns labels only — never a value, excerpt, or
-// hash — so blocked-prompt previews can no longer print a value's truncated
-// sha256; the redacted block message says the value is withheld instead.
-const SCANNER_PATH = process.env.SCRIPT_PATH || '';
-let scannerModule = null;
-let scannerTried = false;
-async function loadScanner() {
-  if (scannerTried) return scannerModule;
-  scannerTried = true;
-  try {
-    const { pathToFileURL } = require('url');
-    scannerModule = await import(pathToFileURL(SCANNER_PATH).href);
-  } catch {
-    scannerModule = null;
-  }
-  return scannerModule;
-}
-
-// The gate is fail-closed on detection AND on scanner availability: a missing
-// or crashing scanner must never silently bypass a channel that could carry a
-// secret (the module is shipped by ukit-runtime-scripts, which the manifest
-// declares this hook requires). Same redacted block shape as a detection.
-function blockScannerUnavailable() {
-  process.stderr.write(
-    'BLOCKED (sensitive data gate unavailable): the shared scanner module '
-    + 'ukit/runtime/sensitive-value-scanner.mjs is missing or failed to load, '
-    + 'so this payload cannot be proven clean. Run `ukit install` to restore it.\n',
-  );
-  process.stdout.write(`${JSON.stringify({
-    systemMessage: 'UKit blocked this call: the sensitive-data scanner module is unavailable (fail-closed). Run `ukit install`.',
-  })}\n`);
-  process.exit(2);
-}
-
-// --- secret file classification ---
-function classifySecretFile(filePath) {
-  if (typeof filePath !== 'string' || !filePath.trim()) return null;
-  const normalized = filePath.replace(/\\/g, '/').trim();
-  const rawBase = normalized.split('/').pop();
-  if (!rawBase) return null;
-  const base = rawBase.toLowerCase();
-  if (base.endsWith('.env.example')) return null;
-  if (base === '.env' || base.startsWith('.env.')) return 'dotenv/secret env file';
-  if (base.endsWith('.pub') || base.endsWith('.public')) return null;
-  if (/^id_(rsa|dsa|ecdsa|ed25519)(\.|$)/.test(base)) return 'SSH private key';
-  if (/\.(pem|key|p12|pfx|keystore|jks)$/.test(base)) return 'key/certificate file';
-  if (/^credentials\.(json|ya?ml|txt|ini)$/.test(base)) return 'credentials file';
-  if (/^service[_-]?account.*\.json$/.test(base)) return 'service-account key file';
-  if (base === '.npmrc' || base === '.netrc' || base === '.htpasswd') return 'credentials file';
-  if (/^secrets?\.(json|ya?ml|txt|ini|env)$/.test(base)) return 'secrets file';
-  if (/(^|\/)\.aws\/credentials$/i.test(normalized)) return 'AWS credentials file';
-  return null;
-}
-
-// --- bash command shapes that dump secrets ---
-const DUMP_VERBS = new Set([
-  'cat', 'head', 'tail', 'less', 'more', 'zless', 'zcat', 'xxd', 'strings',
-  'base64', 'od', 'hexdump', 'bat', 'grep', 'egrep', 'fgrep', 'rg', 'awk', 'sed',
-]);
-
-function scanBashShapes(command) {
-  const found = [];
-  const segments = command.split(/\|\||&&|;|\||\n/);
-  for (const rawSegment of segments) {
-    const segment = rawSegment.trim();
-    if (!segment) continue;
-    const tokens = segment.split(/\s+/);
-    const head = tokens[0].replace(/^["']+|["']+$/g, '');
-
-    if ((head === 'env' || head === 'printenv' || head === 'history') && tokens.length === 1) {
-      found.push({ label: `bare \`${head}\` dumps environment/history (may contain tokens)`, value: segment });
-      continue;
-    }
-    if (head === 'export' && (tokens[1] === '-p' || tokens[1] === '--print')) {
-      found.push({ label: 'bare `export -p` dumps all environment variables', value: segment });
-      continue;
-    }
-
-    if (DUMP_VERBS.has(head)) {
-      for (const token of tokens.slice(1)) {
-        const cleaned = token.replace(/^["']+|["',:]+$/g, '');
-        const kind = classifySecretFile(cleaned);
-        if (kind && !pathAllowed(cleaned)) {
-          found.push({ label: `${head} reads ${kind}`, value: cleaned, isPath: true });
-        }
-      }
-    }
-
-    // `-u/--user user:pass` is only credentials on tools that authenticate with it.
-    // The same flag shape on docker/runuser/chown (`--user 1000:1000`, a uid:gid pair)
-    // is NOT a secret — matching it anyway false-positives every containerised test run.
-    const headBase = head.replace(/^.*\//, '');
-    const CRED_USER_TOOLS = new Set(['curl', 'wget', 'ftp', 'lftp', 'aria2c', 'http', 'https']);
-    const inlineUser = /(^|\s)(-u|--user)\s+["']?([^\s"':]+):([^\s"']+)/.exec(segment);
-    if (inlineUser && CRED_USER_TOOLS.has(headBase)) {
-      // Even on credential tools, a purely numeric pair is a uid:gid, not a password.
-      const numericIds = /^\d+$/.test(inlineUser[3]) && /^\d+$/.test(inlineUser[4]);
-      if (!numericIds) {
-        found.push({ label: 'curl/wget inline credentials (-u user:password)', value: segment });
-      }
-    }
-    if (/https?:\/\/[^\s/@'"]+:[^\s/@'"]+@/.test(segment)) {
-      found.push({ label: 'URL with embedded credentials (user:pass@host)', value: segment });
-    }
-  }
-  return found;
-}
-
-// --- channel wiring ---
-const event = String(payload.hook_event_name || '');
-const toolName = String(payload.tool_name || '');
-const toolInput = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
-
-const textChannels = [];
-const filePathChannels = [];
-let bashCommand = null;
-
-if (event === 'UserPromptSubmit') {
-  const prompt = [payload.prompt, payload.user_prompt, payload.text].find(
-    (candidate) => typeof candidate === 'string' && candidate.trim(),
-  );
-  if (prompt) textChannels.push({ channel: 'prompt', text: prompt });
-} else if (event === 'PreToolUse') {
-  if (toolName === 'Read' && typeof toolInput.file_path === 'string') {
-    filePathChannels.push(toolInput.file_path);
-  } else if (toolName === 'Grep') {
-    if (typeof toolInput.path === 'string' && toolInput.path.trim()) filePathChannels.push(toolInput.path);
-    if (typeof toolInput.pattern === 'string') textChannels.push({ channel: 'grep pattern', text: toolInput.pattern });
-  } else if (toolName === 'Bash' && typeof toolInput.command === 'string') {
-    bashCommand = toolInput.command;
-  }
-} else {
-  process.exit(0);
-}
-
-// --- collect findings (async: the value scan delegates to the shared module) ---
-void (async () => {
-const findings = [];
-
-for (const filePath of filePathChannels) {
-  const kind = classifySecretFile(filePath);
-  if (kind && !pathAllowed(filePath)) {
-    findings.push({ label: `Read of ${kind}`, preview: filePath, hashSource: filePath });
-  }
-}
-
-// The value scan needs the shared scanner module only when a text/bash
-// channel exists to scan; a pure secret-file Read verdict never depends on it.
-const needsScanner = textChannels.length > 0 || bashCommand;
-let scanner = null;
-if (needsScanner) {
-  scanner = await loadScanner();
-  if (!scanner || typeof scanner.scanText !== 'function') {
-    blockScannerUnavailable();
-  }
-}
-const gateEnabled = scanner ? scanner.isSensitiveDataGateEnabled(config) !== false : true;
-const allowlistHashes = scanner ? scanner.loadSensitiveAllowlist({ security: { allowlist } }) : [];
-
-function scanTextLabels(text) {
-  let verdict;
-  try {
-    verdict = scanner.scanText(text, { allowlistHashes, gateEnabled });
-  } catch {
-    blockScannerUnavailable();
-  }
-  return verdict && Array.isArray(verdict.labels) ? verdict.labels : [];
-}
-
-const seenLabels = new Set();
-for (const { channel, text } of textChannels) {
-  for (const label of scanTextLabels(text)) {
-    const key = `${channel}:${label}`;
-    if (seenLabels.has(key)) continue;
-    seenLabels.add(key);
-    findings.push({ label: `${label} in ${channel}` });
-  }
-}
-
-if (bashCommand) {
-  for (const finding of scanBashShapes(bashCommand)) {
-    if (finding.isPath) {
-      findings.push({ label: `bash command touches ${finding.label}`, preview: finding.value });
-      continue;
-    }
-    if (allowedValueHashes.has(sha256(finding.value))) continue;
-    findings.push({ label: `${finding.label} in bash command`, value: finding.value });
-  }
-  for (const label of scanTextLabels(bashCommand)) {
-    const key = `bash:${label}`;
-    if (seenLabels.has(key)) continue;
-    seenLabels.add(key);
-    findings.push({ label: `${label} in bash command` });
-  }
-}
-
-if (findings.length === 0) {
-  process.exit(0);
-}
-
-// --- machine-generated envelope lane (UserPromptSubmit only) ---
-// Harness plumbing (<task-notification>, <system-reminder>,
-// <cross-session-message>) legitimately carries fixture/log content through
-// the prompt channel — test tokens quoted in task bodies, CI logs, agent
-// results. Blocking it silently drops the notification and stalls pipelines
-// ("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 = /^(?: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 && 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.`,
-  })}\n`);
-  process.exit(0);
-}
-
-// --- block message: redacted previews only, never the secret itself ---
-// The shared scanner returns labels only, so value findings can no longer show
-// a truncated sha256 — the value stays withheld entirely (leak-safe contract).
-function describeFinding(finding) {
-  const where = finding.preview ? `${finding.preview}` : '(value withheld)';
-  return `  - ${finding.label}: ${where}`;
-}
-
-const lines = [
-  `BLOCKED (sensitive data): ${findings.length} potential secret(s) detected. Nothing was sent to the AI.`,
-  ...findings.map(describeFinding),
-  'Detection is format-true only: a match must itself be a vendor-formatted key,',
-  'a private key block, a JWT, or a credentials file. Code, prose, hashes and',
-  'encoded blobs are not blocked. To proceed, the USER can choose one of:',
-  '  1. Redact the secret (placeholder like <API_KEY>) and retry.',
-  '  2. Approve it explicitly: add the full sha256 (shasum -a 256 of the value) or the file path',
-  '     to .ukit/storage/security/allowlist.json — that file is protected from AI edits.',
-  '  3. Disable the gate: security.sensitiveDataGate=false in .ukit/storage/config.json (not recommended).',
-  'Never repeat or guess the detected value in your reply. Ask the user instead.',
-];
-process.stderr.write(`${lines.join('\n')}\n`);
-// stderr reaches the model; the user needs a stop reason they can actually see. Emit a
-// structured systemMessage (redacted — labels only, never the matched value) so a
-// sensitive-data block never looks like a silent stall in the UI.
-process.stdout.write(`${JSON.stringify({
-  systemMessage: `UKit blocked this call: ${findings.length} potential secret(s) detected (${findings.map((f) => f.label).slice(0, 3).join('; ')}${findings.length > 3 ? '; …' : ''}). Redact the value, allowlist its sha256, or ask the user to decide.`,
-})}\n`);
-process.exit(2);
-})();
-})();
-NODE
-
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" SCRIPT_PATH="$SCRIPT_PATH" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" UKIT_SALVAGE_ACTIVE="${UKIT_SALVAGE_ACTIVE:-0}" UKIT_SALVAGED_EVENT="${UKIT_SALVAGED_EVENT:-}" UKIT_SALVAGED_TOOL_NAME="${UKIT_SALVAGED_TOOL_NAME:-}" UKIT_SALVAGED_FIELD_NAME="${UKIT_SALVAGED_FIELD_NAME:-}" UKIT_SALVAGED_FIELD_VALUE="${UKIT_SALVAGED_FIELD_VALUE:-}" node "$HOOK_DIR/sensitive-data-guard.mjs"
 NODE_RC=$?
 # BUG-C21-03: a node crash (any non-blocking non-zero exit) means the payload
 # was never fully scanned — fail-closed parity: announce + block, never a

package/templates/.claude/settings.json

@@ -65,7 +65,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\":8",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.mjs\":8",
             "timeout": 18
           }
         ]
@@ -85,7 +85,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-allow-bash.sh\":15 \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/verification-guard.sh\":8",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-allow-bash.sh\":15 \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/verification-guard.sh\":8",
             "timeout": 65
           }
         ]
@@ -97,7 +97,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\":8",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.mjs\":8",
             "timeout": 18
           }
         ]
@@ -107,7 +107,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\":8",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\":8",
             "timeout": 34
           }
         ]
@@ -117,7 +117,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\":8",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.mjs\":8",
             "timeout": 30
           }
         ]
@@ -128,7 +128,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\":20 \"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-window-guard.sh\":10",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.mjs\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\":20 \"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-window-guard.sh\":10",
             "timeout": 60
           }
         ]

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -209,14 +209,30 @@ export async function sweepExecLedgerDir(dir, {
 // bound. Announce the first failure and then every 25th, C22 rate-limit
 // posture. writeSync(1) because a same-tick exit can drop a buffered write.
 let sweepFailureCount = 0;
+// TASK-004 (C40, SPEC §FR-004): in-proc chain steps must never write fd 1 —
+// their messages have to travel back through the step's returned stdout so the
+// runner routes them into the right channel. record-execution.mjs sets this
+// emitter for the duration of its call and resets it in `finally`; when unset,
+// the legacy writeSync(1) posture is unchanged for .sh/CLI callers.
+let ledgerMessageEmitter = null;
+export function setLedgerMessageEmitter(fn) {
+  ledgerMessageEmitter = typeof fn === 'function' ? fn : null;
+}
 export function noteSweepFailure(error) {
   sweepFailureCount += 1;
   if (sweepFailureCount !== 1 && sweepFailureCount % 25 !== 0) return null;
   const message =
     `UKit execution-ledger: dir sweep failed (${sweepFailureCount} failure(s) so far) — `
     + `the committed event is safe but the backlog bound may lag. Cause: ${error?.message || error}`;
+  const line = `${JSON.stringify({ systemMessage: message })}\n`;
+  if (ledgerMessageEmitter) {
+    try {
+      ledgerMessageEmitter(line);
+    } catch { /* an emitter failure never loses the ledger event */ }
+    return message;
+  }
   try {
-    fsSync.writeSync(1, `${JSON.stringify({ systemMessage: message })}\n`);
+    fsSync.writeSync(1, line);
   } catch { /* stdout already gone */ }
   return message;
 }

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -2,13 +2,14 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 // TASK-016: children run through the process-tree runner instead of bare
 // spawnSync — a timed-out child is TERM→KILLed as a whole POSIX process group,
 // so a bash wrapper can no longer orphan the Node grandchildren it spawned.
 import { runHookProcess } from './hook-process.mjs';
 // TASK-019: chain rows and direct-hook rows share one versioned schema and one
 // append API (hook-telemetry.mjs) — including safeName for session files.
-import { appendTelemetryRow, TELEMETRY_VERSION } from './hook-telemetry.mjs';
+import { appendTelemetryRow, recordHookTiming, TELEMETRY_VERSION } from './hook-telemetry.mjs';
 // TASK-018 review fix round 1: the chain budget is resolved by ONE shared module
 // so the runner's inner deadline and the bridge's outer pi.exec timeout can never
 // disagree. Kept as a per-run resolution (not module constants) so an operator's
@@ -26,6 +27,12 @@ const FAIL_CLOSED_SCRIPTS = new Set([
   'handoff-model-guard.sh',
   'context-hardcap-gate.sh',
   'block-dangerous.sh',
+  // TASK-001 (SPEC §FR-002): in-proc module steps join the fail-closed registry.
+  // The runner's static set is authoritative for .mjs steps — an import that
+  // never finishes cannot declare `hookFailClosed`. Basenames only; the `:N`
+  // suffix is stripped before lookup by the same parser used for .sh args.
+  'sensitive-data-guard.mjs',
+  'block-dangerous.mjs',
 ]);
 
 const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
@@ -110,6 +117,67 @@ function parseScriptArg(arg) {
   return { scriptPath: match[1], timeoutMs: Math.round(seconds * 1000) };
 }
 
+// TASK-001 (SPEC §FR-001, §8): a chain arg ending in `.mjs` is an IN-PROC step —
+// `await import()` + `mod.runHook(ctx)` instead of a spawned child. The result
+// is shaped like a hook-process result so `chainFailureKind` and the results[]
+// entry stay identical: throw → failureKind 'error'; deadline → 'deadline' →
+// 'timeout'. The deadline is enforced by Promise.race + AbortSignal; the
+// rejection race keeps running in the background (in-proc code cannot be
+// SIGKILLed) but its late return value is discarded.
+async function runModuleStep({ scriptPath, payload, payloadText, projectRoot, env, deadlineMs }) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve({ failureKind: 'deadline' });
+    }, Math.max(1, deadlineMs));
+  });
+  const invoke = (async () => {
+    // FR-001: module-level self-deadlines that call process.exit must never arm
+    // inside the runner — scrub the env var before the import executes module
+    // top-level code AND from the ctx.env the step inspects. The deadline is
+    // passed explicitly via ctx.deadlineMs/ctx.signal.
+    const scrubbed = 'UKIT_HOOK_DEADLINE_MS' in process.env
+      ? process.env.UKIT_HOOK_DEADLINE_MS : undefined;
+    delete process.env.UKIT_HOOK_DEADLINE_MS;
+    try {
+      const mod = await import(pathToFileURL(scriptPath).href);
+      const childEnv = { ...env };
+      delete childEnv.UKIT_HOOK_DEADLINE_MS;
+      const out = await mod.runHook({
+        payload,
+        payloadText,
+        projectRoot,
+        env: childEnv,
+        deadlineMs,
+        signal: controller.signal,
+      });
+      return {
+        code: Number.isFinite(out?.code) ? out.code : 1,
+        stdout: typeof out?.stdout === 'string' ? out.stdout : '',
+        stderr: typeof out?.stderr === 'string' ? out.stderr : '',
+      };
+    } finally {
+      // Skip the restore once this step was aborted: the race already returned,
+      // so this finally can run while the NEXT step is mid-import — restoring
+      // the var then would arm that module's top-level self-deadline inside the
+      // runner. Every step re-scrubs before its own import, so leaking the
+      // deletion is safe.
+      if (scrubbed !== undefined && !controller.signal.aborted) {
+        process.env.UKIT_HOOK_DEADLINE_MS = scrubbed;
+      }
+    }
+  })();
+  try {
+    return await Promise.race([invoke, timeout]);
+  } catch (error) {
+    return { failureKind: 'error', stderr: error?.message || String(error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
   const parsedArgs = scriptArgs.map(parseScriptArg);
   const scriptPaths = parsedArgs.map((a) => a.scriptPath);
@@ -176,28 +244,47 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
     }
 
     const childStartedAt = Date.now();
-    const result = await runHookProcess({
-      command: scriptPath,
-      deadlineMs: Math.min(childBudgetsMs[scriptIndex], remainingMs),
-      args: [],
-      input: payloadText,
-      maxBuffer: MAX_BUFFER_BYTES,
-      cwd: projectRoot,
-      // TASK-223 (HK-401): mark chain-spawned children so their structured
-      // permission decisions keep the omp contract (stdout parsed on exit 2).
-      // Direct Claude Code invocations carry no marker and exit 0 instead —
-      // a non-zero exit there discards stdout, killing the decision JSON.
-      env: {
-        ...process.env,
-        CLAUDE_PROJECT_DIR: projectRoot,
-        // TASK-234: the marker selects the omp structured-decision contract
-        // (ask + exit 2). Under --emit-verdict the runner replays the direct
-        // Claude contract (deny + exit 0), so children must NOT see it.
-        ...(chainMarker ? { UKIT_HOOK_CHAIN_RUNNER: '1' } : {}),
-      },
-    });
+    const stepEnv = {
+      ...process.env,
+      CLAUDE_PROJECT_DIR: projectRoot,
+      // TASK-234: the marker selects the omp structured-decision contract
+      // (ask + exit 2). Under --emit-verdict the runner replays the direct
+      // Claude contract (deny + exit 0), so children must NOT see it.
+      ...(chainMarker ? { UKIT_HOOK_CHAIN_RUNNER: '1' } : {}),
+    };
+    const stepDeadlineMs = Math.min(childBudgetsMs[scriptIndex], remainingMs);
+    // TASK-001: `.mjs` args run in-proc via runHook(ctx); `.sh` stays a child
+    // process. Both paths share deadline/budget, results[] shape, and break
+    // conditions.
+    const result = scriptPath.endsWith('.mjs')
+      ? await runModuleStep({
+          scriptPath,
+          payload,
+          payloadText,
+          projectRoot,
+          env: stepEnv,
+          deadlineMs: stepDeadlineMs,
+        })
+      : await runHookProcess({
+          command: scriptPath,
+          deadlineMs: stepDeadlineMs,
+          args: [],
+          input: payloadText,
+          maxBuffer: MAX_BUFFER_BYTES,
+          cwd: projectRoot,
+          // TASK-223 (HK-401): mark chain-spawned children so their structured
+          // permission decisions keep the omp contract (stdout parsed on
+          // exit 2). Direct Claude Code invocations carry no marker and exit 0
+          // instead — a non-zero exit there discards stdout, killing the
+          // decision JSON.
+          env: stepEnv,
+        });
     const failureKind = chainFailureKind(result);
-    const code = Number.isFinite(result.code) ? result.code : 1;
+    // FR-001: on infra failure (error/timeout — no module verdict) the result
+    // code is 2 when the step is fail-closed, else 1.
+    const code = Number.isFinite(result.code)
+      ? result.code
+      : (FAIL_CLOSED_SCRIPTS.has(scriptName) ? 2 : 1);
     // `killed` keeps its old meaning for the bridge: the child was stopped before
     // a natural exit. The DISTINCT cause lives in failureKind — an overflowing
     // child is no longer reported as a generic kill or a timeout.
@@ -218,6 +305,22 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
       elapsedMs: Date.now() - childStartedAt,
     });
 
+    // TASK-001 (FR-003): `.sh` children write their own hook-latency row via
+    // hook-telemetry.sh --finish; in-proc `.mjs` steps cannot — the runner
+    // emits the equivalent row per module step (hook = basename incl. `.mjs`).
+    if (scriptPath.endsWith('.mjs')) {
+      recordHookTiming({
+        projectRoot,
+        sessionId: payload?.session_id,
+        event: payload?.hook_event_name || null,
+        tool: payload?.tool_name || null,
+        toolUseId: payload?.tool_use_id || null,
+        hook: scriptName,
+        elapsedMs: Date.now() - childStartedAt,
+        outcome: failureKind,
+      });
+    }
+
     if (code === 2 || killed || (code !== 0 && FAIL_CLOSED_SCRIPTS.has(scriptName))) {
       break;
     }
@@ -371,15 +474,20 @@ try {
     } else {
       const lastIsFailClosed = FAIL_CLOSED_SCRIPTS.has(last.scriptName);
       const lastFailedToVerdict = last.killed || last.failureKind === 'error' || last.failureKind === 'budget-exhausted';
-      if (last.code === 2) {
+      // Check failed-to-verdict BEFORE `last.code === 2`: infra failures on a
+      // fail-closed step now synthesize code 2, so a killed gate would
+      // otherwise take the plain code-2 branch and lose the "(<failureKind>)"
+      // diagnostic. A REAL code 2 has no killed/error/budget failureKind, so
+      // the reorder can't misroute a legitimate block.
+      if (lastIsFailClosed && lastFailedToVerdict) {
         if (contextStdout) process.stdout.write(contextStdout);
-        if (last.stdout) process.stdout.write(last.stdout);
         if (last.stderr) process.stderr.write(last.stderr);
+        else process.stderr.write(`UKit fail-closed hook ${last.scriptName} could not produce a verdict (${last.failureKind})\n`);
         process.exitCode = 2;
-      } else if (lastIsFailClosed && lastFailedToVerdict) {
+      } else if (last.code === 2) {
         if (contextStdout) process.stdout.write(contextStdout);
+        if (last.stdout) process.stdout.write(last.stdout);
         if (last.stderr) process.stderr.write(last.stderr);
-        else process.stderr.write(`UKit fail-closed hook ${last.scriptName} could not produce a verdict (${last.failureKind})\n`);
         process.exitCode = 2;
       } else {
         if (contextStdout) process.stdout.write(contextStdout);