@kontourai/flow-agents 3.3.0 → 3.4.1

package/scripts/ci/trust-reconcile.js

@@ -91,6 +91,25 @@
  *                                         0022 addendum, part 4) — see
  *                                         resolveEnforcementEvent(). Default (unset/
  *                                         unrecognized): treated as a gating event.
+ *   TRUST_RECONCILE_BASE_REF              Optional PR base ref (falls back to
+ *                                         GITHUB_BASE_REF, set by GitHub Actions on
+ *                                         `pull_request` events only) used SOLELY by the
+ *                                         audit-only runtime-session-trailer diagnostic
+ *                                         below to bound its commit-log scan
+ *                                         (`git log <base>..<sha>`); unset/unresolvable →
+ *                                         diagnostic narrows to scanning just the head
+ *                                         commit's own message (documented, accepted
+ *                                         fallback — never a crash, never widens scope).
+ *                                         Never affects Step 1/Step 2/exit-code logic.
+ *
+ * Runtime-session commit-trailer diagnostic (ADR 0022 §1, issue #305 — AUDIT ONLY, never
+ * gating): every run logs a `[trust-reconcile] identified: runtime-session trailer
+ * '<trailer>' on <ref>` line for each distinct `Claude-Session:` / `Codex-Session:` /
+ * `Opencode-Session:` / `Pi-Session:` commit trailer found in the resolved commit range
+ * (see findRuntimeSessionTrailers()/logRuntimeSessionTrailers()). Logs the trailer KEY only
+ * (e.g. `Claude-Session`) — never the trailer VALUE (typically a session URL) — per the
+ * ADR's own quoted line format. This is diagnostic/attribution only: it never writes to
+ * ciResults/issues[] and never changes the exit code, on any path.
  *
  * Auto-discovery (when no --bundle or TRUST_RECONCILE_BUNDLE is set):
  *   Checks delivery/trust.bundle, then delivery/trust.checkpoint.json under repo root
@@ -673,6 +692,111 @@ function isShaInRange(repoRoot, sha, from, to) {
   return isAncestorCommit(repoRoot, from, sha) && isAncestorCommit(repoRoot, sha, to);
 }
 
