@ngockhoale/ukit 2.3.19 → 2.3.20

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.20 - 2026-09-13
+
+C15 bug-fix release record — this release completes the silent-stop class on top of the
+already-published 2.3.19 (published to npm 2026-09-13, registry verified, carrying the C14
+valve removal); it adds no new features. npm is the distribution channel and `ukit update`
+pulls from npm, so an install on 2.3.19 (or older) needs an update to receive these fixes.
+
+- **`--evaluate-stop` never releases a routed stop silently.**
+  `templates/.claude/ukit/runtime/execution-ledger.mjs` had a final dispatch with no `else`, so any
+  evaluation result of `{continue:false, notify:false}` that was not `capped` wrote nothing at all
+  — the Stop was allowed and the session idled with no visible reason. That default path is now a
+  loud release: an invisible blocker and a route with empty/short completion evidence both emit a
+  `systemMessage` naming the cause and how to resume, instead of silence. Malformed stdin no longer
+  crashes the hook into a silent stderr exit — it blocks with the crash detail, bounded by a crash
+  counter that loudly releases after the threshold and resets on a clean evaluate.
+- **Fail-loud completion-gate wrappers.**
+  `templates/.claude/hooks/completion-gate.sh` and `templates/.claude/hooks/record-execution.sh`
+  exited 0 silently when the runtime script was missing or failed; both now emit a
+  `systemMessage` naming the missing/failing runtime and the `ukit install` remedy.
+- **omp reentrant stop gets the same never-silent contract as the CLI.**
+  `templates/.omp/hooks/pre/ukit-bridge.js` released a reentrant stop with a non-blocking notice
+  and no continuation; it now blocks with the actionable reason like any other stop, stays bounded
+  by the ledger's continuation cap, and releases loudly at the cap.
+
 ## 2.3.19 - 2026-09-12
 
 C14 bug-fix release record — one correctness fix is shipped; this release adds no new features.

package/package.json

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

package/scripts/release/verify-release.mjs

@@ -1,10 +1,35 @@
 import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
 const rootDir = process.cwd();
 const npmCacheDir = path.join(os.tmpdir(), 'ukit-npm-cache');
 
+// Opt-in post-publish registry-parity check (Release Policy invariant: npm and git always hold
+// the same latest version). Only meaningful AFTER `npm publish` — before publish the registry is
+// behind by definition — so it is gated behind --post-publish and never runs by default.
+const postPublish = process.argv.includes('--post-publish');
+
+if (postPublish) {
+  const localVersion = JSON.parse(readFileSync(path.join(rootDir, 'package.json'), 'utf8')).version;
+  const registryVersion = await readRegistryVersion();
+
+  console.log(`[release:verify] Registry parity (post-publish)`);
+  console.log(`[release:verify] package.json   = ${localVersion}`);
+  console.log(`[release:verify] npm registry   = ${registryVersion}`);
+
+  if (registryVersion !== localVersion) {
+    console.error(
+      `[release:verify] FAILED: registry version ${registryVersion} !== package.json ${localVersion}`,
+    );
+    process.exit(1);
+  }
+
+  console.log('\n[release:verify] All release checks passed.');
+  process.exit(0);
+}
+
 const steps = [
   {
     label: 'Artifact smoke',
@@ -54,3 +79,23 @@ function runStep({ command, args, env }) {
     child.on('error', () => resolve(1));
   });
 }
+
+function readRegistryVersion() {
+  return new Promise((resolve) => {
+    const child = spawn('npm', ['view', '@ngockhoale/ukit', 'version'], {
+      cwd: rootDir,
+      env: { ...process.env, npm_config_cache: npmCacheDir },
+      stdio: ['ignore', 'pipe', 'inherit'],
+    });
+
+    let stdout = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.on('close', () => {
+      const version = stdout.trim();
+      resolve(version.length > 0 ? version : '<unavailable>');
+    });
+    child.on('error', () => resolve('<unavailable>'));
+  });
+}

package/templates/.claude/hooks/completion-gate.sh

@@ -1,12 +1,24 @@
 #!/bin/bash
 # Stop hook: block premature terminal stops while routed completion evidence is missing.
+# ADVISORY ONLY — always exit 0. A missing or failing runtime must be loud, not a silent pass.
 
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
 
 if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' '{"systemMessage":"UKit completion gate: runtime script missing — run: ukit install"}'
   exit 0
 fi
 
-printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --evaluate-stop
+OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --evaluate-stop)
+STATUS=$?
+
+if [ "$STATUS" -ne 0 ]; then
+  printf '%s\n' '{"systemMessage":"UKit completion gate: runtime script failed — run: ukit install"}'
+  exit 0
+fi
+
+if [ -n "$OUTPUT" ]; then
+  printf '%s\n' "$OUTPUT"
+fi

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

