@ngockhoale/ukit 2.2.2 → 2.2.4

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 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.
+
+### Fixed
+
+- **Silent stalls were unenforceable, because nothing measured them.** A stop after a read-only pass was indistinguishable from a stop after finished work: both were just the model ending its turn. UKit now keeps a session-scoped execution ledger (`.ukit/storage/cache/exec-ledger/<session>.json`) recording source reads, write attempts and outcomes, and verification commands with their exit codes. A new `Stop` hook (`completion-gate.sh`, and omp's `session_stop`) reads it against the routed contract's `completionEvidence` and blocks a premature stop with the specific missing evidence and a recovery instruction matched to the actual state — no source yet, failed write, no write, failed verification, or no verification each get different guidance. Recovery is capped at 6 continuations, then degrades to a warning, so the gate can never loop.
+- **The omp bridge could exceed omp's own handler budget and freeze the session.** A single `Edit` fired 7 hook scripts as 7 serial `pi.exec` subprocesses at up to 8s each — worst case well past omp's ~30s outer timeout, which surfaces to the user as the session simply hanging. They now run in one bounded `hook-chain-runner.mjs` process: 4s per script, 10s total budget, under a 12s outer timeout. Per-event latency is appended to `.ukit/storage/cache/hook-latency/<session>.jsonl` so hook cost stops being invisible.
+- **omp writes bypassed the safety gates entirely.** omp's `normalizeToolEventInput` emits `path` / `paths`; every UKit hook script reads `file_path`. So `protect-files.sh` and `stale-spec-guard.sh` saw no target on an omp edit and waved it through. The bridge now normalizes `path` / `paths[0]` → `file_path` at the host boundary, without mutating the caller's event.
+- **An unmapped mutation-capable tool failed open and silently.** `mapToolName` returned `null` for any tool not in its table, and the bridge ran an empty script chain — so a host tool that writes files but is not yet mapped skipped every guard with no signal. Such tools are now blocked with a message naming the tool; unmapped read-only tools still pass through.
+- **The ledger CLI silently did nothing under a symlinked project root.** Its main-guard compared `fileURLToPath(import.meta.url)` against `path.resolve(process.argv[1])`. Under macOS `/tmp` → `/private/tmp`, or any symlinked work directory, those differ — so `--record` and `--evaluate-stop` returned exit 0 having done nothing: no receipts, no gate. The whole unit suite stayed green; only a scratch install under `/tmp` exposed it. Both paths are now compared by realpath, covered by `tests/hooks/executionLedgerCli.test.js`.
+- **`.omp/config.yml` documented the model aliases backwards**, calling the UNIC names "LITERAL model names, not aliases". They are stable provider-neutral aliases whose hidden backends change during development — which is precisely why orchestration must not branch on vendor names.
+
+### Added
+
+- **`tests/hooks/executionLedgerCli.test.js`** (4 tests) — drives the real CLI through a symlinked root: receipts get written, a premature stop is blocked, a stop with write + passing verification is allowed, and the continuation cap engages at exactly 6. Verified RED against the pre-fix guard (3 of 4 fail).
+- **Manifest entries and dev-mirror parity for the four new files** — `record-execution.sh`, `completion-gate.sh`, `execution-ledger.mjs`, `hook-chain-runner.mjs`. `templates/.claude/` is gitignored and existing template files were force-added, so new ones are invisible to both git and `npm pack` unless added the same way; verified present in the packed tarball, with hook scripts executable after a real `ukit install`.
+
 ## 2.2.2 - 2026-08-22
 
 Running Claude Code and omp side by side exposed that they were not, in fact, running the same UKit. `CLAUDE.md` and `AGENTS.md` are hand-maintained forks of one instruction set read by different harnesses, and `AGENTS.md` had fallen three minor versions behind — so omp was never told the model-tier table existed. This wave re-unifies them and adds a test that makes the drift impossible to repeat.

package/manifests/platform.full.yaml

@@ -1037,6 +1037,30 @@ items:
     packs:
       - core
 
+  - id: hook-record-execution
+    type: hook
+    sourceTemplate: .claude/hooks/record-execution.sh
+    targetPath: .claude/hooks/record-execution.sh
+    requires:
+      - ukit-runtime-execution-ledger-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-completion-gate
+    type: hook
+    sourceTemplate: .claude/hooks/completion-gate.sh
+    targetPath: .claude/hooks/completion-gate.sh
+    requires:
+      - ukit-runtime-execution-ledger-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-auto-allow-bash
     type: hook
     sourceTemplate: .claude/hooks/auto-allow-bash.sh
@@ -1223,6 +1247,28 @@ items:
     packs:
       - core
 
+  - id: ukit-runtime-execution-ledger-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/execution-ledger.mjs
+    targetPath: .claude/ukit/runtime/execution-ledger.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-runtime-hook-chain-runner-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/hook-chain-runner.mjs
+    targetPath: .claude/ukit/runtime/hook-chain-runner.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-runtime-safe-patch-core-script
     type: config
     sourceTemplate: .claude/ukit/runtime/safe-patch-core.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.2",
+  "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/.claude/hooks/completion-gate.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Stop hook: block premature terminal stops while routed completion evidence is missing.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --evaluate-stop

package/templates/.claude/hooks/record-execution.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# PostToolUse hook: persist session-scoped source/write/verification receipts.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --record

package/templates/.claude/settings.json

@@ -139,6 +139,16 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Read|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write",
         "hooks": [
@@ -146,6 +156,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
           }
         ]
       },
