@ngockhoale/ukit 2.4.2 → 2.5.0

package/templates/.claude/ukit/runtime/hook-process.mjs

@@ -0,0 +1,250 @@
+// hook-process.mjs — process-tree-aware child runner for UKit hook chains.
+//
+// TASK-016 (PLAN §2 H03): `spawnSync(..., { timeout })` only signals the DIRECT
+// child. A bash wrapper that timed out that way left every Node grandchild it
+// had spawned alive; the recorded orphan had to be reaped by the harness. This
+// runner closes that gap:
+//   - On POSIX the child is spawned DETACHED, so it leads its own process
+//     group and `kill(-pid)` reaches every descendant, no matter how deep.
+//   - The deadline is a bounded TERM → KILL sequence: group SIGTERM first
+//     (graceful hooks can flush), then — after a bounded grace — group SIGKILL.
+//     A descendant that escapes its group cannot be signalled by this runner, so
+//     the hard-settle backstop destroys the runner-owned streams before resolving;
+//     an escapee can never extend this runner's wall-clock bound.
+//   - The child exiting exactly as the escalation fires is the expected race:
+//     every group signal swallows ESRCH and never turns it into a failure.
+//   - On Windows there are no POSIX process groups; the degradation is
+//     explicit (GROUP_KILL_SUPPORTED=false, direct-child kill only) and never
+//     assumes group semantics.
+//
+// Contract (TASK-016 Interfaces):
+//   runHookProcess({command, args, input, deadlineMs, maxBuffer, ...}) ->
+//     Promise<{code, signal, stdout, stderr, failureKind, elapsedMs}>
+//   failureKind: 'none' | 'deadline' | 'signal' | 'overflow' | 'error'
+//     'deadline' — this runner killed the child because the deadline expired
+//     'signal'   — the child died from a signal this runner did not send
+//     'overflow' — captured output exceeded maxBuffer; the tree was culled
+//     'error'    — the child never spawned (ENOENT and friends)
+
+import { spawn } from 'node:child_process';
+
+// POSIX only. Windows kill() targets the direct child; process groups do not
+// exist there, so pretending otherwise would be a silent, wrong assumption.
+export const GROUP_KILL_SUPPORTED = process.platform !== 'win32';
+
+// Bounded TERM → KILL grace. Long enough for a flush, short enough that a
+// hook chain budget stays predictable.
+export const KILL_GRACE_MS = 500;
+
+// After the KILL escalation the child is expected to die promptly; this hard
+// cap only exists so an unkillable (D-state) child can never hang the chain
+// runner past its own budget.
+const HARD_SETTLE_SLACK_MS = 2000;
+
+/**
+ * Signal a process GROUP by pid (negative-pid kill). Swallows ESRCH — the
+ * child may have exited between arming the timer and this call, or the pid may
+ * simply not be a group leader — and never assumes pid === pgid.
+ * Returns true only when the group signal was delivered.
+ */
+export function signalProcessTree(pid, signal) {
+  if (!GROUP_KILL_SUPPORTED || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ESRCH') return false; // tree already gone — the race is harmless
+    // EPERM / sandbox oddities: fall back to the direct child, still never throw.
+    try {
+      process.kill(pid, signal);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export function runHookProcess({
+  command,
+  args = [],
+  input = '',
+  deadlineMs = 0,
+  maxBuffer = 2 * 1024 * 1024,
+  cwd,
+  env = process.env,
+  graceMs = KILL_GRACE_MS,
+}) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    let child;
+    try {
+      child = spawn(command, args, {
+        cwd,
+        env,
+        // Detached ONLY on POSIX: the child becomes a group leader so the whole
+        // tree dies together. Windows never gets a group assumption.
+        detached: GROUP_KILL_SUPPORTED,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      resolve({
+        code: 1,
+        signal: null,
+        stdout: '',
+        stderr: String(err?.message || err),
+        failureKind: 'error',
+        elapsedMs: Date.now() - startedAt,
+      });
+      return;
+    }
+
+    const pid = child.pid;
+    let settled = false;
+    let deadlineFired = false;
+    let hardSettled = false;
+    let overflowed = false;
+    let spawnError = null;
+    let stdoutBuf = Buffer.alloc(0);
+    let stderrBuf = Buffer.alloc(0);
+    const stdoutRef = { value: stdoutBuf };
+    const stderrRef = { value: stderrBuf };
+    let deadlineTimer = null;
+    let killTimer = null;
+    let hardTimer = null;
+
+    const clearTimers = () => {
+      for (const timer of [deadlineTimer, killTimer, hardTimer]) {
+        if (timer) clearTimeout(timer);
+      }
+    };
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      let code = child.exitCode ?? null;
+      let signal = child.signalCode ?? null;
+      if (spawnError) {
+        code = 1;
+        signal = null;
+      }
+      const failureKind = spawnError
+        ? 'error'
+        : overflowed
+          ? 'overflow'
+          : hardSettled
+            ? 'deadline'
+            : code === null && deadlineFired
+              ? 'deadline'
+              : code === null && signal
+              ? 'signal'
+              : 'none';
+      resolve({
+        code,
+        signal,
+        stdout: stdoutRef.value.toString('utf8'),
+        stderr: stderrRef.value.toString('utf8'),
+        failureKind,
+        elapsedMs: Date.now() - startedAt,
+      });
+    };
+
+    const termTree = () => {
+      if (!signalProcessTree(pid, 'SIGTERM')) {
+        // No group to signal (non-POSIX, or the group is already gone).
+        try {
+          child.kill('SIGTERM');
+        } catch {
+          // already gone
+        }
+      }
+    };
+    const killTree = () => {
+      if (!signalProcessTree(pid, 'SIGKILL')) {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          // already gone
+        }
+      }
+    };
+
+    // Cull the tree the moment output can no longer be honored (spawnSync's
+    // ENOBUFS analogue): overflow is the root cause and wins the classification.
+    const cullOnOverflow = () => {
+      if (overflowed) return;
+      overflowed = true;
+      killTree();
+    };
+
+    const capture = (bufRef, chunk) => {
+      if (overflowed) return;
+      bufRef.value = Buffer.concat([bufRef.value, chunk]);
+      if (bufRef.value.length > maxBuffer) {
+        bufRef.value = bufRef.value.subarray(0, maxBuffer);
+        cullOnOverflow();
+      }
+    };
+
+    child.stdout.on('error', () => {});
+    child.stderr.on('error', () => {});
+    child.stdout.on('data', (chunk) => capture(stdoutRef, chunk));
+    child.stderr.on('data', (chunk) => capture(stderrRef, chunk));
+
+    // A hook may exit without draining stdin (EPIPE) — that is the hook's
+    // choice, never a runner failure.
+    child.stdin.on('error', () => {});
+    if (input) {
+      try {
+        child.stdin.write(input);
+      } catch {
+        // swallowed: mirrored by the stdin 'error' handler above
+      }
+    }
+    child.stdin.end();
+
+    // Bounded TERM → KILL. TERM first so graceful hooks can flush; KILL after
+    // the grace so nothing, however stubborn, survives the deadline. A
+    // non-positive deadlineMs means "no deadline" — the caller opted out, and
+    // no timer is armed at all.
+    const hasDeadline = Number.isFinite(deadlineMs) && deadlineMs > 0;
+
+    if (hasDeadline) {
+      deadlineTimer = setTimeout(() => {
+        deadlineFired = true;
+        termTree();
+        killTimer = setTimeout(killTree, Math.max(0, graceMs));
+      }, deadlineMs);
+
+      // Expected never to fire: close settles first. Kept as the bound that
+      // guarantees the chain runner itself can never hang.
+      hardTimer = setTimeout(() => {
+        // A descendant may have escaped the process group (for example by calling
+        // setsid()) and still hold an inherited stdout/stderr pipe open. SIGKILL on
+        // the original group cannot reach that process, and waiting for `close` would
+        // therefore defeat the wall-clock bound. The runner owns these stream objects:
+        // destroy them before settling so an escaped writer cannot keep this process
+        // alive. The result is deliberately still a deadline failure, not a clean exit.
+        hardSettled = true;
+        killTree();
+        for (const stream of [child.stdin, child.stdout, child.stderr]) {
+          try {
+            stream?.destroy();
+          } catch {
+            // Stream teardown is best-effort; the bounded result must still resolve.
+          }
+        }
+        finish();
+      }, deadlineMs + Math.max(0, graceMs) + HARD_SETTLE_SLACK_MS);
+    }
+
+    child.on('error', (err) => {
+      // Spawn failures (ENOENT and friends) emit 'error' without 'close'.
+      if (!spawnError) spawnError = err;
+      finish();
+    });
+    child.on('close', () => {
+      finish();
+    });
+  });
+}

