@ngockhoale/ukit 2.4.0 → 2.4.2

package/templates/.claude/ukit/index/refresh-index.mjs

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import {
   buildCodeIndex,
-  isIndexStale,
+  inspectIndexStaleness,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
   getIndexArtifactGeneratedAt,
 } from './lib/index-core.mjs';
@@ -14,9 +14,10 @@ const changedFiles = changedArg ? changedArg.split(',').map((x) => x.trim()).fil
 const force = args.includes('--force');
 
 const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
-const stale = force
-  ? true
-  : await isIndexStale({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS, generatedAtMs: lastRefreshMs });
+const staleness = force
+  ? null
+  : await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS, generatedAtMs: lastRefreshMs });
+const stale = force || staleness.stale;
 
 if (!stale) {
   console.log('[ukit:index:refresh] skipped (cache fresh)');
@@ -28,7 +29,11 @@ if (!stale) {
   }
   console.log(`root: ${rootDir}`);
 } else {
-  const summary = await buildCodeIndex({ rootDir });
+  // Reuse the staleness check's discovery snapshot: one enumeration per refresh.
+  const summary = await buildCodeIndex({
+    rootDir,
+    discoverySnapshot: staleness ? staleness.snapshot : null,
+  });
 
   console.log('[ukit:index:refresh] completed');
   if (lastRefreshMs !== null) {

package/templates/.claude/ukit/index/stale-spec-check.mjs

@@ -13,6 +13,14 @@ import {
   summarizeSnippet,
 } from '../runtime/safe-patch-core.mjs';
 
+// Hook-context self-deadline (2.4.1 orphan-leak class): the stale-spec-guard hook passes
+// UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
+// budget. Non-hook usage never sets it and is never self-killed.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
+if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
+  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+}
+
 function getToolName(payload = {}) {
   return String(payload.tool_name || payload.tool || payload.name || '').trim();
 }

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

@@ -7,6 +7,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { withFileLock } from './token-utils.mjs';
 
+// Hook-context self-deadline (2.4.1 orphan-leak class): wrapper hooks pass
+// UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the
+// hook budget. CLI usage never sets it and is never self-killed.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
+if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
+  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+}
+
 const LEDGER_VERSION = 1;
 const RESUME_INTENT_VERSION = 1;
 const RESUME_INTENT_TTL_MS = 30 * 60 * 1000;

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

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// hook-input.mjs — canonical bounded stdin transport for UKit hooks (H01).
+//
+// readHookInput({ maxBytes, overflowPolicy, stdin }) ->
+//   Promise<{ text, truncated, tempPath }>
+//
+// Policies: 'truncate' | 'temp-file' | 'refuse' (throws HookInputOverflow
+// after draining stdin, so producers never see EPIPE).
+//
+// CLI form stages stdin to --out and prints one JSON report line:
+//   node hook-input.mjs --max-bytes 2097152 --policy truncate --out /tmp/staged
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+
+export class HookInputOverflow extends Error {
+  constructor(maxBytes) {
+    super(`hook stdin exceeds ${maxBytes} bytes`);
+    this.name = 'HookInputOverflow';
+    this.maxBytes = maxBytes;
+  }
+}
+
+export async function readHookInput({
+  maxBytes = 2 * 1024 * 1024,
+  overflowPolicy = 'truncate',
+  stdin = process.stdin,
+  tempRoot = os.tmpdir(),
+} = {}) {
+  const chunks = [];
+  let total = 0;
+  let truncated = false;
+  let overflow = false;
+  for await (const chunk of stdin) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    if (truncated || overflow) continue;
+    if (total + buf.length > maxBytes) {
+      if (overflowPolicy === 'refuse') {
+        overflow = true;
+        continue;
+      }
+      const keep = maxBytes - total;
+      if (keep > 0) chunks.push(buf.subarray(0, keep));
+      truncated = true;
+      continue;
+    }
+    total += buf.length;
+    chunks.push(buf);
+  }
+  if (overflow) throw new HookInputOverflow(maxBytes);
+  const body = Buffer.concat(chunks);
+  let tempPath = null;
+  if (overflowPolicy === 'temp-file') {
+    const dir = fs.mkdtempSync(path.join(tempRoot, 'ukit-hook-in.'));
+    tempPath = path.join(dir, 'payload');
+    fs.writeFileSync(tempPath, body);
+  }
+  return { text: body.toString('utf8'), truncated, tempPath };
+}
+
+function parseArgs(argv) {
+  const parsed = { maxBytes: 2 * 1024 * 1024, policy: 'truncate', out: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--max-bytes') parsed.maxBytes = Number.parseInt(argv[++i], 10);
+    else if (arg === '--policy') parsed.policy = argv[++i];
+    else if (arg === '--out') parsed.out = argv[++i];
+  }
+  if (!['truncate', 'temp-file', 'refuse'].includes(parsed.policy)) {
+    throw new Error(`unknown overflow policy: ${parsed.policy}`);
+  }
+  if (!Number.isFinite(parsed.maxBytes) || parsed.maxBytes <= 0) {
+    throw new Error(`invalid --max-bytes: ${parsed.maxBytes}`);
+  }
+  return parsed;
+}
+
+async function cli(argv) {
+  const { maxBytes, policy, out } = parseArgs(argv);
+  let result;
+  try {
+    result = await readHookInput({ maxBytes, overflowPolicy: policy });
+  } catch (error) {
+    if (error instanceof HookInputOverflow) {
+      process.stderr.write(`${error.message} (policy: refuse)\n`);
+      return 2;
+    }
+    throw error;
+  }
+  if (out) fs.writeFileSync(out, result.text, 'utf8');
+  process.stdout.write(
+    `${JSON.stringify({
+      bytes: Buffer.byteLength(result.text),
+      truncated: result.truncated,
+      tempPath: result.tempPath,
+    })}\n`,
+  );
+  return 0;
+}
+
+const isMain = (() => {
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  cli(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (error) => {
+      process.stderr.write(`hook-input: ${error?.message ?? error}\n`);
+      process.exit(1);
+    },
+  );
+}

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

@@ -0,0 +1,60 @@
+# hook-input.sh — bounded stdin staging for UKit hook wrappers.
+#
+# H01 fix: wrappers must never materialize unbounded stdin in a shell
+# variable before any deadline is armed. Source this file, stage stdin
+# through ukit_stage_hook_input, then hand UKIT_INPUT_FILE (a path, never
+# the payload) to Node or read a bounded view via command substitution.
+#
+# Usage:
+#   source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh"
+#   trap ukit_cleanup_hook_input EXIT
+#   ukit_stage_hook_input 2097152 truncate || exit 0
+#
+# Policies:
+#   truncate  — keep at most max_bytes; UKIT_INPUT_TRUNCATED=1 on overflow
+#   temp-file — same bound; the staged file is the payload transport
+#   refuse    — return 2 without staging when stdin exceeds max_bytes
+#
+# refuse is reserved for fail-closed security hooks (sensitive-data-guard):
+# it returns 2 silently and never echoes payload bytes.
+
+ukit_stage_hook_input() {
+  local max_bytes="$1" policy="${2:-truncate}"
+  local dir file size
+  dir="$(mktemp -d "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")" || return 1
+  file="$dir/payload"
+  head -c $((max_bytes + 1)) > "$file" 2>/dev/null
+  # Drain the remainder so the producer never sees EPIPE; discarded bytes
+  # are never materialized.
+  cat > /dev/null 2>&1 || true
+  size="$(wc -c < "$file" | tr -d '[:space:]')"
+  UKIT_INPUT_TRUNCATED=0
+  if [ "$size" -gt "$max_bytes" ]; then
+    case "$policy" in
+      refuse)
+        rm -rf "$dir"
+        UKIT_INPUT_FILE=""
+        return 2
+        ;;
+      truncate|temp-file)
+        truncate -s "$max_bytes" "$file" 2>/dev/null || { rm -rf "$dir"; return 1; }
+        UKIT_INPUT_TRUNCATED=1
+        ;;
+      *)
+        rm -rf "$dir"
+        return 1
+        ;;
+    esac
+  fi
+  UKIT_INPUT_FILE="$file"
+  return 0
+}
+
+ukit_cleanup_hook_input() {
+  if [ -n "${UKIT_INPUT_FILE:-}" ] && [ -f "$UKIT_INPUT_FILE" ]; then
+    rm -f "$UKIT_INPUT_FILE"
+    rmdir "$(dirname "$UKIT_INPUT_FILE")" 2>/dev/null || true
+  fi
+  UKIT_INPUT_FILE=""
+  UKIT_INPUT_TRUNCATED=0
+}

