@ngockhoale/ukit 2.7.3 → 2.7.5

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);

package/templates/.claude/ukit/runtime/hook-field-salvage.mjs

@@ -0,0 +1,119 @@
+// hook-field-salvage.mjs — recover a JSON string field from truncated payload
+// text. Shared helper (SPEC C40 §FR-007): ports ukit_salvage_tool_field from
+// hook-input.sh so in-proc module steps (sensitive-data-guard.mjs now,
+// block-dangerous.mjs in TASK-003) can salvage a decision-relevant field without
+// spawning the bash salvage path.
+//
+// Contract:
+//   salvageField(text, dotPath) -> { complete: boolean, value: string|null }
+//     complete:true  — the field's string value was fully present: its closing
+//                      quote AND a following `,`/`}` boundary appear before the
+//                      cut; `value` is the JSON-decoded string.
+//     complete:false — unrecoverable: missing key, non-string leaf, cut inside
+//                      the string, EOF right after the quote, malformed prefix.
+//                      `value` is null. Callers map this to fail-closed — a
+//                      partial field is never scanned (a truncated dangerous
+//                      shape could parse benign = fail-open).
+// Single string fields only — this is a salvage step, not a JSON repairer.
+
+const isWs = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r';
+const skipWs = (s, i) => {
+  while (i < s.length && isWs(s[i])) i += 1;
+  return i;
+};
+
+// End index of the string literal starting at `start` (which must be `"`), or -1
+// when the string is cut before its closing quote.
+const scanStringEnd = (s, start) => {
+  for (let i = start + 1; i < s.length; i += 1) {
+    const c = s[i];
+    if (c === '\\') {
+      i += 1;
+      continue;
+    }
+    if (c === '"') return i;
+  }
+  return -1;
+};
+
+// Closing brace matching the `{` at `open` (string-aware), or -1 if unclosed.
+const matchBrace = (s, open) => {
+  let depth = 0;
+  for (let i = open; i < s.length; i += 1) {
+    const c = s[i];
+    if (c === '"') {
+      const end = scanStringEnd(s, i);
+      if (end === -1) return -1;
+      i = end;
+      continue;
+    }
+    if (c === '{') depth += 1;
+    else if (c === '}') {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+};
+
+// Find `"key"` used as an object key inside region [lo, hi); returns the index
+// of its `:` or -1. A bare `"key"` inside a string value cannot produce this
+// shape (its quotes are escaped), and non-key uses lack the `:` — both are
+// skipped by scanning forward.
+const findKey = (s, key, lo, hi) => {
+  const needle = `"${key}"`;
+  let pos = s.indexOf(needle, lo);
+  while (pos !== -1 && pos < hi) {
+    const colon = skipWs(s, pos + needle.length);
+    if (colon < hi && colon < s.length && s[colon] === ':') {
+      const prev = pos - 1;
+      const pc = prev >= 0 ? s[prev] : '';
+      if (prev < 0 || pc === '{' || pc === ',' || isWs(pc)) return colon;
+    }
+    pos = s.indexOf(needle, pos + 1);
+  }
+  return -1;
+};
+
+const INCOMPLETE = { complete: false, value: null };
+
+export function salvageField(text, dotPath) {
+  const data = typeof text === 'string' ? text : '';
+  const dotted = String(dotPath || '')
+    .split('.')
+    .filter(Boolean);
+  if (!data || data[0] !== '{' || dotted.length === 0 || dotted.length > 4) return INCOMPLETE;
+
+  let regionLo = 0;
+  let regionHi = data.length;
+  for (let k = 0; k < dotted.length; k += 1) {
+    const colon = findKey(data, dotted[k], regionLo, regionHi);
+    if (colon === -1) return INCOMPLETE;
+    const vstart = skipWs(data, colon + 1);
+    if (vstart >= data.length) return INCOMPLETE;
+    const last = k === dotted.length - 1;
+    const c = data[vstart];
+    if (!last) {
+      if (c !== '{') return INCOMPLETE;
+      const close = matchBrace(data, vstart);
+      // An unclosed parent object still bounds the search to what arrived; the
+      // leaf's own boundary proof below decides completeness.
+      regionLo = vstart + 1;
+      regionHi = close === -1 ? data.length : close;
+      continue;
+    }
+    if (c !== '"') return INCOMPLETE; // string fields only
+    const end = scanStringEnd(data, vstart);
+    if (end === -1) return INCOMPLETE; // cut inside the value — never trust a partial field
+    const after = skipWs(data, end + 1);
+    if (after >= data.length) return INCOMPLETE; // closed quote but no boundary proof — err closed
+    const boundary = data[after];
+    if (boundary !== ',' && boundary !== '}') return INCOMPLETE;
+    try {
+      return { complete: true, value: JSON.parse(data.slice(vstart, end + 1)) };
+    } catch {
+      return INCOMPLETE;
+    }
+  }
+  return INCOMPLETE;
+}

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -32,7 +32,7 @@ import { resolveChainExecTimeoutMs } from '../../../.claude/ukit/runtime/hook-ch
 
 export const HOOK_EVENT_MAP = {
   tool_call: {
-    'Read|Grep|Glob': ['sensitive-data-guard.sh'],
+    'Read|Grep|Glob': ['sensitive-data-guard.mjs'],
     'Edit|Write': [
       'protect-files.sh',
       'stale-spec-guard.sh',
@@ -43,19 +43,19 @@ export const HOOK_EVENT_MAP = {
     ],
     Bash: [
       'auto-allow-bash.sh',
-      'block-dangerous.sh',
-      'sensitive-data-guard.sh',
+      'block-dangerous.mjs',
+      'sensitive-data-guard.mjs',
       'handoff-model-guard.sh',
       'context-hardcap-gate.sh',
       'verification-guard.sh',
     ],
   },
   tool_result: {
-    'Read|Grep|Glob': ['record-execution.sh'],
-    'Edit|Write': ['post-edit-verify.sh', 'record-execution.sh', 'task-watchdog.sh'],
-    Bash: ['compress-output.sh', 'record-execution.sh'],
+    'Read|Grep|Glob': ['record-execution.mjs'],
+    'Edit|Write': ['post-edit-verify.sh', 'record-execution.mjs', 'task-watchdog.sh'],
+    Bash: ['compress-output.sh', 'record-execution.mjs'],
   },
-  before_agent_start: ['sensitive-data-guard.sh', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
+  before_agent_start: ['sensitive-data-guard.mjs', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
   'session.compacting': ['reinject-context.sh'],
   session_start: ['project-important.sh', 'auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh'],
 };
@@ -99,12 +99,18 @@ export const FAIL_CLOSED_SCRIPTS = new Set([
   'context-hardcap-gate.sh',
   'block-dangerous.sh',
   'sensitive-data-guard.sh',
+  // TASK-005 (SPEC §FR-008): the three ported hooks now run as in-proc .mjs
+  // module steps; the .sh names stay registered for the thin-wrapper fallback.
+  'block-dangerous.mjs',
+  'sensitive-data-guard.mjs',
 ]);
 
 export const ADVISORY_SCRIPTS = new Set([
   'skill-router.sh',
   'verification-guard.sh',
   'record-execution.sh',
+  // TASK-005: record-execution now runs as an .mjs module step (advisory).
+  'record-execution.mjs',
   'auto-allow-bash.sh',
   'pre-edit-backup.sh',
   'vision-router.sh',
@@ -130,7 +136,9 @@ function classifyFailure(scriptName) {
 // must not create. One deliberate exception: block-dangerous.sh is the gate the user
 // explicitly required to never fail open (destructive-command protection), so a Bash chain
 // whose dangerous-command check timed out stays blocked with the honest reason.
-const TIMEOUT_STAYS_CLOSED = new Set(['block-dangerous.sh']);
+// TASK-005: block-dangerous runs as an .mjs module step now — both names stay
+// closed (the .sh thin wrapper is still invocable as a fallback path).
+const TIMEOUT_STAYS_CLOSED = new Set(['block-dangerous.sh', 'block-dangerous.mjs']);
 
 // TASK-018: the hook-chain-runner's failure taxonomy. Infrastructure outcomes
 // (overflow / timeout / signal / budget-exhausted) produced NO verdict, so their
@@ -272,11 +280,11 @@ function translateExecResult(scriptName, execResult) {
     // realistic, and that guard fails open. This is deliberate anti-freeze policy:
     // a guard that produced NO verdict is an infrastructure event, and blocking on
     // it froze every Edit|Write whenever the machine was slow. Only
-    // block-dangerous.sh stays closed (TIMEOUT_STAYS_CLOSED) because destructive-
+    // block-dangerous (.sh/.mjs) stays closed (TIMEOUT_STAYS_CLOSED) because destructive-
     // command protection was explicitly required to never fail open. Stated in the
     // warning so a skipped guard is never a silent one.
     const failOpenTradeOff = FAIL_CLOSED_SCRIPTS.has(scriptName) && !TIMEOUT_STAYS_CLOSED.has(scriptName)
-      ? ` ${scriptName} is a fail-closed guard, but a guard that never produced a verdict is treated as "could not verify" rather than a block — the deliberate anti-freeze trade-off for infrastructure events; only block-dangerous.sh stays closed.`
+      ? ` ${scriptName} is a fail-closed guard, but a guard that never produced a verdict is treated as "could not verify" rather than a block — the deliberate anti-freeze trade-off for infrastructure events; only block-dangerous (.sh/.mjs) stays closed.`
       : '';
     return {
       block: false,
@@ -590,11 +598,11 @@ export async function runScriptChain(
     recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
     // TASK-031: a staged payload that was lost or corrupted mid-chain voids every
     // verdict below it. Chains that must not fail open on an unverifiable verdict
-    // (Edit|Write transport policy, and block-dangerous.sh's never-fail-open rule)
+    // (Edit|Write transport policy, and block-dangerous's never-fail-open rule)
     // stay closed; everything else fails open loudly. Neither reason carries any
     // payload content — only the classification and byte count.
     const payloadStaysClosed = payloadProbe !== null
-      && (failClosedOnTransportError || scripts.includes('block-dangerous.sh'));
+      && (failClosedOnTransportError || scripts.includes('block-dangerous.sh') || scripts.includes('block-dangerous.mjs'));
     if (payloadStaysClosed) {
       const integrityReason = `UKit hook payload transport failed: the staged payload file was `
         + `${payloadProbe === 'missing' ? 'removed' : 'truncated'} before the chain could read it `