@ngockhoale/ukit 2.7.3 → 2.7.5

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 All notable changes to UKit are documented here.
 
+## 2.7.5 - 2026-09-20
+
+Hook performance work — cycle C40 (TASK-001..007): `.mjs` module steps,
+fail-closed registry, and a hook budget guard.
+
+- `hook-chain-runner` supports `"<path>.mjs[:N]"` module steps: the arg is
+  imported in-proc and its `runHook(ctx)` is invoked with
+  `{payload, payloadText, projectRoot, env, deadlineMs, signal}` — no child
+  process spawn on the hot path. A throw reports `error`, a
+  `deadlineMs`/`AbortSignal` breach reports `timeout` + `killed`; infra
+  failures exit 2 when the step is fail-closed, else 1. Every step appends a
+  `recordHookTiming` telemetry row under its `<name>.mjs` hook name, and
+  `UKIT_HOOK_DEADLINE_MS` is scrubbed from `process.env`/`ctx.env` around the
+  import so a stale host deadline cannot leak into module steps.
+- Fail-closed registry extended: `sensitive-data-guard.mjs` and
+  `block-dangerous.mjs` join `FAIL_CLOSED_SCRIPTS`, so module-step verdicts
+  keep the same fail-closed posture as the `.sh` wrappers they replaced.
+- `sensitive-data-guard`, `block-dangerous`, and `record-execution` ported to
+  dual-mode modules: each `.mjs` exports `runHook(ctx)` for chain execution
+  plus an `isDirectRun()` CLI path for standalone/debug invocation;
+  `hookFailClosed` is exported per module (`true` for the two gates, `false`
+  for the telemetry sink). The `.sh` files remain as thin wrappers — staging,
+  salvage glue (`UKIT_SALVAGED_*` env), telemetry, then a single
+  `node <module>.mjs` call — with byte-identical verdicts verified against the
+  pre-port implementations. `record-execution.mjs` also exposes
+  `setLedgerMessageEmitter` on `execution-ledger.mjs` so in-proc runs route
+  the `noteSweepFailure` systemMessage through the emitter instead of fd 1.
+- Settings + bridge wiring: `settings.json` chains and the omp bridge
+  `HOOK_EVENT_MAP` now point at the `.mjs` steps; the bridge's
+  `TIMEOUT_STAYS_CLOSED` / payload-stays-closed checks cover
+  `block-dangerous.mjs` so verdicts stay identical after the swap.
+- Hook budget guard: `tests/hooks/hookChainBudget.test.js` enforces ≤8 chain
+  steps per group, requires a `:N` suffix on every `.sh|mjs` arg, and pins
+  outer `timeout` ≥ Σ(:N) + 10s — adding or removing a hook without updating
+  the outer fails loudly. The same suite asserts the settings↔bridge mirror
+  1:1 for every event/matcher lane. The contract is documented under
+  `UKIT_INTERNALS.md → Hook budget`.
+
+## 2.7.4 - 2026-09-20
+
+Deferred hook findings + residual risks — cycle C39 (TASK-001..005).
+
+- `session-episode.sh` held-stdin stall fixed twice over: gate-first
+  ordering — a pre-staging node probe evaluates
+  `learning.episodes.autoWrite === true`; gate off / missing / corrupt
+  config or absent node exits 0 immediately without touching stdin
+  (~2084ms → ~14–40ms). The gate-on staged-read + `ukit memory episode`
+  flow is unchanged. The gate probe itself is armed with an unref'd
+  `UKIT_HOOK_DEADLINE_MS` deadline (default 2s → exit 0, gate-off safe
+  default) so a wedged probe can never re-create the stall it prevents.
+- SessionEnd residual spawn cost (`chain-sessionend-all`) resolved: the
+  background watchdog subshell in `session-episode.sh` inherited the
+  child's stdout/stderr pipes, blocking captured-stdio callers ~2s after
+  script exit. Watchdog now detaches stdio (`>/dev/null 2>&1 &`) —
+  residual 2050ms → ~40ms median; telemetry, per-script `:N` budgets,
+  and fail-open posture preserved.
+- Regression guard `chainTimeoutSuffixes`: every `"<path>.sh":N` budget
+  suffix in template + installed `settings.json` is pinned against the
+  script's original standalone timeout — drift in either direction
+  (wrong N or missing suffix) fails the suite.
+- `ukit doctor` gains a `Hook-chain checks` section
+  (`src/core/hookChainDoctor.js`): bounded scan of recent
+  `hook-latency/*.jsonl` rows reports fail-closed outcomes
+  (timeout/error) as an advisory warning with remedy — never blocks,
+  exit code untouched.
+
 ## 2.7.3 - 2026-09-20
 
 AI freeze audit remediation — cycle C38 (TASK-001..007).