package/templates/.claude/ukit/runtime/hook-telemetry.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// hook-telemetry.mjs — shared, versioned, redacted hook latency telemetry.
+//
+// TASK-019: direct Claude hooks previously had no per-hook latency rows, so a
+// slow or silent hook was indistinguishable from a gateway stall. This module
+// is the ONE append API for both hook paths:
+//   - OMP rows: hook-chain-runner.mjs (per chain, taxonomy outcomes)
+//   - direct rows: hook-telemetry.sh + the `--finish` CLI below (per hook)
+// Both write `.ukit/storage/cache/hook-latency/<safeName(session)>.jsonl`.
+//
+// Redaction contract: rows are METADATA ONLY. buildTimingRow copies a fixed
+// allowlist of fields — payload bodies, tool_input, stdout/stderr, detected
+// secrets, or any unknown key can never reach a row. Session ids pass through
+// safeName (same sanitizer the chain runner has always used) so a hostile id
+// cannot escape the telemetry directory.
+//
+// Advisory contract: every entry point swallows failures and returns a
+// boolean. Telemetry must never delay, block, or change a hook verdict.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Installed trees are frequently reached through a symlink (macOS /var ->
+// /private/var, /tmp -> /private/tmp, versioned install dirs). Node realpathes
+// import.meta.url but not process.argv[1], so BOTH spellings must match or the
+// --finish CLI silently becomes a no-op — exactly what main-detection is for.
+function invokedAsMain() {
+  if (!process.argv[1]) return false;
+  const argvPath = path.resolve(process.argv[1]);
+  if (import.meta.url === pathToFileURL(argvPath).href) return true;
+  try {
+    return import.meta.url === pathToFileURL(fs.realpathSync(argvPath)).href;
+  } catch {
+    return false;
+  }
+}
+
+export const TELEMETRY_VERSION = 1;
+
+// Per-session file cap (TASK-019 boundary): rotation keeps roughly the newest
+// half whenever an append would overflow. Env-tunable and clamped like the
+// chain budgets (TASK-018) so operators and tests can scale it without
+// editing code; the per-call override wins over the env value.
+const DEFAULT_MAX_BYTES = 512 * 1024;
+const MIN_MAX_BYTES = 1024;
+const MAX_MAX_BYTES = 8 * 1024 * 1024;
+
+function capBytes(override) {
+  const raw = Number(override ?? process.env.UKIT_HOOK_TELEMETRY_MAX_BYTES);
+  if (!Number.isFinite(raw) || raw <= 0) return DEFAULT_MAX_BYTES;
+  return Math.min(MAX_MAX_BYTES, Math.max(MIN_MAX_BYTES, raw));
+}
+
+export function safeName(value) {
+  return String(value || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+}
+
+function shortString(value, limit) {
+  const s = String(value ?? '');
+  return s ? s.slice(0, limit) : null;
+}
+
+function normalizeElapsedMs(value) {
+  if (!Number.isFinite(value)) return null;
+  return Math.max(0, Math.round(value));
+}
+
+// Allowlist builder — the ONLY place row fields are chosen. `elapsedMs` may be
+// null when the caller genuinely could not measure it (e.g. the hook exited
+// before its stdin envelope was staged); unknown stays unknown, never zero.
+export function buildTimingRow(entry = {}) {
+  return {
+    v: TELEMETRY_VERSION,
+    ts: Number.isFinite(entry.ts) ? entry.ts : Date.now(),
+    hookEvent: shortString(entry.event ?? entry.hookEvent, 64),
+    toolName: shortString(entry.tool ?? entry.toolName, 96),
+    toolUseId: shortString(entry.toolUseId, 128),
+    hook: shortString(entry.hook, 128),
+    elapsedMs: normalizeElapsedMs(entry.elapsedMs),
+    outcome: shortString(entry.outcome, 32) || 'ok',
+  };
+}
+
+export function telemetryDirFor(projectRoot) {
+  return path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
+}
+
+// Bounded work on THIS session's file only: stat, at most one read of a file
+// already capped at maxBytes, one rewrite of the kept half. The append path
+// never lists or sweeps the telemetry directory.
+function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
+  let size = 0;
+  try {
+    size = fs.statSync(filePath).size;
+  } catch {
+    return; // first row for this session
+  }
+  if (size + incomingBytes <= maxBytes) return;
+  try {
+    const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+    if (lines.length && lines[lines.length - 1] === '') lines.pop();
+    const keepBudget = Math.floor(maxBytes / 2);
+    const keep = [];
+    let kept = 0;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const lineBytes = Buffer.byteLength(lines[i], 'utf8') + 1;
+      if (kept + lineBytes > keepBudget) break;
+      keep.unshift(lines[i]);
+      kept += lineBytes;
+    }
+    fs.writeFileSync(filePath, keep.length ? `${keep.join('\n')}\n` : '', 'utf8');
+  } catch {
+    // Rotation failed; drop this row rather than grow past the cap.
+  }
+}
+
+export function appendTelemetryRow(projectRoot, sessionId, row, options = {}) {
+  try {
+    if (!row || typeof row !== 'object') return false;
+    const dir = telemetryDirFor(projectRoot);
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${safeName(sessionId)}.jsonl`);
+    const line = `${JSON.stringify(row)}\n`;
+    rotateIfNeeded(filePath, Buffer.byteLength(line, 'utf8'), capBytes(options.maxBytes));
+    fs.appendFileSync(filePath, line, 'utf8');
+    return true;
+  } catch {
+    // Advisory: an unwritable or corrupt telemetry target must never alter a
+    // hook's verdict, output, or exit status.
+    return false;
+  }
+}
+
+export function recordHookTiming({
+  sessionId,
+  event,
+  tool,
+  hook,
+  elapsedMs,
+  outcome,
+  toolUseId,
+  ts,
+  projectRoot,
+  maxBytes,
+} = {}) {
+  const row = buildTimingRow({ ts, event, tool, toolUseId, hook, elapsedMs, outcome });
+  const root = projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return appendTelemetryRow(root, sessionId, row, { maxBytes });
+}
+
+// --- `--finish` CLI: one short-lived node process per direct hook exit ------
+// Invoked by ukit_hook_telemetry_finish (hook-telemetry.sh) from the shared
+// cleanup path in hook-input.sh, while the staged payload file still exists.
+
+const FINISH_PARSE_LIMIT = 2 * 1024 * 1024; // all hooks except record-execution stage <= 2 MiB
+const FINISH_HEAD_BYTES = 256 * 1024; // bounded head scan for oversized payloads
+
+function pickEnvelope(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return {};
+  return {
+    session_id: payload.session_id,
+    hook_event_name: payload.hook_event_name,
+    tool_name: payload.tool_name,
+    tool_use_id: payload.tool_use_id,
+  };
+}
+
+// Strict shape: a value containing escapes or quotes never partially matches.
+function envelopeField(head, name) {
+  const match = head.match(new RegExp(`"${name}"\\s*:\\s*"([^"\\\\]{1,128})"`));
+  return match ? match[1] : undefined;
+}
+
+function envelopeFromHead(inputFile, bytes) {
+  let head = '';
+  try {
+    const fd = fs.openSync(inputFile, 'r');
+    try {
+      const buf = Buffer.alloc(Math.min(bytes, fs.fstatSync(fd).size));
+      if (buf.length > 0) {
+        const read = fs.readSync(fd, buf, 0, buf.length, 0);
+        head = buf.subarray(0, read).toString('utf8');
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return {};
+  }
+  return {
+    session_id: envelopeField(head, 'session_id'),
+    hook_event_name: envelopeField(head, 'hook_event_name'),
+    tool_name: envelopeField(head, 'tool_name'),
+    tool_use_id: envelopeField(head, 'tool_use_id'),
+  };
+}
+
+// Full parse keeps metadata exact for normal payloads; oversized payloads
+// (record-execution stages up to 32 MiB) stay off the finish path via the
+// bounded head scan. Both paths feed the same allowlisted fields.
+function readEnvelope(inputFile) {
+  let size = 0;
+  try {
+    size = fs.statSync(inputFile).size;
+  } catch {
+    return {};
+  }
+  if (size > FINISH_PARSE_LIMIT) return envelopeFromHead(inputFile, FINISH_HEAD_BYTES);
+  try {
+    return pickEnvelope(JSON.parse(fs.readFileSync(inputFile, 'utf8')));
+  } catch {
+    return envelopeFromHead(inputFile, FINISH_HEAD_BYTES);
+  }
+}
+
+function finishMain() {
+  try {
+    // process.uptime() covers this spawn itself so the row measures the hook,
+    // not the telemetry process startup.
+    const spawnOverheadMs = process.uptime() * 1000;
+    const inputFile = process.env.UKIT_INPUT_FILE || '';
+    let startMs = null;
+    if (inputFile) {
+      try {
+        startMs = fs.statSync(inputFile).mtimeMs;
+      } catch {
+        startMs = null; // envelope never staged (refuse path) — unknown, not zero
+      }
+    }
+    const envelope = inputFile ? readEnvelope(inputFile) : {};
+    const rc = Number.parseInt(process.env.UKIT_TEL_RC ?? '', 10);
+    // The wrapper resolves PROJECT_ROOT before arming; fall back to the hook
+    // env's CLAUDE_PROJECT_DIR, then cwd (same resolution as the wrappers).
+    recordHookTiming({
+      projectRoot: process.env.PROJECT_ROOT || process.env.CLAUDE_PROJECT_DIR || undefined,
+      sessionId: envelope.session_id,
+      event: envelope.hook_event_name,
+      tool: envelope.tool_name,
+      toolUseId: envelope.tool_use_id,
+      hook: process.env.UKIT_TEL_HOOK,
+      elapsedMs: startMs === null ? null : Date.now() - startMs - spawnOverheadMs,
+      // Direct rows reuse the chain taxonomy (TASK-018): a non-zero exit is a
+      // verdict ('exit-code'), not a guess. Timeout/overflow kills bypass the
+      // EXIT trap, so those kinds stay chain-runner-reported.
+      outcome: rc === 0 ? 'ok' : 'exit-code',
+    });
+  } catch {
+    // Advisory — never surface anything on the hook's stderr.
+  }
+}
+
+if (invokedAsMain()) {
+  if (process.argv[2] === '--finish') finishMain();
+}

package/templates/.claude/ukit/runtime/hook-telemetry.sh

@@ -0,0 +1,60 @@
+# hook-telemetry.sh — advisory direct-hook latency telemetry (TASK-019).
+#
+# Sourced by hook wrappers right after hook-input.sh, INSIDE the successful
+# source branch. Arming is free: no clock is read here — the staged payload
+# file's mtime is the envelope start marker, and hook-telemetry.mjs derives
+# elapsedMs from it at finish time.
+#
+# The finish marker flows through the shared runner exit path: hook-input.sh's
+# ukit_cleanup_hook_input (already the single EXIT trap target in every
+# wrapper) calls ukit_hook_telemetry_finish BEFORE deleting the staged
+# payload. Finish spawns at most one bounded node process, discards all output,
+# and never changes the hook's exit status or verdict.
+#
+# Missing runtime (pre-install tree) simply leaves telemetry off: wrappers
+# source this file with `|| true` and the armed flag stays unset.
+
+UKIT_TEL_ARMED=1
+UKIT_TEL_HOOK="$(basename "${BASH_SOURCE[1]:-$0}")"
+UKIT_TEL_RUNTIME_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+ukit_hook_telemetry_finish() {
+  # The hook's exit status arrives via UKIT_TEL_RC (ukit_cleanup_hook_input
+  # captured it before its own conditionals could reset $?); $? is only the
+  # fallback for direct debug invocation.
+  local rc="${UKIT_TEL_RC:-$?}"
+  command -v node >/dev/null 2>&1 || return 0
+  # UKIT_INPUT_FILE is a plain shell variable (never exported), so the staged
+  # payload path — and through it the envelope start mtime — is passed here
+  # explicitly, exactly like the wrappers pass it to their own node heredocs.
+  # The telemetry child is advisory and must never make the hook's EXIT trap
+  # unbounded. Use a portable background watchdog rather than `timeout`, which
+  # is not available on a stock macOS install. SIGKILL is intentional: the
+  # child has no hook verdict to preserve, and a wedged filesystem call may not
+  # yield to a graceful signal. The child only writes telemetry, so killing it
+  # after the deadline loses at most this row.
+  local timeout_ms timeout_s child watchdog
+  timeout_ms="${UKIT_HOOK_TELEMETRY_TIMEOUT_MS:-250}"
+  case "$timeout_ms" in
+    ''|*[!0-9]*) timeout_ms=250 ;;
+  esac
+  [ "$timeout_ms" -gt 0 ] 2>/dev/null || timeout_ms=250
+  [ "$timeout_ms" -le 1000 ] 2>/dev/null || timeout_ms=1000
+  printf -v timeout_s '%d.%03d' $((timeout_ms / 1000)) $((timeout_ms % 1000))
+
+  UKIT_TEL_RC="$rc" \
+  UKIT_TEL_HOOK="$UKIT_TEL_HOOK" \
+  UKIT_INPUT_FILE="${UKIT_INPUT_FILE:-}" \
+  PROJECT_ROOT="${PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-}}" \
+    node "$UKIT_TEL_RUNTIME_DIR/hook-telemetry.mjs" --finish </dev/null >/dev/null 2>&1 &
+  child=$!
+  (
+    sleep "$timeout_s" 2>/dev/null
+    kill -9 "$child" 2>/dev/null
+  ) <&- >/dev/null 2>&1 &
+  watchdog=$!
+  if wait "$child" 2>/dev/null; then :; fi
+  kill "$watchdog" 2>/dev/null || true
+  if wait "$watchdog" 2>/dev/null; then :; fi
+  return 0
+}