@@ -1,12 +1,24 @@
 #!/bin/bash
 # PostToolUse hook: persist session-scoped source/write/verification receipts.
+# ADVISORY ONLY — always exit 0. A missing or failing runtime must be loud, not a silent pass.
 
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
 
 if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' '{"systemMessage":"UKit record execution: runtime script missing — run: ukit install"}'
   exit 0
 fi
 
-printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --record
+OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --record)
+STATUS=$?
+
+if [ "$STATUS" -ne 0 ]; then
+  printf '%s\n' '{"systemMessage":"UKit record execution: runtime script failed — run: ukit install"}'
+  exit 0
+fi
+
+if [ -n "$OUTPUT" ]; then
+  printf '%s\n' "$OUTPUT"
+fi

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

@@ -13,6 +13,12 @@ const RESUME_INTENT_TTL_MS = 30 * 60 * 1000;
 const MAX_RECEIPTS = 24;
 const MAX_SOURCE_FILES = 16;
 const MAX_CONTINUATIONS = 6;
+// A malformed stdin payload crashes `--evaluate-stop` before a route/session can be read, so
+// the only identity available is the project root. Count consecutive crashes there and, once
+// this bounded budget is exhausted, release LOUD (naming the crash + `ukit install`) instead of
+// blocking forever on a corrupt hook input. A successful evaluate resets the count. Mirrors
+// MAX_CONTINUATIONS style — a hard-coded module const, deliberately not a config knob.
+const MAX_GATE_CRASHES = 3;
 // Two adjacent identical failed verifications (no edit attempt between them) are a loop;
 // vibecode routes — which bypass the cap and every reentrant valve — additionally get a
 // cumulative escape after the same verification failed this many times across edits.
@@ -82,6 +88,17 @@ function ledgerPath(projectRoot, payload = {}) {
   );
 }
 
+function crashCounterPath(projectRoot) {
+  return path.join(
+    projectRoot,
+    '.ukit',
+    'storage',
+    'cache',
+    'exec-ledger',
+    'gate-crash-counter.json',
+  );
+}
+
 function resumeIntentPath(projectRoot, sessionId) {
   return path.join(
     projectRoot,
@@ -727,10 +744,32 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
         reason: `UKit stopped automatic recovery: ${ledger.blocker.detail || 'a recorded blocker ended this run.'}`,
       };
     }
+    // An invisible blocker (e.g. a permission decision the model already named in its own
+    // reply) must not loop — but it must not end silent either. Release loud so the user can
+    // tell a deliberate stop from a stall.
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence: [],
+      reason: `UKit stopped automatic recovery: ${ledger.blocker.detail || 'a recorded blocker ended this run.'}`,
+    };
+  }
+  if (!state || !state.routeSummary) {
+    // No routable state at all: a never-routed session (or a foreign-owned one) is silent
+    // success — there is nothing to report. The CLI's lost-route path handles the case where
+    // THIS session has ledger activity but the state vanished; callers that pass no state
+    // (e.g. the omp bridge for a session it does not own) must not be force-notified.
     return { continue: false, notify: false, missingEvidence: [] };
   }
   if (evidence.length === 0) {
-    return { continue: false, notify: false, missingEvidence: [] };
+    // A route with no completion evidence has no actionable block reason — blocking would
+    // loop unboundedly. Release loud instead of ending indistinguishable from a stall.
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence: [],
+      reason: 'UKit completion gate: this route carries no completion evidence to verify, so the stop released without checking unfinished work. Send the task again in a new message to re-route it with a completion contract.',
+    };
   }
 
   // Request identity is the prompt (see evidencePromptKey): the router re-keys requestKey on
@@ -742,7 +781,10 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   const effectiveLedger = sameRequest ? ledger : {};
   const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, routeSummary));
   if (missingEvidence.length === 0) {
-    return { continue: false, notify: false, missingEvidence: [] };
+    // Silent success: the route is present and every required evidence is satisfied. Marked
+    // `complete` so the CLI dispatch recognizes it BEFORE the loud final else — otherwise a
+    // bare loud else would turn a clean stop into user-visible noise.
+    return { continue: false, notify: false, complete: true, missingEvidence: [] };
   }
 
   // `find-cause` can validly end clean: an investigation may establish that no actionable
@@ -907,7 +949,121 @@ async function readStdin() {
   return chunks.join('');
 }
 
