@ngockhoale/ukit 3.4.59 → 3.4.60

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.60 - 2026-10-22
+
+**Completion Gate: a background completion footer is no longer trusted on its own.**
+- Gap: 3.4.59 accepted `[exited with code N]` at the end of `.../tasks/<id>.output` as the runner's exit status. That file holds the runner's own stdout, so a process (or a test fixture) that prints the footer while still running, or before a non-zero exit, could produce a false PASS.
+- Fix: a completion is accepted only when the session transcript holds the HOST's `<task-notification>` for the same task id (queue event or plain user turn; tool-result text, including a Read of the output file, never counts) and its exit code equals the footer. No notification -> `no-host-notification`; disagreement -> `host-footer-mismatch`. A host-reported failure is recorded as failed.
+- Regression: `tests/hooks/backgroundCompletionForgery.test.js` (footer printed while running, imitation notification inside a tool result, matching notification, mismatching exit, host failure, other task id); lifecycle tests now mirror the host notification.
+- Limit: needs `transcript_path` in the hook payload (Claude Code provides it); without it a background completion stays unproven. omp/Codex shapes not covered; replay, not a live host.
+
 ## 3.4.59 - 2026-10-22
 
 **Completion Gate: a host-backgrounded verification can now complete through a supported, provenance-bound result capture.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.59",
+  "version": "3.4.60",
   "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

@@ -803,6 +803,29 @@ function flattenText(value, depth = 0) {
   return ['content', 'text', 'stdout', 'output', 'file'].map((k) => flattenText(value[k], depth + 1)).filter(Boolean).join('\n');
 }
 
+// Exit status the HOST reported for a background task: a `<task-notification>` delivered as a queue event or a
+// plain user turn. Tool results (runner-controlled text, including a Read of the output file) never count.
+function hostCompletionExit(transcriptPath, id) {
+  if (!transcriptPath || !id) return null;
+  let raw;
+  try { raw = fsSync.readFileSync(transcriptPath, 'utf8'); } catch { return null; }
+  const marker = `<task-id>${id}</task-id>`;
+  let found = null;
+  for (const line of raw.split('\n')) {
+    if (!line.includes(marker)) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    let text = null;
+    if (o?.type === 'queue-operation' && o.operation === 'enqueue' && typeof o.content === 'string') text = o.content;
+    else if (o?.type === 'user' && typeof o.message?.content === 'string') text = o.message.content;
+    if (!text || !text.trimStart().startsWith('<task-notification>')) continue;
+    if (!text.includes(marker)) continue;
+    const m = /\(exit code (-?\d+)\)/.exec(text);
+    if (m) found = Number(m[1]);
+  }
+  return found;
+}
+
 // A host-backgrounded run completes OUTSIDE any tool event the hooks see (a task-notification system
 // event). The supported capture is the host-written task output file: when the agent Reads
 // `.../tasks/<id>.output` and its LAST line is the host footer `[exited with code N]`, that status is the
@@ -816,6 +839,11 @@ async function backgroundCompletionFor({ projectRoot, payload, toolInput, toolRe
   const tail = flattenText(toolResponse).replace(/\s+$/, '');
   const footer = /\[exited with code (-?\d+)\]$/.exec(tail);
   if (!footer) return { rejected: 'no-exit-footer' };
+  // The footer lives in a file the runner can write to, so it is only a cross-check. The authority is the
+  // host's own task-notification in the session transcript (a runner cannot write there).
+  const hostExit = hostCompletionExit(payload?.transcript_path || payload?.transcriptPath, id);
+  if (hostExit === null) return { rejected: 'no-host-notification' };
+  if (hostExit !== Number(footer[1])) return { rejected: 'host-footer-mismatch' };
   const ledger = await readExecutionLedger(projectRoot, payload);
   const receipts = ledger?.receipts || [];
   const launch = receipts.find((r) => r.kind === 'verification' && r.backgroundTaskId === id && !r.backgroundCompletion);