@ngockhoale/ukit 3.4.58 → 3.4.59

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.59 - 2026-10-22
+
+**Completion Gate: a host-backgrounded verification can now complete through a supported, provenance-bound result capture.**
+- Gap: 3.4.57 made a background launch acknowledgement unproven, but nothing could later turn it into evidence, so the only route was re-running a long suite in the foreground. Claude Code delivers the completion as a task-notification the hooks never see; the host does write the runner's output to `.../tasks/<id>.output` ending in `[exited with code N]`.
+- Fix: when the agent reads that file back, the ledger records a verification receipt bound to the launch receipt by `backgroundTaskId` (same task ledger, so another task/session finds no launch), exit status from the host footer, judged against the LAUNCH tree fingerprint. Rejected: no footer (still running / "passed" text only), no matching launch, duplicate completion, output file older than the launch. Exit 1 yields a failed verdict.
+- Regression: `tests/hooks/backgroundCompletionLifecycle.test.js` (success, failure, partial, duplicate, other task, other session, late, stale file, unrelated file, Stop-gate outcomes). Also `tests/orchestration/schedulingHarness.test.js`: a deterministic offline scheduling-logic model (not a throughput benchmark).
+- Limit: replay of the host file format observed on Claude Code; omp/Codex background shapes are not covered, and no hook receives the notification itself.
+
 ## 3.4.58 - 2026-10-22
 
 **Completion Gate: plain publish orders create the registry obligation, new tasks do not inherit the previous task's evidence, and a Vietnamese status line about a config is not a config order.**

package/package.json

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

@@ -786,6 +786,56 @@ function isBackgroundLaunchAck(response) {
     && /^\s*Command running in background with ID: \S+/.test(response);
 }
 
