@ngockhoale/ukit 2.2.3 → 2.2.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.4 - 2026-08-27
+
+Follow-up to 2.2.3's hook-chain collapse: a real omp session on a CloudMounter/FUSE-mounted project reported every tool call — including harmless `echo`, `pwd`, `ls`, and `Edit` — failing with `invalid hook-chain output`, and in one case `protect-files.sh hook chain was killed before safety gates completed`, despite `protect-files.sh` itself passing trivially. The bridge was misattributing any aggregate-runner transport failure to the first fail-closed script in the chain, whether or not that script ever ran.
+
+### Fixed
+
+- **Outer transport failures no longer impersonate a specific safety gate.** `runScriptChain` in `ukit-bridge.js` treated a killed/timed-out `pi.exec`, empty stdout, or malformed JSON from `hook-chain-runner.mjs` as proof that the chain's first fail-closed script (e.g. `protect-files.sh`) had failed — without verifying that script ever ran. It now distinguishes "the runner returned a verifiable per-script result" from "the runner itself failed before producing one," and on the latter reports the real failure (killed/code/elapsedMs/runtime) instead of a fabricated gate name. Diagnostics are appended to `.ukit/storage/cache/hook-errors/<session>.jsonl`.
+- **Bash and Read/Grep/Glob no longer fail closed on a bridge/runner outage.** Only `Edit`/`Write` chains still block when the runner can't produce a verdict, since those guard file mutation. Ordinary shell commands and read-only tools now fail open (with a logged warning), so a runner-level hiccup can no longer brick command execution or diagnosis tools.
+- **`process.execPath` is no longer trusted blindly for the runner subprocess.** The bridge resolves `process.env.UKIT_NODE_PATH || process.execPath` and records the resolved runtime in the failure diagnostic, so a Bun-hosted omp launching the Node-only runner under the wrong binary is now visible instead of silently assumed.
+
+### Added
+
+- **6 regression tests** in `tests/hooks/ompHookBridge.test.js` (`case 13`) covering a killed outer exec, malformed stdout, a non-zero exit with empty stdout before any script ran, fail-open behavior for Bash and Read chains under the same failures, and `UKIT_NODE_PATH` override.
+
 ## 2.2.3 - 2026-08-26
 
 Sessions were stalling mid-task — the model would read source, then simply stop, with the work half done and nothing wrong upstream. This wave stops treating that as a prompting problem. Instructions asking a model to "continue until the edit is made" are advisory by nature: every hidden backend behind `unic-lite` / `unic-code` / `unic-smart` / `unic-vision` reads them slightly differently, and the ones that read them loosely stall. UKit now records what actually happened — real Edit/Write receipts, real verification exit codes — and enforces completion mechanically at the point of stopping, identically on Claude Code and omp. Nothing in the enforcement path branches on provider branding.

package/package.json

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

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

@@ -5,6 +5,7 @@
 // payloads, executes the same ordered script chains, and translates only the
 // result fields that omp consumes.
 
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
@@ -172,7 +173,23 @@ export { translateExecResult };
 
 const HOOK_CHAIN_TIMEOUT_MS = 12000;
 
