@kontourai/flow-agents 4.1.0 → 4.2.1

package/scripts/hooks/lib/liveness-write.js

@@ -18,27 +18,127 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
 
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+const FALSY = new Set(['0', 'false', 'no', 'off']);
+// Cheap per-process memo keyed by the exact env inputs, so a throttled hot path does at most one
+// conf read per (env flag, conf path) signature. Keyed inputs make unit tests that vary
+// TELEMETRY_CONFIG_FILE independent.
+const relayEnabledCache = new Map();
+
+/**
+ * The console-conf resolution chain, mirroring scripts/telemetry/lib/config.sh's slot order:
+ *   1. TELEMETRY_CONFIG_FILE (env) if set + readable
+ *   2. per-workspace override: <workspace-root>/.kontourai/telemetry-console.conf
+ *   3. user-global durable override: ~/.flow-agents/telemetry-console.conf
+ *   4. the shipped default: scripts/telemetry/telemetry.conf (relative to this file)
+ * Slot 4's path is <this file>/../../telemetry/telemetry.conf; the workspace root for slot 2 is
+ * three levels up from scripts/hooks/lib. This resolver is only the SPAWN pre-gate — it is
+ * intentionally lenient (no mode-600 trust gate). relay.sh re-sources config.sh, which applies the
+ * trust gate and is the authoritative decision for both enablement and the POST endpoint, so a
+ * lenient "enabled" here at worst spawns a relay.sh that then trust-gates itself to a no-op.
+ *
+ * ACCEPTED, BY DESIGN (security review LOW, A04): because this pre-gate does NOT re-apply
+ * config.sh's mode-600/owner gate, it can read an explicit key from an UNtrusted default-path conf
+ * (a mode-644 .kontourai/telemetry-console.conf a local tool dropped) that config.sh would skip.
+ * This is fail-toward-no-op, never fail-toward-exfil: the only divergence is (a) we spawn a
+ * relay.sh that config.sh then no-ops (harmless), or (b) an untrusted `=0` here suppresses a spawn
+ * that a trusted conf would have enabled (a missed pulse — availability only, requiring local FS
+ * write access). The pre-gate deliberately does not guarantee relay AVAILABILITY — only that we
+ * avoid spawning when nothing plausibly enables it. It NEVER weakens the exfil defense, which lives
+ * entirely in relay.sh's authoritative, trust-gated re-resolution.
+ * @returns {string|null}  first readable conf path, or null
+ */
+function resolveConsoleConfPath(env) {
+  const candidates = [
+    env.TELEMETRY_CONFIG_FILE,
+    path.join(__dirname, '..', '..', '..', '.kontourai', 'telemetry-console.conf'),
+    path.join(os.homedir(), '.flow-agents', 'telemetry-console.conf'),
+    path.join(__dirname, '..', '..', 'telemetry', 'telemetry.conf'),
+  ];
+  for (const c of candidates) {
+    try {
+      if (c && fs.existsSync(c) && fs.statSync(c).isFile()) return c;
+    } catch {
+      /* keep scanning */
+    }
+  }
+  return null;
+}
+
+/**
+ * Conf-driven liveness relay enablement (#567 — parity with the economics relay #469, so an
+ * operator enables via `console_liveness_relay=1` in the console conf, NOT an env var/.profile).
+ * Precedence mirrors config.sh's economics rule EXACTLY (config.sh:182-204): an explicit
+ * `console_liveness_relay` conf key wins over the env var; absent a key, a pre-set env var is
+ * honored; absent both, default ON once a console sink is configured (any console_*url key present)
+ * — opt-out, not silent-off. Best-effort and cheap: any FS/parse failure falls back to the env-only
+ * decision; never throws. This is the spawn pre-gate; relay.sh+config.sh is authoritative.
+ */
+function resolveLivenessRelayEnabled(env) {
+  const envFlag = String(env.FLOW_AGENTS_CONSOLE_LIVENESS_RELAY || '').toLowerCase();
+  const envDecision = TRUTHY.has(envFlag) ? true : FALSY.has(envFlag) ? false : null;
+  const cacheKey = `${envFlag}|${env.TELEMETRY_CONFIG_FILE || ''}`;
+  if (relayEnabledCache.has(cacheKey)) return relayEnabledCache.get(cacheKey);
+  let enabled;
+  try {
+    let explicit = null;
+    let hasConsoleUrl = false;
+    const confPath = resolveConsoleConfPath(env);
+    if (confPath) {
+      for (const raw of fs.readFileSync(confPath, 'utf8').split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#')) continue;
+        const eq = line.indexOf('=');
+        if (eq < 0) continue;
+        const key = line.slice(0, eq).trim();
+        const value = line.slice(eq + 1).trim().toLowerCase();
+        if (key === 'console_liveness_relay') {
+          if (TRUTHY.has(value)) explicit = true;
+          else if (FALSY.has(value)) explicit = false;
+        } else if (key === 'console_telemetry_url' || key === 'console_url' || key === 'console_telemetry_endpoint_url') {
+          if (value) hasConsoleUrl = true;
+        }
+      }
+    }
+    // config.sh precedence: explicit conf key > pre-set env var > default-on when a console url resolves.
+    enabled = explicit !== null ? explicit : envDecision !== null ? envDecision : hasConsoleUrl;
+  } catch {
+    enabled = envDecision === true; // best-effort: honor only an explicit env-on if the conf read failed
+  }
+  relayEnabledCache.set(cacheKey, enabled);
+  return enabled;
+}
+
 /**
- * OPTIONAL console liveness relay (#295, ADR 0021 §4/§7). Best-effort, FULLY detached mirror of a
- * liveness event to the hosted Console via `scripts/liveness/relay.sh`. Local-first is sacred: this
- * runs AFTER the durable local append and can never block, throw, or affect it — gated on
- * `FLOW_AGENTS_CONSOLE_LIVENESS_RELAY`, the whole thing wrapped so any failure (missing script,
- * spawn error) is swallowed. No flag ⇒ a single cheap env read and return (true no-op).
+ * OPTIONAL console liveness relay (#295, ADR 0021 §4/§7; conf-driven per #567). Best-effort, FULLY
+ * detached mirror of a liveness event to the hosted Console via `scripts/liveness/relay.sh`.
+ * Local-first is sacred: this runs AFTER the durable local append and can never block, throw, or
+ * affect it — gated on `resolveLivenessRelayEnabled`, the whole thing wrapped so any failure
+ * (missing script, spawn error) is swallowed. Not enabled ⇒ a cheap resolve and return (true no-op).
  *
  * @param {object} evt  The liveness event just written locally.
  * @returns {void}
  */
 function relayLivenessEvent(evt) {
   try {
-    const flag = String(process.env.FLOW_AGENTS_CONSOLE_LIVENESS_RELAY || '').toLowerCase();
-    if (flag !== '1' && flag !== 'true' && flag !== 'yes' && flag !== 'on') return;
+    if (!resolveLivenessRelayEnabled(process.env)) return;
     // scripts/hooks/lib/ -> scripts/liveness/relay.sh (same relative layout in dist/* bundles).
     const relay = path.join(__dirname, '..', '..', 'liveness', 'relay.sh');
     if (!fs.existsSync(relay)) return;
-    const child = spawn('bash', [relay, JSON.stringify(evt)], { detached: true, stdio: 'ignore' });
+    // Pass the environment through UNCHANGED — do not force the enable flag. relay.sh re-sources
+    // config.sh, which is the authoritative, trust-gated decision for both enablement (conf key >
+    // env > default-on) and the POST endpoint. Our resolve above is only a lenient spawn pre-gate:
+    // if we enabled from an untrusted default-path conf, config.sh trust-gates relay.sh to a no-op
+    // rather than us bypassing it by forcing the flag on.
+    const child = spawn('bash', [relay, JSON.stringify(evt)], {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env,
+    });
     child.on('error', () => {}); // never surface a spawn failure
     child.unref(); // fully detach — the parent never waits on the relay
   } catch {
@@ -70,4 +170,4 @@ function appendLivenessEvent(root, evt) {
   relayLivenessEvent(evt); // then optionally mirror to the Console — best-effort, detached, off by default
 }
 
-module.exports = { livenessStreamFile, appendLivenessEvent };
+module.exports = { livenessStreamFile, appendLivenessEvent, resolveLivenessRelayEnabled };

package/scripts/liveness/relay.sh

@@ -7,26 +7,36 @@
 # never forked). The Console side ingests this record type and projects the fleet view + runs the
 # janitor (console repo #125); this script is only the flow-agents EMIT half.
 #
-# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
-# is enabled AND a console endpoint is configured. Best-effort throughout — it must NEVER block, slow,
-# or fail the local liveness write that already happened before this was invoked. Every failure path
-# is a quiet `exit 0`.
+# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless the liveness relay is enabled AND a
+# console endpoint is configured. Enablement is conf-driven (#567, parity with economics #469): an
+# operator sets `console_liveness_relay=1` in the console conf (or it defaults on once a console url
+# resolves) — NOT an env var. config.sh (sourced below) is the authoritative, trust-gated decision
+# and also supplies the endpoint/token/tenant from the conf. Best-effort throughout — it must NEVER
+# block, slow, or fail the local liveness write that already happened before this was invoked. Every
+# failure path is a quiet `exit 0`.
 #
 # Invoked (fully detached, best-effort) from scripts/hooks/lib/liveness-write.js after the durable
 # local append. Usage: relay.sh '<liveness-event-json>'
 set -uo pipefail
 
-# Opt-in gate — off by default.
-case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
-  1 | true | TRUE | yes | on) ;;
-  *) exit 0 ;;
-esac
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 0
 
 # transport.sh sources ${TELEMETRY_DIR}/lib/redact.sh at load — point it at the telemetry lib dir,
 # then reuse the SAME console POST core the telemetry mirror uses.
 export TELEMETRY_DIR="${TELEMETRY_DIR:-$SCRIPT_DIR/../telemetry}"