package/manifests/platform.full.yaml

@@ -1096,6 +1096,20 @@ items:
     packs:
       - core
 
+  # TASK-004 (C40): advisory module the thin .sh wrapper delegates to and the
+  # chain runner loads in-proc.
+  - id: hook-record-execution-module
+    type: hook
+    sourceTemplate: .claude/hooks/record-execution.mjs
+    targetPath: .claude/hooks/record-execution.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-completion-gate
     type: hook
     sourceTemplate: .claude/hooks/completion-gate.sh
@@ -1141,6 +1155,20 @@ items:
     packs:
       - core
 
+  # TASK-003 (C40): fail-closed module the thin .sh wrapper delegates to and
+  # the chain runner loads in-proc.
+  - id: hook-block-dangerous-module
+    type: hook
+    sourceTemplate: .claude/hooks/block-dangerous.mjs
+    targetPath: .claude/hooks/block-dangerous.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   # requires: [ukit-runtime-scripts] is forward-declared for the shared sensitive-value
   # scanner (consumed by the guard once TASK-039 wires it). The guard is fail-closed, so
   # its runtime dependency must be installed first — keeps the ordering posture explicit.
@@ -1156,6 +1184,21 @@ items:
     packs:
       - core
 
+  # TASK-002 (C40): dual-mode module the thin .sh wrapper delegates to and the
+  # chain runner loads in-proc. Requires ukit-runtime-scripts for the scanner
+  # AND hook-field-salvage.mjs (both ship via that directory item).
+  - id: hook-sensitive-data-guard-module
+    type: hook
+    sourceTemplate: .claude/hooks/sensitive-data-guard.mjs
+    targetPath: .claude/hooks/sensitive-data-guard.mjs
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-handoff-model-guard
     type: hook
     sourceTemplate: .claude/hooks/handoff-model-guard.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.7.3",
+  "version": "2.7.5",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/doctor.js