@@ -156,6 +171,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
           }
         ]
       }
@@ -181,6 +201,17 @@
         ]
       }
     ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\"",
+            "timeout": 4
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "hooks": [

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

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LEDGER_VERSION = 1;
+const MAX_RECEIPTS = 24;
+const MAX_CONTINUATIONS = 6;
+const IMPLEMENT_MODES = new Set([
+  'tiny-fix',
+  'local-fix',
+  'local-build',
+  'shared-edit',
+  'find-cause',
+]);
+
+function safeSegment(value) {
+  return String(value || 'default')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 96) || 'default';
+}
+
+function firstDefined(values) {
+  return values.find((value) => value !== undefined && value !== null);
+}
+
+function sessionIdentity(payload = {}) {
+  const sessionId = firstDefined([
+    payload.session_id,
+    payload.sessionId,
+  ]);
+  if (sessionId) return safeSegment(sessionId);
+
+  const transcriptPath = firstDefined([
+    payload.transcript_path,
+    payload.transcriptPath,
+  ]);
+  if (transcriptPath) {
+    return `transcript-${crypto.createHash('sha256').update(String(transcriptPath)).digest('hex').slice(0, 20)}`;
+  }
+  return 'default';
+}
+
+function ledgerPath(projectRoot, payload = {}) {
+  return path.join(
+    projectRoot,
+    '.ukit',
+    'storage',
+    'cache',
+    'exec-ledger',
+    `${sessionIdentity(payload)}.json`,
+  );
+}
+
+async function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fs.rename(tempPath, filePath);
+}
+
+export async function readRouteState(projectRoot) {
+  return readJson(path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json'), null);
+}
+
+export async function readExecutionLedger(projectRoot, payload = {}) {
+  return readJson(ledgerPath(projectRoot, payload), null);
+}
+
+function explicitError(payload = {}) {
+  return [
+    payload.isError,
+    payload.is_error,
+    payload.tool_output?.isError,
+    payload.tool_output?.is_error,
+    payload.tool_result?.isError,
+    payload.tool_result?.is_error,
+    payload.tool_response?.isError,
+    payload.tool_response?.is_error,
+  ].some((value) => value === true);
+}
+
+function extractExitCode(payload = {}) {
+  const candidates = [
+    payload.tool_output?.exitCode,
+    payload.tool_output?.exit_code,
+    payload.tool_result?.details?.exitCode,
+    payload.tool_result?.details?.exit_code,
+    payload.tool_result?.exitCode,
+    payload.tool_result?.exit_code,
+    payload.tool_response?.exitCode,
+    payload.tool_response?.exit_code,
+    payload.exitCode,
+    payload.exit_code,
+  ];
+  for (const value of candidates) {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  return null;
+}
+
+function isVerificationCommand(command) {
+  const text = String(command || '').trim();
+  if (!text) return false;
+  return [
+    /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)/i,
+    /(?:^|\s)(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+(?:test|lint|typecheck|check|build)(?:\s|$)/i,
+    /(?:^|\s)(?:tsc|eslint|biome|ruff|mypy)(?:\s|$)/i,
+    /(?:^|\s)node\s+--check(?:\s|$)/i,
+  ].some((pattern) => pattern.test(text));
+}
+
+function compactReceipt(receipt) {
+  const compact = {
+    ts: receipt.ts,
+    kind: receipt.kind,
+    success: receipt.success,
+  };
+  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'error']) {
+    if (receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
+      compact[key] = receipt[key];
+    }
+  }
+  return compact;
+}
+
+function appendReceipt(receipts, receipt) {
+  return [...(receipts || []), compactReceipt(receipt)].slice(-MAX_RECEIPTS);
+}
+
+function freshLedger(payload, routeState, harness) {
+  return {
+    version: LEDGER_VERSION,
+    sessionKey: sessionIdentity(payload),
+    sessionId: payload.session_id || payload.sessionId || null,
+    transcriptPath: payload.transcript_path || payload.transcriptPath || null,
+    harness,
+    requestKey: routeState?.requestKey || null,
+    routeFingerprint: routeState?.fingerprint || null,
+    sourceSucceeded: false,
+    writeAttempted: false,
+    writeSucceeded: false,
+    verificationAttempted: false,
+    verificationSucceeded: false,
+    verificationFailed: false,
+    receipts: [],
+    blocker: null,
+    continuationCount: 0,
+    updatedAt: Date.now(),
+  };
+}
+
+export async function recordExecutionReceipt({
+  projectRoot,
+  payload = {},
+  toolName = payload.tool_name,
+  harness = 'unknown',
+} = {}) {
+  if (!projectRoot || !toolName) return null;
+  const routeState = await readRouteState(projectRoot);
+  const current = await readExecutionLedger(projectRoot, payload);
+  const ledger = !current || current.requestKey !== (routeState?.requestKey || null)
+    ? freshLedger(payload, routeState, harness)
+    : { ...current, harness: current.harness || harness };
+
+  const failed = explicitError(payload);
+  const exitCode = extractExitCode(payload);
+  const success = !failed && (exitCode === null || exitCode === 0);
+  const toolInput = payload.tool_input || {};
+  const receipt = {
+    ts: Date.now(),
+    toolName,
+    toolUseId: payload.tool_use_id || null,
+    success,
+    exitCode,
+  };
+
+  if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
+    receipt.kind = 'source';
+    receipt.file = toolInput.file_path || toolInput.path || null;
+    ledger.sourceSucceeded ||= success;
+  } else if (toolName === 'Edit' || toolName === 'Write') {
+    receipt.kind = 'write';
+    receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
+    ledger.writeAttempted = true;
+    ledger.writeSucceeded ||= success;
+  } else if (toolName === 'Bash' && isVerificationCommand(toolInput.command)) {
+    receipt.kind = 'verification';
+    receipt.command = String(toolInput.command || '').trim();
+    ledger.verificationAttempted = true;
+    ledger.verificationSucceeded ||= success;
+    ledger.verificationFailed ||= !success;
+  } else {
+    return ledger;
+  }
+
+  ledger.receipts = appendReceipt(ledger.receipts, receipt);
+  ledger.updatedAt = Date.now();
+  await writeJsonAtomic(ledgerPath(projectRoot, payload), ledger);
+  return ledger;
+}
+
+function requiredEvidence(state = {}) {
+  const routeSummary = state?.routeSummary || {};
+  const contractEvidence = routeSummary.executionContract?.completionEvidence;
+  if (Array.isArray(contractEvidence) && contractEvidence.length > 0) {
+    return [...new Set(contractEvidence)];
+  }
+  return [...new Set(routeSummary.completionState?.missingEvidence || [])];
+}
+
+function evidenceSatisfied(evidence, ledger = {}) {
+  if (evidence === 'write-evidence') return ledger.writeSucceeded === true;
+  if (evidence === 'verification-evidence') return ledger.verificationSucceeded === true;
+  if (evidence === 'impact-evidence') return ledger.sourceSucceeded === true;
+  return false;
+}
+
+function recoveryInstruction(missingEvidence, ledger = {}) {
+  if (missingEvidence.includes('write-evidence')) {
+    if (!ledger.sourceSucceeded) {
+      return 'Pull one bounded indexed source slice, then make the requested Edit/Write in this continuation.';
+    }
+    if (ledger.writeAttempted && !ledger.writeSucceeded) {
+      return 'Recover from the failed mutation using the current error, then retry the smallest correct Edit/Write.';
+    }
+    return 'Make the smallest correct Edit/Write now; do not end after more read-only analysis.';
+  }
+  if (missingEvidence.includes('verification-evidence')) {
+    if (ledger.verificationFailed) {
+      return 'Use the latest failed verification output, fix the failure, and rerun targeted verification.';
+    }
+    return 'Run the routed targeted verification now and inspect its result before stopping.';
+  }
+  return 'Complete the current routed milestone before stopping.';
+}
+
+export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
+  const routeSummary = state?.routeSummary || {};
+  const mode = routeSummary.executionMode || routeSummary.approachSelector?.executionMode || null;
+  const evidence = requiredEvidence(state);
+  if (!IMPLEMENT_MODES.has(mode) || evidence.length === 0 || ledger?.blocker) {
+    return { continue: false, missingEvidence: [] };
+  }
+
+  const sameRequest = !ledger?.requestKey || !state?.requestKey || ledger.requestKey === state.requestKey;
+  const effectiveLedger = sameRequest ? ledger : {};
+  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger));
+  if (missingEvidence.length === 0) {
+    return { continue: false, missingEvidence: [] };
+  }
+
+  const continuationCount = Number(effectiveLedger?.continuationCount || 0);
+  if (continuationCount >= MAX_CONTINUATIONS) {
+    return {
+      continue: false,
+      capped: true,
+      missingEvidence,
+      reason: `UKit continuation cap reached with missing evidence: ${missingEvidence.join(', ')}.`,
+    };
+  }
+
+  const finalAttempt = continuationCount === MAX_CONTINUATIONS - 1;
+  const instruction = recoveryInstruction(missingEvidence, effectiveLedger);
+  return {
+    continue: true,
+    missingEvidence,
+    reason: [
+      `UKit completion gate: missing ${missingEvidence.join(', ')}.`,
+      instruction,
+      finalAttempt ? 'Final automatic recovery attempt: finish now or report a concrete blocker with its evidence.' : null,
+    ].filter(Boolean).join(' '),
+  };
+}
+
+export async function incrementContinuation(projectRoot, payload = {}, ledger = null) {
+  const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
+  const next = {
+    ...current,
+    continuationCount: Number(current.continuationCount || 0) + 1,
+    lastContinuationAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+  await writeJsonAtomic(ledgerPath(projectRoot, payload), next);
+  return next;
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(String(chunk));
+  return chunks.join('');
+}
+
+async function main() {
+  const payload = JSON.parse((await readStdin()) || '{}');
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
+  if (process.argv.includes('--record')) {
+    await recordExecutionReceipt({
+      projectRoot,
+      payload,
+      toolName: payload.tool_name,
+      harness: process.env.UKIT_HARNESS || 'claude-code',
+    });
+    return;
+  }
+  if (process.argv.includes('--evaluate-stop')) {
+    const state = await readRouteState(projectRoot);
+    const ledger = await readExecutionLedger(projectRoot, payload) || {};
+    const result = evaluateCompletion({ state, ledger });
+    if (result.continue) {
+      await incrementContinuation(projectRoot, payload, ledger);
+      process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
+    } else if (result.capped) {
+      process.stderr.write(`[ukit-completion] ${result.reason}\n`);
+    }
+  }
+}
+
+// Compare real paths: a project under a symlinked root (macOS /tmp -> /private/tmp, or a
+// symlinked work directory) makes import.meta.url resolve to the real path while argv[1]
+// keeps the symlinked spelling. Without realpath the guard silently never runs the CLI.
+function isDirectRun() {
+  const argvPath = process.argv[1];
+  if (!argvPath) return false;
+  const selfPath = fileURLToPath(import.meta.url);
+  const resolved = path.resolve(argvPath);
+  if (selfPath === resolved) return true;
+  try {
+    return fsSync.realpathSync(selfPath) === fsSync.realpathSync(resolved);
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectRun()) {
+  main().catch((error) => {
+    process.stderr.write(`[ukit-execution-ledger] ${error?.message || error}\n`);
+    process.exitCode = 1;
+  });
+}

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const FAIL_CLOSED_SCRIPTS = new Set([
+  'protect-files.sh',
+  'stale-spec-guard.sh',
+  'handoff-model-guard.sh',
+  'vision-gate.sh',
+  'context-hardcap-gate.sh',
+  'block-dangerous.sh',
+  'verification-guard.sh',
+]);
+
+const TOTAL_BUDGET_MS = 10000;
+const CHILD_BUDGET_MS = 4000;
+const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+
+function safeName(value) {
+  return String(value || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+}
+
+function recordTiming(projectRoot, payload, timing) {
+  try {
+    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${safeName(payload?.session_id)}.jsonl`);
+    fs.appendFileSync(filePath, `${JSON.stringify(timing)}\n`, 'utf8');
+  } catch {
+    // Timing telemetry is advisory and must never delay or block a tool call.
+  }
+}
+
+function run(payloadText, scriptPaths) {
+  const payload = JSON.parse(payloadText || '{}');
+  const firstScript = scriptPaths[0] || '';
+  const projectRoot = firstScript
+    ? path.resolve(path.dirname(firstScript), '../..')
+    : (payload.cwd || process.cwd());
+  const startedAt = Date.now();
+  const deadline = startedAt + TOTAL_BUDGET_MS;
+  const results = [];
+
+  for (const scriptPath of scriptPaths) {
+    const scriptName = path.basename(scriptPath);
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      results.push({
+        scriptName,
+        code: 1,
+        stdout: '',
+        stderr: `hook chain exceeded its ${TOTAL_BUDGET_MS}ms total budget`,
+        killed: true,
+        elapsedMs: 0,
+      });
+      break;
+    }
+
+    const childStartedAt = Date.now();
+    const result = spawnSync(scriptPath, [], {
+      cwd: projectRoot,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      input: payloadText,
+      encoding: 'utf8',
+      timeout: Math.min(CHILD_BUDGET_MS, remainingMs),
+      maxBuffer: MAX_BUFFER_BYTES,
+    });
+    const code = Number.isFinite(result.status) ? result.status : 1;
+    const killed = Boolean(result.signal || result.error?.code === 'ETIMEDOUT');
+    const stderr = [result.stderr, result.error?.message].filter(Boolean).join('\n');
+    results.push({
+      scriptName,
+      code,
+      stdout: result.stdout || '',
+      stderr,
+      killed,
+      elapsedMs: Date.now() - childStartedAt,
+    });
+
+    if (code === 2 || killed || (code !== 0 && FAIL_CLOSED_SCRIPTS.has(scriptName))) {
+      break;
+    }
+  }
+
+  const elapsedMs = Date.now() - startedAt;
+  recordTiming(projectRoot, payload, {
+    ts: Date.now(),
+    hookEvent: payload?.hook_event_name || null,
+    toolName: payload?.tool_name || null,
+    toolUseId: payload?.tool_use_id || null,
+    elapsedMs,
+    budgetMs: TOTAL_BUDGET_MS,
+    scripts: results.map(({ scriptName, code, killed, elapsedMs: scriptElapsedMs }) => ({
+      scriptName,
+      code,
+      killed,
+      elapsedMs: scriptElapsedMs,
+    })),
+  });
+
+  return { results, elapsedMs, budgetMs: TOTAL_BUDGET_MS };
+}
+
+try {
+  const [, , payloadText = '{}', ...scriptPaths] = process.argv;
+  process.stdout.write(JSON.stringify(run(payloadText, scriptPaths)));
+} catch (error) {
+  process.stdout.write(JSON.stringify({
+    results: [],
+    wrapperError: error?.message || String(error),
+  }));
+  process.exitCode = 1;
+}

package/templates/.omp/config.yml

@@ -1,5 +1,6 @@
-# UNIC gateway model names are LITERAL model names, not aliases, and they ship as the
-# installed default. Do NOT substitute sonnet/opus/haiku here. See PLAN.md §3 D15.
+# UNIC gateway model names are stable provider-neutral aliases. Their hidden backend
+# models may change during development; orchestration must not branch on vendor names.
+# Do NOT substitute sonnet/opus/haiku here. See PLAN.md §3 D15.
 #
 # Non-UNIC omp provider? A maintainer edits the three cost tiers to the values in
 # orchestration.modelTiers[*].claudeModel (.ukit/storage/config.json) — currently