+
+# Source config.sh FIRST (best-effort, like economics-record.sh) so the conf resolves enablement
+# (FLOW_AGENTS_CONSOLE_LIVENESS_RELAY) and the endpoint/token/tenant — trust-gated for default-path
+# confs. This is what makes conf-only operation work with NO env var set.
+# shellcheck source=/dev/null
+[[ -f "$TELEMETRY_DIR/lib/config.sh" ]] && source "$TELEMETRY_DIR/lib/config.sh" 2>/dev/null || true
+
+# Opt-in gate — off by default, now honoring the conf-derived value config.sh just resolved.
+case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
+  1 | true | TRUE | yes | on) ;;
+  *) exit 0 ;;
+esac
+
 [[ -f "$TELEMETRY_DIR/lib/transport.sh" ]] || exit 0
 # shellcheck source=/dev/null
 source "$TELEMETRY_DIR/lib/transport.sh" 2>/dev/null || exit 0
@@ -73,7 +83,9 @@ record="$(printf '%s' "$event_json" | jq -c '{
   ttlSeconds: (.ttlSeconds // null),
   host: (.host // null),
   branch: (.branch // null),
-  artifact_dir: (.artifact_dir // .artifactDir // null)
+  artifact_dir: (.artifact_dir // .artifactDir // null),
+  source: (.source // null),
+  activity: (.activity // null)
 }' 2>/dev/null)" || exit 0
 [[ -z "$record" || "$record" == "null" ]] && exit 0
 

package/scripts/telemetry/lib/config.sh

@@ -109,6 +109,13 @@ FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_ECONOMICS_ENDP
 # Set (non-empty) only when the config file carries an explicit console_economics_relay key —
 # distinguishes "operator said 0/1" from "key absent" for the default-on rule below.
 console_economics_relay_raw=""
+# Liveness relay (#567): same conf-driven, opt-out-not-silent-off shape as economics (#469) so an
+# operator enables the hosted liveness mirror via console_liveness_relay=1 in the conf, NOT an env
+# var/.profile. A caller-pre-set env var is the starting point; the config key overrides it; absent
+# any key the default-on rule below turns it on once a console telemetry sink resolves.
+FLOW_AGENTS_CONSOLE_LIVENESS_RELAY="${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}"
+FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL:-}"
+console_liveness_relay_raw=""
 # Pricing registry source (consumed by lib/pricing.sh). Explicit file/URL win;
 # otherwise lib/pricing.sh uses the bundled pricing.json offline.
 TELEMETRY_PRICING_FILE="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
@@ -164,6 +171,17 @@ if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
           esac
           ;;
         console_economics_endpoint_url) FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="$value" ;;
+        console_liveness_relay)
+          case "$(echo "$value" | tr '[:upper:]' '[:lower:]')" in
+            1|true|yes|on) console_liveness_relay_raw="1" ;;
+            0|false|no|off) console_liveness_relay_raw="0" ;;
+            *)
+              printf 'warning: config.sh: unrecognized console_liveness_relay value %q; treating as off\n' "$value" >&2
+              console_liveness_relay_raw="$value"
+              ;;
+          esac
+          ;;
+        console_liveness_endpoint_url) FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$value" ;;
         console_pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_file) TELEMETRY_PRICING_FILE="$value" ;;