+/**
+ * Runtime-session commit-trailer names this reconciler recognizes for the audit-only
+ * diagnostic below (ADR 0022 §1, table row 1). These are commit-message TRAILER keys
+ * (e.g. `Claude-Session: https://claude.ai/code/session_...`), a distinct vocabulary from
+ * scripts/hooks/lib/actor-identity.js's RUNTIME_SESSION_ID_VARS (env var names) — but the
+ * same four-runtime enumeration (claude-code/codex/opencode/pi).
+ */
+const RUNTIME_SESSION_TRAILER_NAMES = [
+  'Claude-Session',
+  'Codex-Session',
+  'Opencode-Session',
+  'Pi-Session',
+];
+
+/**
+ * Diagnostic-only (ADR 0022 §1): find runtime-session commit trailers (`Claude-Session:`,
+ * `Codex-Session:`, `Opencode-Session:`, `Pi-Session:`) across the commit range this run is
+ * evaluating, and report which trailer KEYS were found — never the trailer VALUE (typically
+ * a session URL). "Commit trailer present — logged by the reconciler ... for audit; does not
+ * change the exit path" (ADR 0022 §1). This function is write-only diagnostics: its return
+ * value / any failure NEVER feeds ciResults, issues[], or the exit code.
+ *
+ * Range resolution (accepted, documented narrower fallback — ADR 0022 §1 Residuals):
+ *   - Prefer `git log <baseRef>..<sha>` when a PR base ref is resolvable
+ *     (TRUST_RECONCILE_BASE_REF env override, else GITHUB_BASE_REF — set by GitHub Actions
+ *     on `pull_request` events only).
+ *   - No base ref resolvable (local/manual invocation, `push`/`workflow_dispatch` events,
+ *     which have no PR base) — falls back to scanning just `ctx.sha`'s own commit message.
+ *     This is a narrower-than-ideal default (misses trailers on other commits in an
+ *     unresolvable range) but is NEVER a crash and NEVER silently expands scope beyond what
+ *     is actually derivable — documented gap, not a silent limitation.
+ *   - No usable sha at all — zero trailers found (nothing to scan).
+ *
+ * @param {string} repoRoot - Repository root (cwd for git subprocess calls).
+ * @param {{ref: string, sha: string}} ctx - Resolved scope context (resolveScopeContext()).
+ * @returns {Array<{trailerName: string, ref: string}>} Distinct (trailerName) diagnostics
+ *   found in range, each paired with the ref to log against. Empty array on any failure or
+ *   when no trailer is present — never throws.
+ */
+function findRuntimeSessionTrailers(repoRoot, ctx) {
+  const sha = (ctx && ctx.sha) || '';
+  if (!sha) return [];
+  const ref = (ctx && ctx.ref) || sha;
+
+  const baseRef = (process.env.TRUST_RECONCILE_BASE_REF || process.env.GITHUB_BASE_REF || '').trim();
+
+  let commitMessages = [];
+  try {
+    if (baseRef) {
+      const res = spawnSync('git', ['log', '--format=%B%x00', `${baseRef}..${sha}`], {
+        cwd: repoRoot, encoding: 'utf8',
+      });
+      if (res && !res.error && res.status === 0 && typeof res.stdout === 'string') {
+        commitMessages = res.stdout.split('\0').map((m) => m.trim()).filter(Boolean);
+      }
+    }
+    // No base ref resolvable, or the ranged log produced nothing usable — fall back to
+    // just the head commit's own message (accepted narrower default, never a crash).
+    if (!baseRef || commitMessages.length === 0) {
+      const res = spawnSync('git', ['log', '--format=%B', '-1', sha], {
+        cwd: repoRoot, encoding: 'utf8',
+      });
+      if (res && !res.error && res.status === 0 && typeof res.stdout === 'string' && res.stdout.trim()) {
+        commitMessages = [res.stdout.trim()];
+      }
+    }
+  } catch {
+    return [];
+  }
+
+  const found = [];
+  const seen = new Set();
+  for (const message of commitMessages) {
+    for (const trailerName of RUNTIME_SESSION_TRAILER_NAMES) {
+      if (seen.has(trailerName)) continue;
+      const prefix = `${trailerName}:`;
+      const hasTrailer = message.split('\n').some((line) => line.trim().startsWith(prefix));
+      if (hasTrailer) {
+        seen.add(trailerName);
+        found.push({ trailerName, ref });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Diagnostic-only (ADR 0022 §1): write the audit line for each runtime-session commit
+ * trailer found in range. Never touches ciResults/issues[]/exit code — wrapped so any
+ * unexpected failure degrades to zero lines written, never a thrown error.
+ *
+ * @param {string} repoRoot
+ * @param {{ref: string, sha: string}} ctx
+ */
+function logRuntimeSessionTrailers(repoRoot, ctx) {
+  try {
+    const trailers = findRuntimeSessionTrailers(repoRoot, ctx);
+    for (const { trailerName, ref } of trailers) {
+      process.stdout.write(`[trust-reconcile] identified: runtime-session trailer '${trailerName}' on ${ref}\n`);
+    }
+  } catch {
+    // Diagnostic-only — any failure here must never affect the reconciler's outcome.
+  }
+}
+
 /**
  * Match a SINGLE scope condition (one of the four forms) against the resolved context.
  * Extracted from matchesScope() so a compound (space-separated, AND) scope can validate
@@ -910,6 +1034,13 @@ function runTrustReconcile({ bundle = null, commands = [], repoRoot = null, mani
   // to pick, among per-session candidates, the one that attests THIS change.
   const scopeCtx = resolveScopeContext(resolvedRepoRoot);
 
+  // Diagnostic-only (ADR 0022 §1, issue #305): audit-log any runtime-session commit
+  // trailer found in range — logged for attribution, never gating. Runs unconditionally,
+  // regardless of bundle/DECLARED branch, immediately after scopeCtx resolves and before
+  // bundle auto-discovery/Step 1, so it always fires the same way whether or not a bundle
+  // or DECLARED exemption is later found. Never affects ciResults/issues[]/exit code.
+  logRuntimeSessionTrailers(resolvedRepoRoot, scopeCtx);
+
   let bundlePath = explicitBundlePath || discoverBundle(resolvedRepoRoot, scopeCtx.sha) || null;
   const bundleWasAutoDiscovered = !explicitBundlePath && !!bundlePath;
 
@@ -1321,6 +1452,11 @@ module.exports.noEvidenceCommandIssues = noEvidenceCommandIssues;
 module.exports.reconcilableManifestIssues = reconcilableManifestIssues;
 module.exports.sessionLocalShapeIssues = sessionLocalShapeIssues;
 
+// Exported for evals (#305 trailer-diagnostic coverage) — read-only diagnostic helpers,
+// never gating; see the header comment's "Runtime-session commit-trailer diagnostic" note.
+module.exports.findRuntimeSessionTrailers = findRuntimeSessionTrailers;
+module.exports.logRuntimeSessionTrailers = logRuntimeSessionTrailers;
+
 if (require.main === module) {
   main();
 }

package/scripts/hooks/codex-hook-adapter.js

@@ -12,6 +12,7 @@
 
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { extractExitCodeFromBanner, readExitCodeFromRollout } = require('./lib/codex-exit-code');
 
 const MAX_STDIN = 1024 * 1024;
 
@@ -127,6 +128,73 @@ function blockedOutput(event, reason) {
   };
 }
 
+/**
+ * enrichEvidenceCapturePayload(raw, hookId, event) → string
+ *
+ * Codex-only, evidence-capture-only enrichment (#470): codex's PostToolUse
+ * payload carries no structured exit code, so `evidence-capture.js`'s rule 3
+ * (no signal) would otherwise fire on every codex command, including
+ * genuinely failing ones. This injects a deterministic `tool_response.exitCode`
+ * extracted from the codex host banner (`Process exited with code N`) BEFORE
+ * the payload reaches evidence-capture, so capture stays host-agnostic and
+ * never itself scans narration (docs/spec/runtime-hook-surface.md §2.5).
+ *
+ * Narrowly gated to hookId === 'evidence-capture' && event === 'PostToolUse'
+ * so every other codex hook (quality-gate, workflow-steering, stop-goal-fit,
+ * ...) is byte-unchanged. Fail-open: any parse error, missing field, or
+ * missing/oversized/unreadable rollout returns `raw` unchanged — a hook must
+ * never crash the agent, and a miss simply lets evidence-capture's own rule 3
+ * (ambiguous default) apply.
+ */
+function enrichEvidenceCapturePayload(raw, hookId, event) {
+  if (hookId !== 'evidence-capture' || event !== 'PostToolUse') return raw;
+  try {
+    const payload = JSON.parse(raw);
+    if (!payload || typeof payload !== 'object') return raw;
+
+    // Tier 1: a payload output field, if codex ever surfaces one directly
+    // (cheap; observed absent on codex today — checked defensively).
+    const outputFields = [
+      payload.tool_response && payload.tool_response.output,
+      payload.tool_response && payload.tool_response.stdout,
+      payload.tool_output && payload.tool_output.output,
+      payload.tool_output && payload.tool_output.stdout,
+      payload.output,
+    ];
+    let exitCode = null;
+    for (const field of outputFields) {
+      if (typeof field !== 'string' || !field) continue;
+      const found = extractExitCodeFromBanner(field);
+      if (found !== null) { exitCode = found; break; }
+    }
+
+    // Tier 2: bounded tail read of the session rollout at transcript_path.
+    if (exitCode === null && typeof payload.transcript_path === 'string' && payload.transcript_path) {
+      // No documented codex field correlates a PostToolUse payload to a
+      // rollout function_call_output's call_id today; try the plausible
+      // candidates defensively and fall back to "last banner in the tail"
+      // when none are present (see codex-exit-code.js doc comment). `command`
+      // is passed alongside for the command cross-check correlation (Decision
+      // B, #470 iteration 2): absent a call_id match, it lets the helper
+      // decline (rather than mis-attribute) when the newest rollout banner's
+      // paired call doesn't match the command that triggered this PostToolUse.
+      const callId = payload.call_id || payload.tool_call_id || payload.id || null;
+      const command = payload.tool_input && payload.tool_input.command;
+      exitCode = readExitCodeFromRollout(payload.transcript_path, { callId, command });
+    }
+
+    if (exitCode === null) return raw;
+
+    const existingResponse = payload.tool_response && typeof payload.tool_response === 'object'
+      ? payload.tool_response
+      : {};
+    payload.tool_response = { ...existingResponse, exitCode };
+    return JSON.stringify(payload);
+  } catch {
+    return raw; // fail-open: malformed payload or helper throw — pass through unchanged
+  }
+}
+
 async function main() {
   const [, , hookId, relScriptPath, profilesCsv] = process.argv;
   const { raw, truncated } = await readStdinRaw();
@@ -138,9 +206,16 @@ async function main() {
     return;
   }
 
+  // Enrich only the evidence-capture PostToolUse invocation with a structured
+  // exit code extracted from the codex host banner (#470). `effectiveRaw` is
+  // used for BOTH the spawn input and the stdout echo-diff below so the two
+  // stay consistent (an enriched-vs-original mismatch would leak the raw JSON
+  // as additionalContext via guidanceFromStdout).
+  const effectiveRaw = enrichEvidenceCapturePayload(raw, hookId, event);
+
   const runHookPath = path.resolve(__dirname, 'run-hook.js');
   const result = spawnSync(process.execPath, [runHookPath, hookId, relScriptPath, profilesCsv || ''], {
-    input: raw,
+    input: effectiveRaw,
     encoding: 'utf8',
     cwd: process.cwd(),
     env: {
@@ -166,7 +241,7 @@ async function main() {
   }
 
   if (result.stderr) process.stderr.write(result.stderr);
-  const output = successOutput(event, guidanceFromStdout(raw, result.stdout));
+  const output = successOutput(event, guidanceFromStdout(effectiveRaw, result.stdout));
   if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
 }
 

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 = {