@@ -25,6 +25,7 @@ import {
 import { runDocContractChecks } from '../../core/docContracts.js';
 import { inspectUnattendedMode } from '../../core/unattendedDoctor.js';
 import { inspectPermissions } from '../../core/permissionDoctor.js';
+import { inspectHookChainHealth } from '../../core/hookChainDoctor.js';
 import { findOpencodeArtifacts, opencodeSteerMessage } from '../../core/opencodeSteer.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
@@ -316,6 +317,19 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   const permissionReport = await inspectPermissions({ projectRoot, ompPath });
   printPermissionSection(permissionReport, { verbose: argv.includes('--permissions') });
 
+  // TASK-004 / FR-005 — hook-chain failure-taxonomy watch. Advisory only:
+  // warnings render as ✗ + (warning) but never enter the blocking set below.
+  const hookChainHealth = await inspectHookChainHealth({ projectRoot });
+  console.log('[UKit] Hook-chain checks:');
+  {
+    const sev = hookChainHealth.severity === 'warning' ? ' (warning)' : hookChainHealth.severity === 'info' ? ' (info)' : '';
+    console.log(`[UKit]   ${ok(hookChainHealth.passed)}  ${hookChainHealth.label}${sev}`);
+    if (hookChainHealth.detail) console.log(`[UKit]      detail: ${hookChainHealth.detail}`);
+    if (hookChainHealth.remedy && (!hookChainHealth.passed || hookChainHealth.severity === 'warning')) {
+      console.log(`[UKit]      remedy: ${hookChainHealth.remedy}`);
+    }
+  }
+
   if (runtimeConfigInspection.errors.length > 0) {
     console.log(`[UKit] Runtime config issues: ${runtimeConfigInspection.errors.join(' | ')}`);
   }

package/src/core/hookChainDoctor.js

@@ -0,0 +1,149 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+// TASK-004 / SPEC §FR-005 — production-facing watch over the chain-runner
+// failure taxonomy (report §7 residual risk). Scans recent
+// `.ukit/storage/cache/hook-latency/*.jsonl` rows for `hook-chain-runner`
+// entries and reports non-`ok` outcomes by failureKind.
+//
+// Posture: ADVISORY ONLY. A warning never enters doctor's blocking set —
+// missing/clean telemetry is a pass, non-ok outcomes surface as
+// severity:'warning' so doctor.js prints ✗ + (warning) without flipping the
+// exit code (same convention as permissionDoctor drift checks).
+
+const WINDOW_MS = 24 * 60 * 60 * 1000; // last 24h of telemetry files
+const MAX_FILES = 32; // newest session files by mtime
+const MAX_ROWS = 5000; // total rows parsed across all files
+const MAX_BYTES_PER_FILE = 512 * 1024; // tail-read bound per file
+const CHAIN_HOOK = 'hook-chain-runner';
+
+// Row outcomes that mean a fail-closed gate tripped or a child script died.
+const FAILURE_OUTCOMES = new Set([
+  'timeout',
+  'budget-exhausted',
+  'output-overflow',
+  'error',
+  'signal',
+]);
+
+function telemetryDirFor(projectRoot) {
+  return path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
+}
+
+async function recentTelemetryFiles(dir, now) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return []; // dir absent — unknown, not failure
+  }
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+    const filePath = path.join(dir, entry.name);
+    try {
+      const stat = await fs.stat(filePath);
+      candidates.push({ filePath, mtimeMs: stat.mtimeMs, size: stat.size });
+    } catch {
+      // vanished between readdir/stat — skip
+    }
+  }
+  // Bound: only files touched inside the window, newest first, capped.
+  return candidates
+    .filter((f) => now - f.mtimeMs <= WINDOW_MS)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(0, MAX_FILES);
+}
+
+async function tailLines(filePath, size) {
+  const handle = await fs.open(filePath, 'r');
+  try {
+    const length = Math.min(size, MAX_BYTES_PER_FILE);
+    const start = Math.max(0, size - length);
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, start);
+    let text = buffer.toString('utf8');
+    if (start > 0) {
+      // Drop the first (probably partial) line of a tail-read.
+      const nl = text.indexOf('\n');
+      text = nl >= 0 ? text.slice(nl + 1) : '';
+    }
+    return text.split('\n').filter((line) => line.length > 0);
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function inspectHookChainHealth({ projectRoot, now = Date.now() } = {}) {
+  const dir = telemetryDirFor(projectRoot);
+  const files = await recentTelemetryFiles(dir, now);
+
+  const counts = { rowsScanned: 0, filesScanned: files.length, ok: 0 };
+  let rowsLeft = MAX_ROWS;
+
+  for (const file of files) {
+    if (rowsLeft <= 0) break;
+    let lines;
+    try {
+      lines = await tailLines(file.filePath, file.size);
+    } catch {
+      continue; // unreadable file — skip, never fatal
+    }
+    for (const line of lines) {
+      if (rowsLeft <= 0) break;
+      let row;
+      try {
+        row = JSON.parse(line);
+      } catch {
+        continue; // corrupt line ignored — regression guard
+      }
+      if (row?.hook !== CHAIN_HOOK) continue;
+      rowsLeft -= 1;
+      counts.rowsScanned += 1;
+      const outcome = typeof row.outcome === 'string' && row.outcome.length > 0 ? row.outcome : 'ok';
+      counts[outcome] = (counts[outcome] ?? 0) + 1;
+    }
+  }
+
+  const label = 'hook-chain health';
+
+  if (counts.rowsScanned === 0) {
+    return {
+      label,
+      passed: true,
+      failed: false,
+      severity: 'info',
+      remediationClass: 'advisory',
+      detail: 'no telemetry — no hook-chain-runner rows in .ukit/storage/cache/hook-latency/ (unknown, not failure)',
+      counts,
+    };
+  }
+
+  const failureKinds = Object.keys(counts)
+    .filter((key) => FAILURE_OUTCOMES.has(key) && counts[key] > 0)
+    .sort();
+
+  if (failureKinds.length === 0) {
+    return {
+      label,
+      passed: true,
+      failed: false,
+      severity: 'info',
+      remediationClass: 'advisory',
+      detail: `${counts.rowsScanned} chain row(s) scanned across ${counts.filesScanned} file(s) — all outcome:ok`,
+      counts,
+    };
+  }
+
+  const breakdown = failureKinds.map((kind) => `${kind}=${counts[kind]}`).join(', ');
+  return {
+    label,
+    passed: false,
+    failed: true,
+    severity: 'warning',
+    remediationClass: 'advisory',
+    detail: `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`,
+    remedy: 'Inspect recent rows in .ukit/storage/cache/hook-latency/ for the failing scriptName/failureKind and fix or widen the gate budget.',
+    counts,
+  };
+}