@ngockhoale/ukit 3.4.49 → 3.4.50

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.50 - 2026-10-21
+
+**Verification exit-proof integrity (long-run OMP field audit).**
+- Fix execution-ledger false PASS receipts: a bare `pipefail`/`PIPESTATUS` word (e.g. `echo pipefail`) no longer exempts a masked pipe; only real `set -o pipefail` before the pipe or an immediate `exit ${PIPESTATUS[n]}` with the correct index proves the runner status.
+- A runner followed by `|| …`, backgrounded with `&`, inside a `for`/`while`/`case` flow, behind `bash -c` hiding a masked pipe, or followed by `exit 0`/`true`/`:`/leading `!` is recorded as `exitStatusUnproven` (not passing). Claude `tool_response.interrupted:true` now counts as failure.
+- Bare runners, `cd repo; runner`, `&&` chains, real pipefail and terminal subshell/group runners stay accepted. Sequential consumers (including `; echo "exit=$?"`) and `if runner; then echo ok; fi` no longer receive PASS credit: recognizing a runner attempt does not prove its exit. Loop keywords as runner arguments (`vitest -t case`) are not loops.
+- Audit report: `UKIT_LONG_RUN_ORCHESTRATION_AUDIT.md`. Verified locally on macOS/Node 22 only; OMP live host-ordering attribution remains UNVERIFIED. No CI dispatch.
+
 ## 3.4.49 - 2026-10-19
 
 **Conditional consumer verification intent closure.**

package/manifests/documentation.yaml

@@ -71,6 +71,17 @@ entries:
     validation: [manual]
     archive_policy: never
     notes: release record
+  - id: root-long-run-orchestration-audit
+    path: UKIT_LONG_RUN_ORCHESTRATION_AUDIT.md
+    class: canonical
+    audience: [owner, maintainer]
+    owner: runtime
+    source_of_truth: UKIT_LONG_RUN_ORCHESTRATION_AUDIT.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual, test:tests/hooks/executionLedger.test.js, test:tests/hooks/verificationExitProof.test.js]
+    archive_policy: replace-with-snapshot
+    notes: evidence-based long-run field audit; current reproductions are distinct from incident attribution
   - id: registry-self
     path: manifests/documentation.yaml
     class: canonical

package/package.json

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

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