-export async function runScriptChain(pi, scripts, payload, { projectRoot }) {
+function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic) {
+  try {
+    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-errors');
+    fs.mkdirSync(dir, { recursive: true });
+    const safeSession = String(sessionId || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+    fs.appendFileSync(path.join(dir, `${safeSession}.jsonl`), `${JSON.stringify(diagnostic)}\n`, 'utf8');
+  } catch {
+    // Diagnostics are advisory and must never block or throw.
+  }
+}
+
+export async function runScriptChain(
+  pi,
+  scripts,
+  payload,
+  { projectRoot, failClosedOnTransportError = false },
+) {
   const invoked = [];
   const context = [];
   if (scripts.length === 0) {
@@ -181,50 +198,64 @@ export async function runScriptChain(pi, scripts, payload, { projectRoot }) {
 
   const runnerPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'hook-chain-runner.mjs');
   const scriptPaths = scripts.map((scriptName) => path.join(projectRoot, '.claude', 'hooks', scriptName));
+  // Do not blindly trust process.execPath: under a Bun-hosted omp, it points at bun, not node.
+  const nodeExecutable = process.env.UKIT_NODE_PATH || process.execPath;
+  const startedAt = Date.now();
   let execResult;
   try {
     execResult = await pi.exec(
-      process.execPath,
+      nodeExecutable,
       [runnerPath, JSON.stringify(payload), ...scriptPaths],
       { cwd: projectRoot, timeout: HOOK_CHAIN_TIMEOUT_MS },
     );
   } catch (error) {
     execResult = { code: 1, stdout: '', stderr: error?.message ?? String(error), killed: false };
   }
+  const elapsedMs = Date.now() - startedAt;
 
-  if (execResult?.killed) {
-    const firstGate = scripts.find((scriptName) => FAIL_CLOSED_SCRIPTS.has(scriptName));
-    return firstGate
-      ? {
-          block: true,
-          reason: `${firstGate} hook chain was killed before safety gates completed`,
-          context,
-          invoked,
-        }
-      : { block: false, context, invoked };
-  }
-
-  let chainResult;
-  try {
-    chainResult = JSON.parse(execResult?.stdout || '{}');
-  } catch {
-    chainResult = { results: [], wrapperError: execResult?.stderr || 'invalid hook-chain output' };
+  let chainResult = null;
+  let parseError = null;
+  if (!execResult?.killed) {
+    try {
+      chainResult = JSON.parse(execResult?.stdout || '{}');
+    } catch (error) {
+      parseError = error;
+    }
   }
 
-  if (chainResult.wrapperError || execResult?.code) {
-    const firstGate = scripts.find((scriptName) => FAIL_CLOSED_SCRIPTS.has(scriptName));
-    if (firstGate) {
-      return {
-        block: true,
-        reason: chainResult.wrapperError || execResult?.stderr || `${firstGate} hook chain failed`,
-        context,
-        invoked,
-      };
+  const hasUsableResults = Boolean(chainResult) && Array.isArray(chainResult.results) && chainResult.results.length > 0;
+  const transportFailed = Boolean(execResult?.killed) || Boolean(parseError) || Boolean(chainResult?.wrapperError) || !hasUsableResults;
+
+  if (transportFailed) {
+    // The aggregate runner produced no verifiable per-script verdict. Never relabel this as a
+    // specific fail-closed script's decision -- that script may never have run.
+    const diagnostic = {
+      ts: Date.now(),
+      scripts,
+      killed: Boolean(execResult?.killed),
+      code: execResult?.code ?? null,
+      stdoutLength: (execResult?.stdout || '').length,
+      stderr: execResult?.stderr || '',
+      elapsedMs,
+      nodeExecutable,
+      nodeVersion: process.version,
+      runnerPath,
+      parseError: parseError?.message || null,
+      wrapperError: chainResult?.wrapperError || null,
+    };
+    recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
+    const reason = `UKit OMP hook runner failed before producing a valid result `
+      + `(killed=${diagnostic.killed}, code=${diagnostic.code}, elapsedMs=${diagnostic.elapsedMs}, `
+      + `runtime=${diagnostic.nodeExecutable}). No safety-gate verdict was available for [${scripts.join(', ')}]. `
+      + `See .ukit/storage/cache/hook-errors/.`;
+    if (failClosedOnTransportError) {
+      return { block: true, reason, context, invoked };
     }
-    pi.logger?.warn?.(`[UKit] hook chain failed open: ${chainResult.wrapperError || execResult?.stderr || 'unknown error'}`);
+    pi.logger?.warn?.(`[UKit] ${reason}`);
+    return { block: false, context, invoked };
   }
 
-  for (const item of chainResult.results ?? []) {
+  for (const item of chainResult.results) {
     const scriptName = item?.scriptName;
     if (!scriptName || !scripts.includes(scriptName)) continue;
     invoked.push(scriptName);
@@ -314,7 +345,13 @@ export async function runToolCall(pi, event, { projectRoot, context: extensionCo
     toolUseId: event.toolCallId,
     ...metadata,
   });
-  const result = await runScriptChain(pi, scriptsForToolCall(toolName), payload, { projectRoot });
+  // Only Edit|Write stays fail-closed on a bridge/runner transport failure; Bash and
+  // Read|Grep|Glob fail open so diagnosis/recovery tools are never bricked by a runner outage.
+  const failClosedOnTransportError = matcherGroupFor(toolName) === 'Edit|Write';
+  const result = await runScriptChain(pi, scriptsForToolCall(toolName), payload, {
+    projectRoot,
+    failClosedOnTransportError,
+  });
   if (!result.block) sendContext(pi, result.context, 'steer');
   return { ...result, toolName };
 }