+// Malformed hook input crashes the evaluate BEFORE any route/session can be read, so the only
+// stable identity is the project root. Count consecutive crashes there; past MAX_GATE_CRASHES,
+// release LOUD naming the crash and the remedy instead of blocking a corrupt hook forever. Any
+// counter I/O failure fails SAFE to block (still loud, never silent). A successful evaluate
+// resets the count.
+async function handleEvaluateCrash(projectRoot, error) {
+  const detail = `malformed hook input crashed the completion gate (${error?.message || error})`;
+  const blockReason = () => `${detail}. This is the UKit completion gate, not the task — re-send the task in a new message so the hook payload is regenerated.`;
+  let count = 0;
+  try {
+    const current = await readJson(crashCounterPath(projectRoot), null);
+    count = Number(current?.count) || 0;
+  } catch {
+    count = 0;
+  }
+  const next = count + 1;
+  try {
+    await writeJsonAtomic(crashCounterPath(projectRoot), { count: next, updatedAt: Date.now() });
+  } catch {
+    // Counter unwritable: we cannot bound the crash loop, but silence is never an option.
+    process.stdout.write(`${JSON.stringify({ decision: 'block', reason: blockReason() })}\n`);
+    return;
+  }
+  if (next >= MAX_GATE_CRASHES) {
+    const message = `UKit completion gate: ${detail}. This recurred ${next} times and cannot be bounded, so the stop is releasing loudly instead of blocking again. The hook payload is corrupt — run: ukit install to refresh the runtime, then re-send the task in a new message.`;
+    process.stderr.write(`[ukit-completion] ${message}\n`);
+    process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify({ decision: 'block', reason: blockReason() })}\n`);
+}
+
+async function resetGateCrashCounter(projectRoot) {
+  // Only touch disk when a crash was actually counted — a clean stop on a healthy project
+  // must not create/rewrite a crash-counter file.
+  try {
+    await fs.access(crashCounterPath(projectRoot));
+  } catch {
+    return;
+  }
+  try {
+    await writeJsonAtomic(crashCounterPath(projectRoot), { count: 0, updatedAt: Date.now() });
+  } catch {
+    // Best-effort: an unwritable counter only means the next crash blocks again, which is safe.
+  }
+}
+
+async function runEvaluateStop() {
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  let payload;
+  try {
+    payload = JSON.parse((await readStdin()) || '{}');
+  } catch (error) {
+    await handleEvaluateCrash(projectRoot, error);
+    return;
+  }
+  // A parse that reached here is a functioning evaluate — reset the crash budget so the next
+  // malformed payload starts blocking again.
+  await resetGateCrashCounter(projectRoot);
+
+  const state = await readRouteState(projectRoot, payload);
+  const ledger = await readExecutionLedger(projectRoot, payload) || {};
+
+  // A session ledger with activity proves this session was routed and accumulating evidence.
+  // If the route state is now missing or unreadable (router crashed/timed out before
+  // persisting it, or the session stamp was lost), the gate cannot evaluate completion — and
+  // ending silently there is indistinguishable from a mid-run stall. Surface the loss so the
+  // user sees WHY the run released. Sessions that were never routed (no ledger activity at
+  // all) stay silent: there is nothing to report (silent-success carve-out).
+  if (!state) {
+    const hasActivity = ledger.sourceSucceeded || ledger.writeAttempted
+      || ledger.verificationAttempted || (ledger.receipts || []).length > 0;
+    if (!hasActivity) return;
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: 'UKit completion gate: route state for this session was lost before the stop was evaluated (router did not persist it), so unfinished work could not be verified. Send the task again in a new message to re-route and finish it.',
+    })}\n`);
+    return;
+  }
+
+  const result = evaluateCompletion({ state, ledger });
+
+  // A reentrant Stop (Claude Code re-fires Stop after this hook already blocked once) is
+  // gated exactly like any other Stop: while evidence is still missing it blocks again with
+  // the actionable reason instead of silently releasing the recovery turn. Loop termination
+  // is guaranteed elsewhere — non-vibecode routes end at the continuation cap (final-notice
+  // block -> capped visible release), and vibecode ends on the visible verification-loop
+  // blocker.
+  if (result.continue) {
+    if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
+    else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state));
+    process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
+    return;
+  }
+  if (result.capped || result.notify) {
+    // Non-blocking endings (non-gated modes, an invisible blocker, an evidence-less route, or
+    // cap reached after the final notice) must still tell the user what is unfinished — a
+    // silent end is indistinguishable from a stall.
+    process.stderr.write(`[ukit-completion] ${result.reason}\n`);
+    process.stdout.write(`${JSON.stringify({ systemMessage: result.reason })}\n`);
+    return;
+  }
+  if (result.complete) return; // silent success: route present, all evidence satisfied
+  // Defensive final else: no evaluation result may ever end a routed stop silently.
+  const fallback = `UKit completion gate: the stop was evaluated without a decision (missing evidence: ${(result.missingEvidence || []).join(', ') || 'none'}). If work is unfinished, re-send the task in a new message.`;
+  process.stderr.write(`[ukit-completion] ${fallback}\n`);
+  process.stdout.write(`${JSON.stringify({ systemMessage: fallback })}\n`);
+}
+
 async function main() {
+  // Dispatch the stop flag BEFORE parsing stdin: a malformed payload used to throw out of
+  // main(), hit the .catch (stderr + exit 1) with no decision, and release the stop silently.
+  if (process.argv.includes('--evaluate-stop')) {
+    await runEvaluateStop();
+    return;
+  }
   const payload = JSON.parse((await readStdin()) || '{}');
   const projectRoot = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
   if (process.argv.includes('--record')) {
@@ -917,44 +1073,6 @@ async function main() {
       toolName: payload.tool_name,
       harness: process.env.UKIT_HARNESS || 'claude-code',
     });
-    return;
-  }
-  if (process.argv.includes('--evaluate-stop')) {
-    const state = await readRouteState(projectRoot, payload);
-    const ledger = await readExecutionLedger(projectRoot, payload) || {};
-    const result = evaluateCompletion({ state, ledger });
-
-    // A session ledger with activity proves this session was routed and accumulating
-    // evidence. If the route state is now missing or unreadable (router crashed/timed out
-    // before persisting it, or the session stamp was lost), the gate cannot evaluate
-    // completion — and ending silently there is indistinguishable from a mid-run stall.
-    // Surface the loss so the user sees WHY the run released. Sessions that were never
-    // routed (no ledger activity at all) stay silent: there is nothing to report.
-    if (!state && (ledger.sourceSucceeded || ledger.writeAttempted
-      || ledger.verificationAttempted || (ledger.receipts || []).length > 0)) {
-      process.stdout.write(`${JSON.stringify({
-        systemMessage: 'UKit completion gate: route state for this session was lost before the stop was evaluated (router did not persist it), so unfinished work could not be verified. Send the task again in a new message to re-route and finish it.',
-      })}\n`);
-      return;
-    }
-
-    // A reentrant Stop (Claude Code re-fires Stop after this hook already blocked once) is
-    // gated exactly like any other Stop: while evidence is still missing it blocks again
-    // with the actionable reason instead of silently releasing the recovery turn. Loop
-    // termination is guaranteed elsewhere — non-vibecode routes end at the continuation cap
-    // (final-notice block -> capped visible release), and vibecode ends on the visible
-    // verification-loop blocker.
-
-    if (result.continue) {
-      if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
-      else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state));
-      process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
-    } else if (result.capped || result.notify) {
-      // Non-blocking endings (non-gated modes, or cap reached after the final notice) must
-      // still tell the user what is unfinished — a silent end is indistinguishable from a stall.
-      process.stderr.write(`[ukit-completion] ${result.reason}\n`);
-      process.stdout.write(`${JSON.stringify({ systemMessage: result.reason })}\n`);
-    }
   }
 }
 

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