@@ -460,6 +460,10 @@ function explicitError(payload = {}) {
   return [
     payload.isError,
     payload.is_error,
+    payload.interrupted,
+    payload.tool_output?.interrupted,
+    payload.tool_result?.interrupted,
+    payload.tool_response?.interrupted,
     payload.tool_output?.isError,
     payload.tool_output?.is_error,
     payload.tool_result?.isError,
@@ -530,8 +534,8 @@ function extractExitCode(payload = {}) {
   return null;
 }
 
-// The trailing boundary accepts shell terminators (`;`, `&`, `|`, `)`) so
-// `yarn release:verify; echo "exit=$?"` — the real-exit-code idiom — still mints a receipt.
+// Recognize runner presence separately from exit proof. A trailing echo of `$?`
+// can report a status in text but cannot make the wrapper's exit authoritative.
 // Blank out quoted literals so `echo '(jest passed)'` / `git commit -m "run yarn test"` do not
 // look like a runner invocation. A `bash|sh|zsh -c '<script>'` wrapper really executes its
 // quoted script, so that script is tested on its own (bounded recursion).
@@ -584,71 +588,94 @@ function isVerificationCommand(command, depth = 0) {
   ].some((pattern) => pattern.test(text));
 }
 
-// Split a shell command into pipelines of stages (quote/escape aware). `&&`, `||`, `;` and
-// newlines separate pipelines; a lone `|` (or `|&`) separates stages. Redirections such as
-// `2>&1` / `&>` are not separators.
-function shellPipelineStages(command) {
-  const text = String(command || '');
-  const pipelines = [];
-  let stages = [];
+// Bounded shell exit-proof recognition, not a shell interpreter. Keep separators so a
+// later echo/OR/background job cannot turn a child runner failure into verification PASS.
+function verificationShellUnits(command) {
+  const units = [];
   let buffer = '';
   let quote = null;
   let escaped = false;
-  const closeStage = () => {
-    if (buffer.trim()) stages.push(buffer.trim());
-    buffer = '';
-  };
-  const closePipeline = () => {
-    closeStage();
-    if (stages.length) pipelines.push(stages);
-    stages = [];
-  };
-  for (let i = 0; i < text.length; i += 1) {
-    const char = text[i];
+  const close = (separator) => { units.push({ text: buffer.trim(), separator }); buffer = ''; };
+  for (let i = 0; i < command.length; i += 1) {
+    const char = command[i];
     if (escaped) { escaped = false; buffer += char; continue; }
-    if (char === '\\') { escaped = true; buffer += char; continue; }
+    if (char === '\\' && quote !== "'") { escaped = true; buffer += char; continue; }
     if (quote) { if (char === quote) quote = null; buffer += char; continue; }
     if (char === "'" || char === '"') { quote = char; buffer += char; continue; }
-    if (char === '|') {
-      if (text[i + 1] === '|') { closePipeline(); i += 1; continue; }
-      closeStage();
-      if (text[i + 1] === '&') i += 1;
+    if (char === '#' && (!buffer || /\s$/.test(buffer))) {
+      while (i < command.length && command[i] !== '\n') i += 1;
+      if (i < command.length) close(';');
       continue;
     }
-    if (char === '&') {
-      if (text[i + 1] === '&') { closePipeline(); i += 1; continue; }
-      buffer += char; // `2>&1`, `&>file`, trailing background `&`
+    if (char === '&' && (/[<>]$/.test(buffer) || command[i + 1] === '>')) { buffer += char; continue; }
+    if (char === '|' || char === '&') {
+      const next = command[i + 1];
+      const separator = next === char ? char + next : char === '|' && next === '&' ? '|&' : char;
+      close(separator);
+      if (separator.length === 2) i += 1;
       continue;
     }
-    if (char === ';' || char === '\n') { closePipeline(); continue; }
+    if (char === ';' || char === '\n' || char === '\r') { close(';'); continue; }
     buffer += char;
   }
-  closePipeline();
-  return pipelines;
+  if (quote || escaped) return null;
+  if (buffer.trim()) close('');
+  return units.filter((unit) => unit.text || unit.separator !== ';');
 }
 
-// A shell pipeline exits with its LAST stage's status, so `npx vitest run | tail` is exit 0
-// even when vitest failed. A verification command in a non-final stage therefore has an
-// unproven exit status — unless the command enables `pipefail` or reads `PIPESTATUS`.
-// Returns the masked verification stage (string) or null.
-function maskedVerificationStage(command) {
-  const text = String(command || '');
-  if (/\bpipefail\b|\bPIPESTATUS\b|\bpipestatus\b/.test(text)) return null;
-  for (const stages of shellPipelineStages(text)) {
-    for (const stage of stages.slice(0, -1)) {
-      if (isVerificationCommand(stage)) return stage;
+function maskedVerificationStage(command, depth = 0) {
+  const text = String(command || '').trim();
+  const units = verificationShellUnits(text);
+  if (!units?.length || depth > 2) return text;
+  let pipefail = false;
+  let sawRunner = false;
+  for (let i = 0; i < units.length; i += 1) {
+    const unit = units[i];
+    const plain = maskQuotedLiterals(unit.text);
+    // Unsupported flow may skip a runner or discard an earlier iteration's failure.
+    // Parens, braces and `if` are not interpreted here. A sequential consumer must not
+    // turn the status of an earlier runner into PASS, even when it prints that status.
+    if (sawRunner && units[i - 1]?.separator === ';' && !/^[)}]+$/.test(plain)) return unit.text;
+    // Command position only: `vitest -t case` is an argument, not a loop.
+    if (/^(?:for|while|until|case|function|done)\b/.test(plain)) return unit.text;
+    // A later `exit 0`/`true`/`:` replaces the runner's status; a leading `!` inverts it.
+    if (sawRunner && /^(?:exit\s+0|true|:)$/.test(plain)) return unit.text;
+    if (/^!\s/.test(plain) && isVerificationCommand(unit.text)) return unit.text;
+    if (unit.separator === '||' || unit.separator === '&') return unit.text;
+    const enable = /^set\s+-(?:[a-z]*o)\s+pipefail$/.test(plain);
+    const disable = /^set\s+\+(?:[a-z]*o)\s+pipefail$/.test(plain);
+    if (enable || disable) pipefail = enable;
+    let runner = isVerificationCommand(unit.text);
+    // Only an entire simple shell wrapper can inherit the inner script's proof.
+    const wrapper = unit.text.match(/^(?:bash|sh|zsh|dash|ksh)\s+(?:-o\s+\w+\s+|-[a-z]+\s+)*(-[a-z]*c)\s+(?:'([^']*)'|"((?:[^"\\]|\\.)*)")$/);
+    if (runner && wrapper) {
+      if (maskedVerificationStage(wrapper[2] ?? wrapper[3] ?? '', depth + 1)) return unit.text;
+    } else if (runner && /(?:^|\s)(?:bash|sh|zsh|dash|ksh)\s/.test(plain)) return unit.text;
+    if (runner) sawRunner = true;
+    if (unit.separator === '|' || unit.separator === '|&') {
+      if (runner && !pipefail) {
+        // A single runner's immediate Bash PIPESTATUS read can propagate its status.
+        let end = i;
+        while (units[end]?.separator === '|' || units[end]?.separator === '|&') end += 1;
+        const proof = units[end + 1];
+        const expected = `exit ${'${'}PIPESTATUS[${i - (units.slice(0, i).findLastIndex((u) => u.separator !== '|' && u.separator !== '|&') + 1)}]}`;
+        if (units[end]?.separator !== ';' || proof?.text !== expected || proof.separator
+          || units.slice(i + 1, end + 1).some((u) => isVerificationCommand(u.text))) return unit.text;
+        return null;
+      }
+      continue;
     }
   }
-  return null;
+  return sawRunner ? null : text;
 }
 
 // Announce through the in-proc hook emitter only (never fd 1 from library callers).
 function noteUnprovenExitStatus(stage) {
   if (!ledgerMessageEmitter) return;
   const message =
-    `UKit execution-ledger: \`${stage}\` ran in a pipeline, so the exit status belongs to the last pipe stage `
-    + '(e.g. tail/grep), not the test runner — it is NOT counted as passing verification. '
-    + 'Re-run with `set -o pipefail; <cmd> | tail` (or without the pipe) to prove the result.';
+    `UKit execution-ledger: runner exit status is unproven for \`${stage}\` — `
+    + 'the shell wrapper may mask or skip the runner; it is NOT counted as passing verification. '
+    + 'Re-run the bare verification command in the same workspace, without loops, backgrounding or status-swallowing consumers.';
   try {
     ledgerMessageEmitter(`${JSON.stringify({ systemMessage: message })}\n`);
   } catch { /* an emitter failure never loses the ledger event */ }