@ngockhoale/ukit 2.7.3 → 2.7.4

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to UKit are documented here.
 
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.7.3",
+  "version": "2.7.4",
   "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,
+  };
+}

package/templates/.claude/hooks/session-episode.sh

@@ -15,6 +15,28 @@
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 CONFIG_FILE="$PROJECT_ROOT/.ukit/storage/config.json"
 
+# Gate-first fast path (TASK-001): evaluate learning.episodes.autoWrite BEFORE
+# staging stdin. A producer that holds the pipe open would otherwise burn the
+# full stdin-staging watchdog (measured ~2020ms) even though a gate-off run
+# never inspects the payload — the same held-stdin stall TASK-235 fixed in
+# project-important.sh. Missing/corrupt config or missing node resolves to 0,
+# i.e. gate off → exit 0 without touching stdin.
+__ukit_ep_gate="$(node -e '
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 2000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+const fs = require("fs");
+try {
+  const config = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  process.stdout.write(config?.learning?.episodes?.autoWrite === true ? "1" : "0");
+} catch {
+  process.stdout.write("0");
+}
+' "$CONFIG_FILE" 2>/dev/null)" || __ukit_ep_gate="0"
+if [ "$__ukit_ep_gate" != "1" ]; then
+  exit 0
+fi
+unset __ukit_ep_gate
+
 # Bounded stdin read (existing hook style): cap +1 byte in background so a
 # producer that never closes the pipe cannot park the session teardown.
 UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-episode-in.XXXXXX")" || exit 0
@@ -23,7 +45,10 @@ if [ -e /dev/fd/0 ]; then
   head -c 65537 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
   UKIT_HEAD_PID=$!
   # UKIT_HOOK_STAGE_MS:-2000 — bounded wait for the staged payload.
-  ( sleep 2; kill "$UKIT_HEAD_PID" 2>/dev/null ) &
+  # TASK-002: detach the watchdog's inherited stdout/stderr — otherwise a
+  # captured-stdio caller (hook-chain-runner) sees the pipe held open ~2s
+  # after the script exits, inflating the SessionEnd residual to ~2000ms.
+  ( sleep 2; kill "$UKIT_HEAD_PID" 2>/dev/null ) >/dev/null 2>&1 &
   UKIT_WATCH_PID=$!
   wait "$UKIT_HEAD_PID" 2>/dev/null
   kill "$UKIT_WATCH_PID" 2>/dev/null