@@ -14,7 +14,6 @@ import {
   evidencePromptKey,
   incrementContinuation,
   markNotified,
-  noteStopProgress,
   readExecutionLedger,
   readRouteState,
   recordExecutionReceipt,
@@ -634,23 +633,6 @@ export async function runSessionStop(
   }
 
   if (suppliedLedger === undefined) {
-    // Claude Code flags reentrant stops with stop_hook_active and the ledger CLI releases on
-    // them; omp's session_stop carries no such field. Detect the equivalent from the ledger:
-    // when the recovery turn produced no new receipts since the stop that blocked it,
-    // blocking again would only burn another turn in a self-sustaining loop — release with a
-    // visible reason instead. Vibecode autonomy keeps pushing (same as the CLI valve).
-    let reentrantStop = false;
-    try {
-      reentrantStop = (await noteStopProgress(projectRoot, payload)).reentrant === true;
-    } catch {
-      reentrantStop = false;
-    }
-    if (reentrantStop && state?.routeSummary?.autonomyLevel !== 'vibecode') {
-      const notice = `UKit stopped automatic recovery after one continuation: ${evaluation.reason}`;
-      pi.logger?.warn?.(`[UKit] ${notice}`);
-      sendContext(pi, [notice], 'nextTurn', { display: true });
-      return undefined;
-    }
     try {
       if (evaluation.finalNotice) await markNotified(projectRoot, payload, ledger);
       else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state));