@kontourai/flow-agents 3.2.0 → 3.4.0

package/scripts/hooks/evidence-capture.js

@@ -12,7 +12,12 @@
  * Records to `.kontourai/flow-agents/<slug>/command-log.jsonl`, one JSON object per line:
  *   {
  *     "command":        "<the command string the agent ran>",
- *     "observedResult": "pass" | "fail",   // deterministically inferred
+ *     "observedResult": "pass" | "fail" | "ambiguous", // deterministically inferred
+ *                                       // ("ambiguous": a bare, non-self-asserting
+ *                                       // grep/diff exited 1 — could mean zero
+ *                                       // matches/no differences (PASS for an
+ *                                       // absence check) or an unintended miss
+ *                                       // (FAIL for a presence check); #362)
  *     "exitCode":       <integer> | null,  // null when only pass/fail is inferable
  *     "capturedAt":     "<ISO-8601 timestamp>",
  *     "source":         "postToolUse-capture",
@@ -38,7 +43,10 @@
  * (per docs/spec/runtime-hook-surface.md §1, postToolUse). A clean integer exit
  * code is host-dependent. We extract the real exit code where present; otherwise
  * we derive `observedResult` from `error`/stderr-style failure indication and
- * record `exitCode: null`. We never record the model's words about the outcome.
+ * record `exitCode: null`. Absent positive success evidence (a clean integer
+ * exit code of 0; no host currently surfaces a positive success flag), the
+ * result is 'ambiguous', never 'pass'. We never record the model's words about
+ * the outcome.
  *
  * Non-blocking — always exits 0. Idempotent/append-only. Fail-open on any error:
  * a capture failure must never block the agent or corrupt the log.
@@ -51,6 +59,7 @@ const path = require('path');
 const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
 const { resolveActor } = require('./lib/actor-identity.js');
 const { readCurrentPointer } = require('./lib/current-pointer.js');
+const { isAmbiguousAbsenceCommand } = require('./lib/runnable-command.js');
 const crypto = require('crypto');
 
 const MAX_STDIN = 1024 * 1024;
@@ -248,15 +257,32 @@ function cleanExitCode(value) {
  *
  * Priority:
  *   1. A clean integer exit code anywhere the host surfaces it → exitCode set;
- *      observedResult = pass iff exitCode === 0.
+ *      observedResult = pass iff exitCode === 0, EXCEPT (#362) a bare,
+ *      non-self-asserting `grep`/`diff` invocation (per
+ *      `isAmbiguousAbsenceCommand`, ./lib/runnable-command.js) that exits
+ *      EXACTLY 1 → observedResult = 'ambiguous' instead of 'fail'. Exit 1 for
+ *      such a command could mean zero matches/no differences (PASS for an
+ *      absence check) or an unintended miss (FAIL for a presence check) —
+ *      this is never coerced to 'pass' (that would trade a false-block for a
+ *      false-pass) nor silently left as 'fail' (that is the exact false
+ *      caught-completion #362 reports). Exit codes >= 2 for these two
+ *      binaries are real tool errors and remain 'fail', unchanged.
  *   2. Else, a non-empty `error` field or stderr-style failure indication →
  *      observedResult = fail, exitCode = null.
- *   3. Else → observedResult = pass, exitCode = null.
+ *   3. Else → observedResult = ambiguous, exitCode = null. Absent positive
+ *      success evidence (a clean integer exit code of 0; no host currently
+ *      surfaces a positive success flag), the result is 'ambiguous', never
+ *      'pass'.
+ *
+ * `input.command` (the raw command string, already in scope at the run()
+ * call site) is required to evaluate the #362 carve-out; when absent, the
+ * carve-out simply never fires and behavior is byte-identical to before #362.
  */
 function observeResult(input) {
   const response = input.tool_response;
   const output = input.tool_output;
   const error = input.error;
+  const command = typeof input.command === 'string' ? input.command : '';
 
   // Candidate locations for a host-provided exit code.
   const candidates = [];
@@ -274,6 +300,9 @@ function observeResult(input) {
   }
 
   if (exitCode !== null) {
+    if (exitCode === 1 && command && isAmbiguousAbsenceCommand(command)) {
+      return { exitCode, observedResult: 'ambiguous' };
+    }
     return { exitCode, observedResult: exitCode === 0 ? 'pass' : 'fail' };
   }
 
@@ -281,7 +310,7 @@ function observeResult(input) {
   if (isFailureIndicated(error, response, output)) {
     return { exitCode: null, observedResult: 'fail' };
   }
-  return { exitCode: null, observedResult: 'pass' };
+  return { exitCode: null, observedResult: 'ambiguous' };
 }
 
 // True when the host surfaces a deterministic failure signal: a non-empty
@@ -326,6 +355,10 @@ function run(rawInput) {
       exit_code: input.exit_code,
       status: input.status,
       code: input.code,
+      // #362: thread the raw command string through so observeResult can apply the
+      // bare-grep/diff-exit-1 ambiguous carve-out. `command` is already in scope here
+      // (extracted above from input.tool_input.command).
+      command,
     });
 
     const record = {

package/scripts/hooks/lib/actor-identity.js

@@ -229,6 +229,75 @@ function sanitizeSegment(value) {
   return cleaned || 'unknown';
 }
 
+/**
+ * #398: detect a CI-triggered session and derive a STABLE actor identity from the CI provider's
+ * published identifiers. The right granularity is the JOB/RUN (a CI job ≈ one agent session), NOT
+ * the runner machine (hostname can be shared/reused across jobs). Detection is order-independent
+ * (each provider gates on its own canonical marker env var). Returns `{ runtime, session_id }` on a
+ * recognized provider WITH a non-blank stable id, else `null` (caller falls through to
+ * process-ancestry, where #293's advisory verify-hold net still protects).
+ *
+ * Deliberately conservative: a generic/unrecognized `CI=true` returns null rather than fabricating
+ * a "stable" id from something that might shift between subprocesses — a wrong stable classification
+ * would let the #293 hard gate ENFORCE against a shifting identity, which is worse than advisory.
+ * All segments are sanitized by serializeActor at the call site (allowed charset, length-capped),
+ * so a hostile env var value cannot inject.
+ *
+ * ACCEPTED GRANULARITY GAP (matrix / parallelism): the id is job/run-granular. GitLab (`CI_JOB_ID`),
+ * Azure (`SYSTEM_JOBID`), and Buildkite (`BUILDKITE_JOB_ID`) expose a per-job-INSTANCE id that is
+ * already unique across matrix/parallel legs. CircleCI parallelism is disambiguated below via
+ * `CIRCLE_NODE_INDEX`. But GitHub Actions and Jenkins declarative-`matrix{}` cells share
+ * `GITHUB_JOB` / `BUILD_TAG` across all legs of one run+attempt — matrix values live only in the
+ * `${{ matrix }}` / axis context, not in any env var this can read — so two concurrent legs collapse
+ * to the SAME CI actor. This degrades SAFELY: worst case is idempotent self-recognition (one leg
+ * treats another's claim as its own); it never false-blocks and never injects. The coordination-
+ * relevant CI jobs (trust-reconcile / publish) run as single, non-matrix jobs today. Filed as a
+ * fast-follow to add a GitHub-matrix disambiguator if a coordination path ever runs under a matrix.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{runtime: string, session_id: string} | null}
+ */
+function detectCiActor(env = process.env) {
+  env = env || {};
+  const s = (v) => String(v == null ? '' : v).trim();
+  const compose = (...parts) => parts.map(s).filter(Boolean).join('-');
+
+  // GitHub Actions — run id + attempt + job is unique and stable across the whole job.
+  if (s(env.GITHUB_ACTIONS) === 'true') {
+    const id = compose(env.GITHUB_RUN_ID, env.GITHUB_RUN_ATTEMPT, env.GITHUB_JOB);
+    return id ? { runtime: 'github-actions', session_id: id } : null;
+  }
+  // GitLab CI — CI_JOB_ID is stable per job.
+  if (s(env.GITLAB_CI) === 'true') {
+    const id = s(env.CI_JOB_ID);
+    return id ? { runtime: 'gitlab-ci', session_id: id } : null;
+  }
+  // CircleCI — workflow id + job name + node index (CIRCLE_NODE_INDEX disambiguates the containers
+  // of a `parallelism: N` job; "0" for a single-container job, so it is always present and stable).
+  if (s(env.CIRCLECI) === 'true') {
+    const id = compose(env.CIRCLE_WORKFLOW_ID, env.CIRCLE_JOB, env.CIRCLE_NODE_INDEX) || s(env.CIRCLE_BUILD_NUM);
+    return id ? { runtime: 'circleci', session_id: id } : null;
+  }
+  // Jenkins — BUILD_TAG is the stable per-build identifier; fall back to job + build id.
+  if (s(env.JENKINS_URL)) {
+    const id = s(env.BUILD_TAG) || compose(env.JOB_NAME, env.BUILD_ID);
+    return id ? { runtime: 'jenkins', session_id: id } : null;
+  }
+  // Azure Pipelines — build id + system job id (SYSTEM_JOBID is a per-job-instance GUID, unique
+  // across matrix/strategy legs).
+  if (s(env.TF_BUILD) === 'true') {
+    const id = compose(env.BUILD_BUILDID, env.SYSTEM_JOBID);
+    return id ? { runtime: 'azure-pipelines', session_id: id } : null;
+  }
+  // Buildkite — job id is a stable UUID per job.
+  if (s(env.BUILDKITE) === 'true') {
+    const id = s(env.BUILDKITE_JOB_ID);
+    return id ? { runtime: 'buildkite', session_id: id } : null;
+  }
+  // Generic/unrecognized CI: do NOT fabricate stability — fall through to process-ancestry.
+  return null;
+}
+
 /**
  * Serialize a runtime-agnostic actor struct into a single string safe for
  * the existing `${subjectId}::${actor}` grouping key: each field is passed
@@ -334,6 +403,18 @@ function resolveActor(env = process.env) {
     return { actor, source: `runtime-session-id:${runtime}` };
   }
 
+  // #398: CI-runtime tier — sits ABOVE process-ancestry (stable across every subprocess in a CI
+  // job) and BELOW an explicit override / native runtime session id (those are more specific and
+  // already returned above). A CI-triggered agent session otherwise falls to process-ancestry,
+  // whose seed differs across subprocesses within one job (a subject claimed in `ensure-session`
+  // isn't recognized as self at `publish`) — the exact instability #293 had to degrade the
+  // verify-hold gate to advisory for. A stable CI identity lets that gate ENFORCE instead.
+  const ci = detectCiActor(env);
+  if (ci && ci.session_id) {
+    const actor = serializeActor({ runtime: ci.runtime, session_id: ci.session_id, host: os.hostname() });
+    return { actor, source: `ci-runtime:${ci.runtime}` };
+  }
+
   const seed = ancestorActorSeed();
   if (seed) {
     const actor = serializeActor({ runtime, session_id: `anc-${seed}`, host: os.hostname() });
@@ -360,6 +441,7 @@ function isUnresolvedActor(actor) {
 module.exports = {
   detectRuntime,
   runtimeSessionId,
+  detectCiActor,
   ancestorActorSeed,
   sanitizeSegment,
   serializeActor,

package/scripts/hooks/lib/codex-exit-code.js

@@ -0,0 +1,316 @@
+'use strict';
+/**
+ * codex-exit-code.js — codex-only host-banner exit-code extraction (#470).
+ *
+ * The codex PostToolUse payload carries no structured exit code (no
+ * `tool_response.exitCode`/`exit_code`, no `error`, no `stderr`). The only
+ * deterministic host signal is a fixed-format banner the codex CLI itself
+ * writes into the session rollout's `function_call_output`:
+ *
+ *   Process exited with code N
+ *
+ * This is HOST-authored prose (observed on codex-cli 0.142.5), not model
+ * narration — regex-matching exactly this banner is a deterministic host
+ * signal, distinct from scanning stdout/narration for "error"/"fail" words
+ * (which docs/spec/runtime-hook-surface.md §2.5 forbids and this module does
+ * not do).
+ *
+ * SECURITY (iteration 2 / #470 review). The banner lives in the HOST-authored
+ * PREAMBLE of a `function_call_output.output` string, BEFORE the model's own
+ * stdout, which is appended after a literal `Output:` delimiter:
+ *
+ *   Process exited with code 1
+ *   Original token count: 25
+ *   Output:
+ *   <arbitrary model-produced stdout, which may itself contain the string
+ *    "Process exited with code 0" — this is NOT a host signal and must never
+ *    be matched>
+ *
+ * Both exports are therefore PREAMBLE-ANCHORED: extraction only ever looks
+ * BEFORE the first `Output:` delimiter and takes the FIRST banner match there
+ * (the host writes it once). The post-delimiter model stdout is never
+ * scanned, at any size — this is what makes the extraction fail-safe against
+ * a command that deliberately prints a forged banner to stdout.
+ *
+ * Both exports are pure/fail-open: malformed input, a missing/unreadable file,
+ * an oversized/inaccessible rollout, or an ambiguous cross-call correlation
+ * all degrade to `null` ("no signal"), never a throw. Callers must treat
+ * `null` as "extraction unavailable", not as exit code 0.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// The two forms the `Output:` delimiter can take depending on how far the
+// caller has decoded the surrounding JSON:
+//   - a JSON.parse'd `output` string carries the delimiter as a REAL newline
+//     pair: "...\nOutput:\n...".
+//   - a raw (still JSON-escaped) slice of the rollout file — used only by the
+//     head-only fallback below, when a line is too large to fully parse —
+//     carries it literally escaped: "...\\nOutput:\\n...".
+// extractExitCodeFromBanner accepts either input flavor and anchors on
+// whichever form is present (real callers only ever hand it one flavor at a
+// time; this is not an ambiguity, just support for both call sites).
+const ANCHOR_REAL = '\nOutput:\n';
+const ANCHOR_ESCAPED = '\\nOutput:\\n';
+
+const BANNER_RE = /Process exited with code (\d+)/;
+
+function splitPreamble(text) {
+  const iReal = text.indexOf(ANCHOR_REAL);
+  const iEsc = text.indexOf(ANCHOR_ESCAPED);
+  let idx = -1;
+  if (iReal !== -1 && iEsc !== -1) idx = Math.min(iReal, iEsc);
+  else if (iReal !== -1) idx = iReal;
+  else if (iEsc !== -1) idx = iEsc;
+  // No anchor found at all: fall back to treating the whole text as the
+  // preamble (documented residual — the observed codex format always
+  // includes the `Output:` delimiter; see docs/spec + plan risk log).
+  return idx === -1 ? text : text.slice(0, idx);
+}
+
+/**
+ * extractExitCodeFromBanner(text) → integer | null
+ *
+ * Pure regex extraction — no I/O, cannot throw on well-formed string input.
+ * PREAMBLE-ANCHORED (#470 iteration 2, CRITICAL finding #1): splits `text` on
+ * the FIRST `Output:` delimiter (real or JSON-escaped form) and matches the
+ * banner ONLY in the portion before it, returning the FIRST match. The
+ * model's stdout after the delimiter is never scanned, so a command that
+ * prints a forged `Process exited with code 0` to its own stdout cannot
+ * override the real host-reported code in the preamble.
+ */
+function extractExitCodeFromBanner(text) {
+  if (typeof text !== 'string' || !text) return null;
+  const preamble = splitPreamble(text);
+  const match = BANNER_RE.exec(preamble);
+  if (!match) return null;
+  const n = Number(match[1]);
+  return Number.isInteger(n) ? n : null;
+}
+
+function normalizeCommandText(value) {
+  if (typeof value === 'string') return value.trim() || null;
+  if (Array.isArray(value)) {
+    const joined = value.map(v => String(v)).join(' ').trim();
+    return joined || null;
+  }
+  return null;
+}
+
+// Best-effort parse of a rollout `function_call`'s `arguments` field into a
+// normalized command string, used only for the command cross-check
+// correlation (Decision B #2). Any shape mismatch degrades to `null`
+// (unresolvable pairing), never a throw.
+function normalizeCallArguments(argumentsField) {
+  let parsed = argumentsField;
+  if (typeof argumentsField === 'string') {
+    try {
+      parsed = JSON.parse(argumentsField);
+    } catch {
+      return null;
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  return normalizeCommandText(parsed.command);
+}
+
+const OUTPUT_FIELD_NEEDLE = '"output":"';
+
+/**
+ * parseCandidateLine(line, maxLineHeadBytes) → candidate | null
+ *
+ * Interprets one JSONL rollout line as either a `function_call_output` or a
+ * `function_call` response_item, HEAD-ANCHORED (#470 iteration 2, MEDIUM
+ * finding #5): a line that fits within `maxLineHeadBytes` is fully
+ * `JSON.parse`d (cheap, and correct for the real-newline anchor form); a line
+ * that exceeds the head window is NEVER fully parsed (that would mean holding
+ * arbitrarily large flooded stdout in memory and risks the preamble/banner —
+ * which lives at the line HEAD — being reasoned about incorrectly). Instead
+ * only the first `maxLineHeadBytes` raw bytes are inspected: the banner and
+ * `Output:` delimiter live within the first few hundred bytes of the `output`
+ * field regardless of how much stdout follows, so the raw head slice is
+ * sufficient for `extractExitCodeFromBanner` (escaped-anchor form).
+ */
+function parseCandidateLine(line, maxLineHeadBytes) {
+  const byteLen = Buffer.byteLength(line, 'utf8');
+  if (byteLen <= maxLineHeadBytes) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      return null; // malformed/partial line — skip, keep scanning
+    }
+    const payload = entry && typeof entry === 'object' ? entry.payload : null;
+    if (!payload || typeof payload !== 'object') return null;
+    const callId = typeof payload.call_id === 'string' ? payload.call_id : null;
+    if (payload.type === 'function_call_output' && typeof payload.output === 'string') {
+      return { type: 'function_call_output', callId, output: payload.output };
+    }
+    if (payload.type === 'function_call') {
+      return { type: 'function_call', callId, command: normalizeCallArguments(payload.arguments) };
+    }
+    return null;
+  }
+
+  // Line exceeds the head window: raw, head-only, best-effort extraction.
+  // `function_call` entries carry only a short command string in practice and
+  // are not expected to exceed the head window; only `function_call_output`
+  // (whose stdout can flood) is handled here.
+  const head = line.slice(0, maxLineHeadBytes);
+  if (head.indexOf('"type":"function_call_output"') === -1) return null;
+  const callIdMatch = /"call_id":"([^"]*)"/.exec(head);
+  const outputIdx = head.indexOf(OUTPUT_FIELD_NEEDLE);
+  if (outputIdx === -1) return null; // output field itself starts beyond the head window
+  const rawOutputHead = head.slice(outputIdx + OUTPUT_FIELD_NEEDLE.length);
+  return {
+    type: 'function_call_output',
+    callId: callIdMatch ? callIdMatch[1] : null,
+    output: rawOutputHead, // still JSON-escaped; extractExitCodeFromBanner handles both anchor forms
+  };
+}
+
+// Best-effort containment (#470 iteration 2, LOW finding #8): realpath the
+// transcript path and require it to be a regular file; when the codex
+// sessions root itself resolves on this host, additionally reject a realpath
+// that escapes it (defends against a symlinked transcript_path pointing
+// somewhere unexpected). Fail-open: any resolution error propagates to the
+// caller's try/catch as "unusable" (null); a non-resolvable sessions root
+// (e.g. custom CODEX_HOME, test fixtures) simply skips the containment check.
+function resolveContainedRealPath(transcriptPath) {
+  const realPath = fs.realpathSync(transcriptPath);
+  const stat = fs.statSync(realPath);
+  if (!stat.isFile()) return null;
+  try {
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    const sessionsRoot = path.join(codexHome, 'sessions');
+    const realRoot = fs.realpathSync(sessionsRoot);
+    const rel = path.relative(realRoot, realPath);
+    if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return null;
+  } catch {
+    // Sessions root doesn't exist/resolve on this host — best-effort only.
+  }
+  return realPath;
+}
+
+/**
+ * readExitCodeFromRollout(transcriptPath, options) → integer | null
+ *
+ * options:
+ *   - maxScanBytes (default 1MB): bounded backward-scan window from EOF used
+ *     to locate candidate `response_item` lines. Beyond this cap, an
+ *     unresolvable line start (and thus that candidate) is dropped — never
+ *     read further back, and never a crash.
+ *   - maxLineHeadBytes (default 64KB): per-line head window; see
+ *     `parseCandidateLine`. This is what makes extraction survive a flooded
+ *     `output` field (#470 iteration 2, MEDIUM finding #5) — the preamble
+ *     banner sits at the line HEAD, so bounding reads to the head can never
+ *     have the banner pushed out of the window by TAIL stdout volume.
+ *   - callId: correlate to a specific `function_call_output.call_id`.
+ *   - command: the claimed command (e.g. `tool_input.command`), used only for
+ *     the command cross-check correlation below.
+ *
+ * Correlation policy (Decision B, #470 iteration 2, HIGH finding #4), in
+ * priority order:
+ *   1. call_id match wins — authoritative.
+ *   2. Absent a call_id match: take the newest `function_call_output` in the
+ *      scanned window, resolve its paired `function_call` (same call_id), and
+ *      compare that call's `arguments` command (normalized) to `command`. A
+ *      resolved MATCH uses the newest output; a resolved MISMATCH DECLINES
+ *      (`null`) rather than knowingly attribute a different call's exit code.
+ *   3. If no pairing is resolvable at all (the common single-call case): fall
+ *      back to the newest `function_call_output` banner.
+ *
+ * Any failure (missing/unreadable/non-regular file, containment violation,
+ * malformed JSON lines, no candidate found) yields `null` — never throws.
+ */
+function readExitCodeFromRollout(transcriptPath, options) {
+  const opts = options || {};
+  const maxScanBytes = Number.isInteger(opts.maxScanBytes) && opts.maxScanBytes > 0
+    ? opts.maxScanBytes
+    : 1024 * 1024;
+  const maxLineHeadBytes = Number.isInteger(opts.maxLineHeadBytes) && opts.maxLineHeadBytes > 0
+    ? opts.maxLineHeadBytes
+    : 64 * 1024;
+  const callId = typeof opts.callId === 'string' && opts.callId ? opts.callId : null;
+  const command = normalizeCommandText(opts.command);
+
+  if (typeof transcriptPath !== 'string' || !transcriptPath) return null;
+
+  let text;
+  let truncated;
+  try {
+    const realPath = resolveContainedRealPath(transcriptPath);
+    if (realPath === null) return null; // containment violation
+
+    const stat = fs.statSync(realPath);
+    const fd = fs.openSync(realPath, 'r');
+    try {
+      const readLen = Math.min(maxScanBytes, stat.size);
+      const start = stat.size - readLen;
+      const buf = Buffer.alloc(readLen);
+      fs.readSync(fd, buf, 0, readLen, start);
+      text = buf.toString('utf8');
+      // A read starting after byte 0 means the file is larger than the scan
+      // window and the first captured line may be a truncated fragment of a
+      // longer line that started before `start` — only then is it dropped.
+      truncated = start > 0;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+
+  let lines;
+  try {
+    lines = text.split('\n');
+  } catch {
+    return null;
+  }
+  if (truncated && lines.length > 1) lines.shift();
+
+  let matchedByCallId = null;
+  let newestOutputEntry = null;
+  let pairedCommand = null;
+
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    const candidate = parseCandidateLine(line, maxLineHeadBytes);
+    if (!candidate) continue; // malformed/partial/unrecognized line — skip, keep scanning
+
+    if (candidate.type === 'function_call_output') {
+      if (newestOutputEntry === null) newestOutputEntry = candidate; // first seen scanning backward = newest
+      if (callId && candidate.callId === callId) {
+        matchedByCallId = candidate;
+        break; // call_id match is authoritative — stop scanning
+      }
+    } else if (candidate.type === 'function_call') {
+      if (newestOutputEntry && pairedCommand === null && candidate.callId === newestOutputEntry.callId) {
+        pairedCommand = candidate.command;
+      }
+    }
+  }
+
+  let chosenOutput = null;
+  if (matchedByCallId) {
+    chosenOutput = matchedByCallId.output;
+  } else if (newestOutputEntry) {
+    if (pairedCommand !== null && command) {
+      if (pairedCommand === command) {
+        chosenOutput = newestOutputEntry.output;
+      } else {
+        return null; // positive command mismatch — decline rather than mis-attribute
+      }
+    } else {
+      chosenOutput = newestOutputEntry.output; // single-call fallback — no pairing resolvable
+    }
+  }
+
+  if (chosenOutput === null) return null;
+  return extractExitCodeFromBanner(chosenOutput);
+}
+
+module.exports = { extractExitCodeFromBanner, readExitCodeFromRollout };