@@ -186,6 +204,17 @@ elif [[ -z "$FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY" \
   FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY=1
 fi
 
+# Liveness relay default-on rule (#567), identical shape to economics above: an explicit
+# console_liveness_relay config key always wins; otherwise, once a console telemetry sink resolves,
+# the relay defaults ON unless a caller already pre-set FLOW_AGENTS_CONSOLE_LIVENESS_RELAY in the
+# environment. relay.sh's own opt-in gate reads this exact variable.
+if [[ -n "$console_liveness_relay_raw" ]]; then
+  FLOW_AGENTS_CONSOLE_LIVENESS_RELAY="$console_liveness_relay_raw"
+elif [[ -z "$FLOW_AGENTS_CONSOLE_LIVENESS_RELAY" \
+      && ( -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_TELEMETRY_ENDPOINT_URL:-}" ) ]]; then
+  FLOW_AGENTS_CONSOLE_LIVENESS_RELAY=1
+fi
+
 # Pricing URL is explicit-only (env or config). Do not derive the console
 # pricing endpoint by default; the bundled registry is the reliable offline floor.
 

package/src/builder-flow-runtime.ts

@@ -710,7 +710,7 @@ async function bundleGateEvidence(
     throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", `is not declared by gate ${String((gate as AnyRecord).id ?? "<unknown>")}`);
   }
   if (String((gate as AnyRecord).id) === "verify-gate" && relevant.some((claim) => claim.claimType === "builder.verify.tests" && claim.value === "pass")) {
-    await assertVerifiedTestsTrust(bundle.claims, projectRoot);
+    await assertVerifiedTestsTrust(relevant, projectRoot);
   }
   return { failed, routeReason, expectationIds, visitEnteredAt: enteredAt };
 }
@@ -739,15 +739,20 @@ function timestampAtOrAfter(value: unknown, boundary: number): boolean {
   return parsed !== null && parsed >= boundary;
 }
 
-async function assertVerifiedTestsTrust(claims: unknown[], projectRoot: string): Promise<void> {
-  const testClaims = claims.filter((claim): claim is AnyRecord => isRecord(claim)
+async function assertVerifiedTestsTrust(currentGateClaims: AnyRecord[], projectRoot: string): Promise<void> {
+  const testClaims = currentGateClaims.filter((claim): claim is AnyRecord => isRecord(claim)
     && claim.claimType === "builder.verify.tests"
     && claim.value === "pass"
     && isRecord(claim.metadata)
     && isRecord(claim.metadata.gate_claim)
     && claim.metadata.gate_claim.expectation_id === "tests-evidence");
   if (testClaims.length === 0) throw new BuilderBuildRunInputError("evidence.tests", "is missing a passing tests-evidence claim");
-  const liveCritiques = claims.filter((claim): claim is AnyRecord => isRecord(claim)
+  // A route-back starts a new gate visit and therefore a new critique generation. Historical
+  // reviewer slices remain in the bundle and manifest for audit, but only critiques acquired
+  // during this visit describe the implementation snapshot currently being verified. Within a
+  // visit every live reviewer slice still participates, so changing reviewers cannot bury a
+  // disputed finding.
+  const liveCritiques = currentGateClaims.filter((claim): claim is AnyRecord => isRecord(claim)
     && isRecord(claim.metadata)
     && claim.metadata.origin === "critique"
     && typeof claim.metadata.superseded_by !== "string");
@@ -763,7 +768,7 @@ async function assertVerifiedTestsTrust(claims: unknown[], projectRoot: string):
     await Promise.all(artifacts.map((artifact) => assertReviewedArtifactDigest(artifact, projectRoot)));
     assertReviewedWorkspaceSnapshot(claim, artifacts, projectRoot);
   }));
-  const criteria = claims.filter((claim): claim is AnyRecord => isRecord(claim) && isRecord(claim.metadata) && claim.metadata.origin === "acceptance");
+  const criteria = currentGateClaims.filter((claim): claim is AnyRecord => isRecord(claim) && isRecord(claim.metadata) && claim.metadata.origin === "acceptance");
   if (criteria.length === 0 || criteria.some((claim) => {
     const criterion = isRecord(claim.metadata.criterion) ? claim.metadata.criterion : null;
     return claim.value !== "pass" || !criterion || !Array.isArray(criterion.evidence_refs) || criterion.evidence_refs.length === 0;

package/src/cli/builder-flow-runtime.test.mjs

@@ -1382,6 +1382,8 @@ test("failed verification projects Flow-owned route-back attempt and budget", as
   assert.equal(verify.run.state.current_step, "verify");
 
   const failureTimestamp = new Date().toISOString();
+  const initialPrerequisites = verifiedTestsPrerequisites(session, failureTimestamp);
+  initialPrerequisites[0].claim.metadata.reviewer = "reviewer-before-route-back";
   const routed = await writeAndSync(session, [bundleClaim({
     expectation: "tests-evidence",
     claimType: "builder.verify.tests",
@@ -1389,7 +1391,7 @@ test("failed verification projects Flow-owned route-back attempt and budget", as
     status: "fail",
     routeReason: "implementation_defect",
     timestamp: failureTimestamp,
-  }), ...verifiedTestsPrerequisites(session, failureTimestamp)]);
+  }), ...initialPrerequisites]);
 
   assert.equal(routed.run.state.current_step, "execute");
   assert.equal(routed.projection.flow_run.route_back_attempt, 1);
@@ -1415,15 +1417,66 @@ test("failed verification projects Flow-owned route-back attempt and budget", as
   assert.equal(staleRetry.attached, false);
   assert.equal(staleRetry.run.state.current_step, "verify");
   assert.equal(staleRetry.run.state.transitions.filter((transition) => transition.type === "route_back").length, 1);
+  fs.writeFileSync(path.join(session.projectRoot, "review-target", "delivery.md"), "corrected delivery after route-back\n");
   const correctedAt = new Date(Date.parse(reentered.run.state.transitions.at(-1).at) + 1).toISOString();
+  const correctedPrerequisites = verifiedTestsPrerequisites(session, correctedAt)
+    .map((entry, index) => withIdentitySuffix(entry, `corrected-${index}`));
+  correctedPrerequisites[0].claim.metadata.reviewer = "reviewer-after-route-back";
   const corrected = await writeAndSync(session, [
     withIdentitySuffix(bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step", timestamp: correctedAt }), "corrected"),
-    ...verifiedTestsPrerequisites(session, correctedAt).map((entry, index) => withIdentitySuffix(entry, `corrected-${index}`)),
+    ...correctedPrerequisites,
+    // Compose-safe writers preserve this older reviewer's still-live PASS slice. It targets the
+    // prior implementation bytes and must remain audit history without deadlocking the new gate
+    // visit or requiring the new reviewer to impersonate the old one.
+    initialPrerequisites[0],
   ]);
   assert.equal(corrected.run.state.current_step, "merge-ready");
   const verifyEvidence = corrected.run.manifest.evidence.filter((entry) => entry.gate_id === "verify-gate");
   assert.equal(verifyEvidence.length, 2);
   assert.equal(verifyEvidence[0].superseded_by, verifyEvidence[1].id);
+  const retainedCritiques = readJson(path.join(session.sessionDir, "trust.bundle")).claims
+    .filter((claim) => claim.metadata?.origin === "critique" && !claim.metadata.superseded_by);
+  assert.deepEqual(retainedCritiques.map((claim) => claim.metadata.reviewer).sort(), [
+    "reviewer-after-route-back",
+    "reviewer-before-route-back",
+  ]);
+});
+
+test("a different passing reviewer cannot hide a disputed critique in the same gate visit", async () => {
+  const session = makeSession("same-visit-reviewer-handoff");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  await writeAndSync(session, [bundleClaim({ expectation: "selected-work", claimType: "builder.pull-work.selected", subjectType: "work-item" })]);
+  await writeAndSync(session, [
+    bundleClaim({ expectation: "pickup-probe-readiness", claimType: "builder.design-probe.pickup-readiness", subjectType: "work-item" }),
+    bundleClaim({ expectation: "probe-decisions-or-accepted-gaps", claimType: "builder.design-probe.decisions", subjectType: "decision" }),
+  ]);
+  await writeAndSync(session, [bundleClaim({ expectation: "implementation-plan", claimType: "builder.plan.implementation", subjectType: "artifact" })]);
+  await writeAndSync(session, [bundleClaim({ expectation: "implementation-scope", claimType: "builder.execute.scope", subjectType: "change" })]);
+
+  const timestamp = new Date().toISOString();
+  const prerequisites = verifiedTestsPrerequisites(session, timestamp);
+  prerequisites[0].claim.metadata.reviewer = "passing-reviewer";
+  const disputedCritique = withIdentitySuffix(structuredClone(prerequisites[0]), "disputed-reviewer");
+  disputedCritique.claim.value = "fail";
+  disputedCritique.claim.status = "disputed";
+  disputedCritique.claim.metadata.reviewer = "disputed-reviewer";
+  disputedCritique.claim.metadata.lanes = [{ id: "code", status: "fail" }];
+  disputedCritique.claim.metadata.findings = [{ id: "unresolved", status: "open", severity: "high" }];
+  disputedCritique.event.status = "disputed";
+
+  const blocked = await writeAndSync(session, [
+    bundleClaim({ expectation: "tests-evidence", claimType: "builder.verify.tests", subjectType: "flow-step", timestamp }),
+    ...prerequisites,
+    disputedCritique,
+  ]);
+  assert.equal(blocked.attached, false);
+  assert.equal(blocked.run.state.current_step, "verify");
+  const retainedCritiques = readJson(path.join(session.sessionDir, "trust.bundle")).claims
+    .filter((claim) => claim.metadata?.origin === "critique" && !claim.metadata.superseded_by);
+  assert.deepEqual(retainedCritiques.map((claim) => [claim.metadata.reviewer, claim.value]).sort(), [
+    ["disputed-reviewer", "fail"],
+    ["passing-reviewer", "pass"],
+  ]);
 });
 
 test("producer-superseded FAIL is audit history and live PASS drives verify", async () => {

package/src/cli/codex-exit-code.test.mjs

@@ -55,6 +55,22 @@ function functionCall(callId, command) {
   };
 }
 
+function execCommandCall(callId, cmd) {
+  return {
+    timestamp: "2026-07-06T00:00:00Z",
+    type: "response_item",
+    payload: { type: "function_call", call_id: callId, name: "exec_command", arguments: JSON.stringify({ cmd }) },
+  };
+}
+
+function functionToolCall(callId, name, args) {
+  return {
+    timestamp: "2026-07-06T00:00:00Z",
+    type: "response_item",
+    payload: { type: "function_call", call_id: callId, name, arguments: JSON.stringify(args) },
+  };
+}
+
 // --- extractExitCodeFromBanner: preamble-anchored (CRITICAL finding #1) ---
 
 test("extractExitCodeFromBanner: forgery in post-Output: stdout is ignored (preamble wins)", () => {
@@ -95,7 +111,7 @@ test("readExitCodeFromRollout: malformed JSONL lines are skipped, valid entry st
 
 // --- truncation arithmetic (HEAD-anchored bounded scan, MEDIUM finding #5) ---
 
-test("readExitCodeFromRollout: target line near EOF still found when file exceeds the scan window", () => {
+test("readExitCodeFromRollout: call-id target near EOF is found when file exceeds the scan window", () => {
   const filler = [];
   for (let i = 0; i < 60; i++) filler.push({ timestamp: "2026-07-06T00:00:00Z", type: "turn_context", payload: {} });
   const target = functionCallOutput("call_1", "Process exited with code 1\nOutput:\n...");
@@ -106,7 +122,7 @@ test("readExitCodeFromRollout: target line near EOF still found when file exceed
   // Window smaller than the whole file (forces truncation) but comfortably
   // larger than the target line itself.
   const maxScanBytes = targetLineBytes + 50;
-  assert.equal(readExitCodeFromRollout(file, { maxScanBytes }), 1);
+  assert.equal(readExitCodeFromRollout(file, { callId: "call_1", maxScanBytes }), 1);
 });
 
 test("readExitCodeFromRollout: target line start beyond maxScanBytes yields null (never mis-reads a fragment)", () => {
@@ -130,6 +146,15 @@ test("readExitCodeFromRollout: call_id match wins over the newer entry", () => {
   assert.equal(readExitCodeFromRollout(file, { callId: "call_b" }), 5);
 });
 
+test("readExitCodeFromRollout: an unresolved explicit call_id never downgrades to command matching", () => {
+  const file = writeRollout([
+    execCommandCall("call_other", "npm test"),
+    functionCallOutput("call_other", "Process exited with code 0\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { callId: "call_missing", command: "npm test" }), null);
+});
+
 // --- command cross-check correlation (Decision B #2, HIGH finding #4) ---
 
 test("readExitCodeFromRollout: command cross-check mismatch declines to null", () => {
@@ -148,6 +173,196 @@ test("readExitCodeFromRollout: command cross-check match uses the correlated ent
   assert.equal(readExitCodeFromRollout(file, { command: "npm run lint" }), 1);
 });
 
+test("readExitCodeFromRollout: Codex exec_command cmd argument correlates the result", () => {
+  const file = writeRollout([
+    execCommandCall("call_1", "npm run lint"),
+    functionCallOutput("call_1", "Process exited with code 1\nOutput:\n..."),
+  ]);
+  assert.equal(readExitCodeFromRollout(file, { command: "npm run lint" }), 1);
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+});
+
+test("readExitCodeFromRollout: parallel call cannot inherit the previous call result", () => {
+  const file = writeRollout([
+    execCommandCall("call_pass", "find seed -type f"),
+    execCommandCall("call_fail", "cat seed/src/window.js"),
+    functionCallOutput("call_pass", "Process exited with code 0\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "find seed -type f" }), 0);
+  assert.equal(readExitCodeFromRollout(file, { command: "cat seed/src/window.js" }), null);
+});
+
+test("readExitCodeFromRollout: parallel outputs correlate to their exact commands", () => {
+  const file = writeRollout([
+    execCommandCall("call_pass", "find seed -type f"),
+    execCommandCall("call_fail", "cat seed/src/window.js"),
+    functionCallOutput("call_pass", "Process exited with code 0\nOutput:\n..."),
+    functionCallOutput("call_fail", "Process exited with code 1\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "find seed -type f" }), 0);
+  assert.equal(readExitCodeFromRollout(file, { command: "cat seed/src/window.js" }), 1);
+});
+
+test("readExitCodeFromRollout: repeated parallel command text is ambiguous without call_id", () => {
+  const file = writeRollout([
+    execCommandCall("call_a", "npm test"),
+    execCommandCall("call_b", "npm test"),
+    functionCallOutput("call_a", "Process exited with code 0\nOutput:\n..."),
+    functionCallOutput("call_b", "Process exited with code 1\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+  assert.equal(readExitCodeFromRollout(file, { callId: "call_a", command: "npm test" }), 0);
+  assert.equal(readExitCodeFromRollout(file, { callId: "call_b", command: "npm test" }), 1);
+});
+
+test("readExitCodeFromRollout: a repeated call without its output cannot reuse an older result", () => {
+  const file = writeRollout([
+    execCommandCall("call_old", "npm test"),
+    functionCallOutput("call_old", "Process exited with code 0\nOutput:\n..."),
+    execCommandCall("call_current", "npm test"),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+});
+
+test("readExitCodeFromRollout: unresolved multi-call tail never falls back to newest output", () => {
+  const file = writeRollout([
+    {
+      timestamp: "2026-07-06T00:00:00Z",
+      type: "response_item",
+      payload: { type: "function_call", call_id: "call_a", name: "unknown", arguments: "not-json" },
+    },
+    functionCallOutput("call_a", "Process exited with code 0\nOutput:\n..."),
+    functionCallOutput("call_b", "Process exited with code 1\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+  assert.equal(readExitCodeFromRollout(file, {}), null);
+});
+
+test("readExitCodeFromRollout: malformed function call cannot make an output look unpaired", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "codex-exit-code-"));
+  const file = path.join(dir, "rollout.jsonl");
+  const output = JSON.stringify(functionCallOutput("call_old", "Process exited with code 0\nOutput:\n..."));
+  fs.writeFileSync(file, `${output}\n{"payload":{"type":"function_call","call_id":"call_current"\n`);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+});
+
+test("readExitCodeFromRollout: truncated call context cannot make an output look unpaired", () => {
+  const output = functionCallOutput("call_old", "Process exited with code 7\nOutput:\n...");
+  const file = writeRollout([functionCall("call_old", "npm run lint"), output]);
+  const outputLineBytes = Buffer.byteLength(JSON.stringify(output), "utf8") + 1;
+
+  assert.equal(readExitCodeFromRollout(file, {
+    command: "npm test",
+    maxScanBytes: outputLineBytes + 10,
+  }), null);
+});
+
+test("readExitCodeFromRollout: reused call IDs are ambiguous", () => {
+  const file = writeRollout([
+    execCommandCall("same", "npm test"),
+    execCommandCall("same", "npm run lint"),
+    functionCallOutput("same", "Process exited with code 9\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+  assert.equal(readExitCodeFromRollout(file, { command: "npm run lint" }), null);
+});
+
+test("readExitCodeFromRollout: an unresolvable current call blocks historical command reuse", () => {
+  const file = writeRollout([
+    execCommandCall("call_old", "npm test"),
+    functionCallOutput("call_old", "Process exited with code 0\nOutput:\n..."),
+    {
+      timestamp: "2026-07-06T00:00:01Z",
+      type: "response_item",
+      payload: { type: "function_call", call_id: "call_current", name: "exec_command", arguments: "not-json" },
+    },
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+});
+
+test("readExitCodeFromRollout: malformed duplicate call IDs remain ambiguous", () => {
+  const file = writeRollout([
+    execCommandCall("same", "npm test"),
+    {
+      timestamp: "2026-07-06T00:00:01Z",
+      type: "response_item",
+      payload: { type: "function_call", call_id: "same", name: "exec_command", arguments: "not-json" },
+    },
+    functionCallOutput("same", "Process exited with code 9\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { callId: "same", command: "npm test" }), null);
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+});
+
+test("readExitCodeFromRollout: malformed JSON blocks historical and explicit-id correlation", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "codex-exit-code-"));
+  const file = path.join(dir, "rollout.jsonl");
+  const call = JSON.stringify(execCommandCall("same", "npm test"));
+  const output = JSON.stringify(functionCallOutput("same", "Process exited with code 0\nOutput:\n..."));
+  fs.writeFileSync(file, `${call}\n${output}\n{"payload":{"type":"function_call","call_id":"same"\n`);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+  assert.equal(readExitCodeFromRollout(file, { callId: "same", command: "npm test" }), null);
+});
+
+test("readExitCodeFromRollout: a partial function-call token blocks historical correlation", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "codex-exit-code-"));
+  const file = path.join(dir, "rollout.jsonl");
+  const call = JSON.stringify(execCommandCall("old", "npm test"));
+  const output = JSON.stringify(functionCallOutput("old", "Process exited with code 0\nOutput:\n..."));
+  fs.writeFileSync(file, `${call}\n${output}\n{"payload":{"type":"function_cal\n`);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+});
+
+test("readExitCodeFromRollout: unrelated function tools do not poison exact command correlation", () => {
+  const file = writeRollout([
+    functionToolCall("patch_call", "apply_patch", { patch: "*** Begin Patch" }),
+    execCommandCall("command_call", "npm test"),
+    functionCallOutput("command_call", "Process exited with code 0\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), 0);
+});
+
+test("readExitCodeFromRollout: nameless command-shaped calls participate in ambiguity checks", () => {
+  const file = writeRollout([
+    execCommandCall("old", "npm test"),
+    functionCallOutput("old", "Process exited with code 0\nOutput:\n..."),
+    functionToolCall("current", null, { cmd: "npm test" }),
+    functionCallOutput("current", "Process exited with code 1\nOutput:\n..."),
+  ]);
+
+  assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+  assert.equal(readExitCodeFromRollout(file, { callId: "current", command: "npm test" }), 1);
+});
+
+test("readExitCodeFromRollout: semantically nameless malformed calls block historical command reuse", () => {
+  for (const name of [null, "", "   "]) {
+    const file = writeRollout([
+      execCommandCall("old", "npm test"),
+      functionCallOutput("old", "Process exited with code 0\nOutput:\n..."),
+      {
+        timestamp: "2026-07-06T00:00:01Z",
+        type: "response_item",
+        payload: { type: "function_call", call_id: "current", name, arguments: "not-json" },
+      },
+      functionCallOutput("current", "Process exited with code 1\nOutput:\n..."),
+    ]);
+
+    assert.equal(readExitCodeFromRollout(file, { command: "npm test" }), null);
+  }
+});
+
 test("readExitCodeFromRollout: no resolvable pairing falls back to the newest banner (single-call case)", () => {
   const file = writeRollout([
     functionCallOutput("call_1", "Process exited with code 1\nOutput:\n..."),