+// Id of the host background task a launch acknowledgement names (structured field first).
+function backgroundTaskIdOf(response) {
+  if (response && typeof response === 'object' && !Array.isArray(response)) {
+    if (typeof response.backgroundTaskId === 'string' && response.backgroundTaskId) return response.backgroundTaskId;
+    return backgroundTaskIdOf(response.stdout ?? response.output ?? response.content);
+  }
+  const m = typeof response === 'string' ? /^\s*Command running in background with ID: ([A-Za-z0-9_-]+)/.exec(response) : null;
+  return m ? m[1] : null;
+}
+
+function flattenText(value, depth = 0) {
+  if (typeof value === 'string') return value;
+  if (!value || typeof value !== 'object' || depth > 4) return '';
+  if (Array.isArray(value)) return value.map((v) => flattenText(v, depth + 1)).join('\n');
+  return ['content', 'text', 'stdout', 'output', 'file'].map((k) => flattenText(value[k], depth + 1)).filter(Boolean).join('\n');
+}
+
+// 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
+// runner's exit status. It is bound to the launch receipt by `backgroundTaskId` (same task ledger, so a
+// completion for another task/session finds no launch), counted once, and judged against the tree that
+// was tested at LAUNCH. A bare "passed" line, a partial read, or a path whose id has no launch is no proof.
+async function backgroundCompletionFor({ projectRoot, payload, toolInput, toolResponse }) {
+  const file = String(toolInput?.file_path || toolInput?.path || '');
+  const id = /[\\/]tasks[\\/]([A-Za-z0-9_-]+)\.output$/.exec(file)?.[1];
+  if (!id) return null;
+  const tail = flattenText(toolResponse).replace(/\s+$/, '');
+  const footer = /\[exited with code (-?\d+)\]$/.exec(tail);
+  if (!footer) return { rejected: 'no-exit-footer' };
+  const ledger = await readExecutionLedger(projectRoot, payload);
+  const receipts = ledger?.receipts || [];
+  const launch = receipts.find((r) => r.kind === 'verification' && r.backgroundTaskId === id && !r.backgroundCompletion);
+  if (!launch) return { rejected: 'no-matching-launch' };
+  if (receipts.some((r) => r.backgroundCompletion === id)) return { rejected: 'duplicate-completion' };
+  let mtime = null;
+  try { mtime = fsSync.statSync(file).mtimeMs; } catch { return { rejected: 'output-file-missing' }; }
+  if (mtime + 2000 < launch.ts) return { rejected: 'output-predates-launch' };
+  const exitCode = Number(footer[1]);
+  const success = exitCode === 0;
+  const lv = launch.verdict || {};
+  const kind = success ? (isTestGateCommand(launch.command) ? 'test-verified' : 'check-only') : 'failed';
+  return {
+    kind: 'verification', command: launch.command, success, exitCode, backgroundCompletion: id,
+    ...(launch.scope ? { scope: launch.scope } : {}),
+    ...(launch.workspaceFp ? { workspaceFp: launch.workspaceFp } : {}),
+    verdict: { ...lv, kind, evidence: launch.command, verifier: lv.verifier || 'self', ts: new Date().toISOString() },
+  };
+}
+
 function noteUnprovenExitStatus(stage) {
   if (!ledgerMessageEmitter) return;
   const message =
@@ -803,7 +853,7 @@ function compactReceipt(receipt) {
     kind: receipt.kind,
     success: receipt.success,
   };
-  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error', 'verdict', 'evidence', 'evidenceSurface', 'class', 'status', 'detail', 'operation', 'transportSuccess', 'taskInstanceId', 'sessionKey', 'sequence', 'exitStatusUnproven', 'agentId', 'agentType', 'contentSha']) {
+  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error', 'verdict', 'evidence', 'evidenceSurface', 'class', 'status', 'detail', 'operation', 'transportSuccess', 'taskInstanceId', 'sessionKey', 'sequence', 'exitStatusUnproven', 'backgroundTaskId', 'backgroundCompletion', 'agentId', 'agentType', 'contentSha']) {
     if (receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
       compact[key] = key === 'operation' ? compactOperation(receipt[key]) : receipt[key];
     }
@@ -1728,7 +1778,7 @@ function newEventId() {
   return `${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
 }
 
-const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope', 'workspaceFp', 'workspaceRoot', 'workspaceHeadTs', 'bashReadOnly', 'exitStatusUnproven', 'detail', 'operation', 'transportSuccess', 'taskInstanceId', 'sessionKey', 'sequence', 'agentId', 'agentType', 'contentSha', 'handback', 'review', 'verdict'];
+const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope', 'workspaceFp', 'workspaceRoot', 'workspaceHeadTs', 'bashReadOnly', 'exitStatusUnproven', 'backgroundTaskId', 'backgroundCompletion', 'detail', 'operation', 'transportSuccess', 'taskInstanceId', 'sessionKey', 'sequence', 'agentId', 'agentType', 'contentSha', 'handback', 'review', 'verdict'];
 
 // TASK-009 (BL-011): evidence attestations are whitelisted verbatim — class /
 // surface / result / claim, the ARCH §Evidence Schema fields a receipt may
@@ -3150,13 +3200,17 @@ export async function recordExecutionReceipt({
   // command has not finished, so that response carries no exit status. It must never mint
   // verification or operation evidence (completion arrives later, outside this tool event).
   const backgroundLaunchAck = toolName === 'Bash' && isBackgroundLaunchAck(toolResponse);
+  const bgCompletion = toolName === 'Read'
+    ? await backgroundCompletionFor({ projectRoot, payload, toolInput, toolResponse }) : null;
   const nativeGoal = routeState?.routeSummary?.executionContract?.operationGoal;
   const operationReceipt = backgroundLaunchAck ? null : cronOperationReceipt(toolName, toolInput, toolResponse, success, { sessionId: explicitSessionId(payload), harness })
     || (toolName === 'Bash' && !bashScope.foreign
       ? (bashOperationReceipt(toolInput.command, toolResponse, success, nativeGoal, { sessionId: explicitSessionId(payload), harness })
         || releaseOperationReceipt(toolInput.command, toolResponse, success, { sessionId: explicitSessionId(payload), harness }))
       : null);
-  if (operationReceipt) {
+  if (bgCompletion && !bgCompletion.rejected) {
+    Object.assign(receipt, bgCompletion);
+  } else if (operationReceipt) {
     Object.assign(receipt, operationReceipt);
   } else if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
     receipt.kind = 'source';
@@ -3182,6 +3236,7 @@ export async function recordExecutionReceipt({
     receipt.command = String(toolInput.command || '').trim();
     // A pipe-masked runner status (exit 0 from `| tail`) is not evidence of a pass.
     const maskedStage = isVerificationCommand(toolInput.command) ? maskedVerificationStage(toolInput.command) : null;
+    if (backgroundLaunchAck) receipt.backgroundTaskId = backgroundTaskIdOf(toolResponse);
     if (backgroundLaunchAck && receipt.success) {
       receipt.success = false;
       receipt.exitStatusUnproven = true;
@@ -3243,7 +3298,8 @@ export async function recordExecutionReceipt({
     }
   }
   if (workspaceFp) {
-    receipt.workspaceFp = workspaceFp;
+    // A background completion is judged against the tree that was tested at LAUNCH, never today's tree.
+    receipt.workspaceFp = bgCompletion && !bgCompletion.rejected && bgCompletion.workspaceFp ? bgCompletion.workspaceFp : workspaceFp;
     if (workspaceRoot !== projectRoot) {
       receipt.workspaceRoot = workspaceRoot;
       const ct = Number(gitOutput(['log', '-1', '--format=%ct'], workspaceRoot));