package/templates/.claude/ukit/runtime/output-compression.mjs

@@ -16,6 +16,14 @@ import {
 } from './token-utils.mjs';
 import { updateCompactPressureFromOutput } from './compact-threshold.mjs';
 
+// Hook-context self-deadline (2.4.1 orphan-leak class): the compress-output hook passes
+// UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
+// budget. Non-hook usage never sets it and is never self-killed.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
+if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
+  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+}
+
 const ANSI_RE = /\u001b\[[0-9;]*m/g;
 const DEFAULT_MAX_OUTPUT_TOKENS = 180;
 const DEFAULT_OUTPUT_HISTORY_MAX_ENTRIES = 25;

package/templates/.claude/ukit/runtime/reinject-context.mjs

@@ -19,6 +19,14 @@ import {
   writeThresholdCompactPlan,
 } from './compact-threshold.mjs';
 
+// Hook-context self-deadline (2.4.1 orphan-leak class): the reinject-context hook passes
+// UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
+// budget. Non-hook usage never sets it and is never self-killed.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
+if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
+  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+}
+
 const STATE_TTL_MS = 30 * 60 * 1000;
 const STOPWORDS = new Set([
   'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',

package/templates/.claude/ukit/runtime/transcript-tail.mjs

@@ -0,0 +1,107 @@
+// transcript-tail.mjs — bounded, reverse-safe JSONL tail reader (H04).
+//
+// scanTranscriptTail(path, { maxBytes, signal }) ->
+//   Promise<{ entries, truncated, bytesRead }>
+//
+// Why this exists: the context-window-guard hook used to stat/read/split up to 24 MiB of
+// live transcript synchronously on every UserPromptSubmit. This module is the async,
+// hard-capped replacement: seek near the end of the file, read at most `maxBytes`, skip a
+// partial first line, and parse complete records only.
+//
+// Failure posture is FAIL-OPEN, always: concurrent growth/truncation, vanished files,
+// permission errors, and aborts all RESOLVE (with whatever was read, or an empty result)
+// — scanTranscriptTail never throws and never prints a stack trace. Callers are advisory
+// hooks; a lost measurement must never block a prompt.
+
+import fsp from 'node:fs/promises';
+
+// Hard ceiling on bytes read per scan. Well under the old 24 MiB synchronous read, and
+// the same order as compact-threshold.mjs's BOUNDARY_TAIL_BYTES so one number describes
+// a UKit tail scan. No config knob exists for byte caps (compact.hardCapTokens is tokens),
+// so this constant IS the ceiling; tests pin it below 24 MiB.
+export const DEFAULT_TAIL_MAX_BYTES = 4 * 1024 * 1024;
+
+const EMPTY_RESULT = () => ({ entries: [], truncated: false, bytesRead: 0 });
+
+function positiveInteger(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
+async function scanOnce(filePath, maxBytes) {
+  const cap = positiveInteger(maxBytes, DEFAULT_TAIL_MAX_BYTES);
+  const stat = await fsp.stat(filePath);
+  if (!stat.isFile() || stat.size <= 0) {
+    return EMPTY_RESULT();
+  }
+  const start = Math.max(0, stat.size - cap);
+  const length = Math.min(cap, stat.size);
+  const truncated = start > 0;
+  const handle = await fsp.open(filePath, 'r');
+  let bytesRead = 0;
+  let text = '';
+  try {
+    const buffer = Buffer.allocUnsafe(length);
+    ({ bytesRead } = await handle.read(buffer, 0, length, start));
+    text = buffer.toString('utf8', 0, bytesRead);
+  } finally {
+    try {
+      await handle.close();
+    } catch { /* a racing writer/truncator may have invalidated the handle already */ }
+  }
+
+  // A tail read almost certainly starts mid-record: drop everything before the first
+  // complete line. If the window holds no newline at all, nothing parseable is in it.
+  let payload = text;
+  if (truncated) {
+    const firstNewline = text.indexOf('\n');
+    if (firstNewline === -1) {
+      return { entries: [], truncated: true, bytesRead };
+    }
+    payload = text.slice(firstNewline + 1);
+  }
+
+  // Parse complete records only; partial or non-JSON lines are skipped, exactly like the
+  // consumers that previously split the raw text did. An unterminated final line that
+  // still parses (writer flushed the record, newline pending) is a complete record.
+  const entries = [];
+  for (const line of payload.split('\n')) {
+    if (!line) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch { /* partial or non-JSON record — skip */ }
+  }
+  return { entries, truncated, bytesRead };
+}
+
+export async function scanTranscriptTail(transcriptPath, { maxBytes, signal } = {}) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) {
+    return EMPTY_RESULT();
+  }
+  if (signal?.aborted) {
+    return EMPTY_RESULT();
+  }
+  // Race the scan against the abort signal so a deadline (e.g. the hook's 3 s
+  // self-deadline) abandons an in-flight read instead of waiting on it.
+  let onAbort;
+  const aborted = new Promise((resolve) => {
+    onAbort = () => resolve(EMPTY_RESULT());
+    try {
+      signal?.addEventListener('abort', onAbort, { once: true });
+    } catch {
+      resolve(EMPTY_RESULT());
+    }
+  });
+  try {
+    return await Promise.race([scanOnce(transcriptPath, maxBytes), aborted]);
+  } catch {
+    // Unreadable transcript (first prompt of a session, permissions, races, aborts).
+    // Nothing to measure; fail open with an empty result.
+    return EMPTY_RESULT();
+  } finally {
+    try {
+      signal?.removeEventListener('abort', onAbort);
+    } catch { /* signal went away between add and remove */ }
+  }
+}