@kontourai/flow-agents 4.2.0 → 4.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [4.2.1](https://github.com/kontourai/flow-agents/compare/v4.2.0...v4.2.1) (2026-07-19)
+
+
+### Fixes
+
+* correlate Codex command results exactly ([#710](https://github.com/kontourai/flow-agents/issues/710)) ([089aca3](https://github.com/kontourai/flow-agents/commit/089aca32ecc41d637d770ae4b1b447956de0dc3f))
+* restore clean npm installs ([#707](https://github.com/kontourai/flow-agents/issues/707)) ([2096acd](https://github.com/kontourai/flow-agents/commit/2096acddb6bf48db5dcad2a24f744b5b72022e73))
+* scope critique freshness to gate visits ([#724](https://github.com/kontourai/flow-agents/issues/724)) ([d2dc723](https://github.com/kontourai/flow-agents/commit/d2dc723b73f27fa24e94604492dbb1fffc82af1d))
+
 ## [4.2.0](https://github.com/kontourai/flow-agents/compare/v4.1.0...v4.2.0) (2026-07-18)
 
 

package/build/src/builder-flow-runtime.js

@@ -572,7 +572,7 @@ async function bundleGateEvidence(bundle, gate, state, subject, projectRoot, man
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", `is not declared by gate ${String(gate.id ?? "<unknown>")}`);
     }
     if (String(gate.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 };
 }
@@ -602,8 +602,8 @@ function timestampAtOrAfter(value, boundary) {
     const parsed = parseTimestamp(value);
     return parsed !== null && parsed >= boundary;
 }
-async function assertVerifiedTestsTrust(claims, projectRoot) {
-    const testClaims = claims.filter((claim) => isRecord(claim)
+async function assertVerifiedTestsTrust(currentGateClaims, projectRoot) {
+    const testClaims = currentGateClaims.filter((claim) => isRecord(claim)
         && claim.claimType === "builder.verify.tests"
         && claim.value === "pass"
         && isRecord(claim.metadata)
@@ -611,7 +611,12 @@ async function assertVerifiedTestsTrust(claims, projectRoot) {
         && 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) => 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) => isRecord(claim)
         && isRecord(claim.metadata)
         && claim.metadata.origin === "critique"
         && typeof claim.metadata.superseded_by !== "string");
@@ -627,7 +632,7 @@ async function assertVerifiedTestsTrust(claims, projectRoot) {
         await Promise.all(artifacts.map((artifact) => assertReviewedArtifactDigest(artifact, projectRoot)));
         assertReviewedWorkspaceSnapshot(claim, artifacts, projectRoot);
     }));
-    const criteria = claims.filter((claim) => isRecord(claim) && isRecord(claim.metadata) && claim.metadata.origin === "acceptance");
+    const criteria = currentGateClaims.filter((claim) => 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/context/contracts/verification-contract.md

@@ -20,6 +20,12 @@ Verifiers and reviewers do not modify source code. They may run commands, inspec
 
 Verifiers write evidence and acceptance status **through** `record-evidence` (directly, or via the orchestrating skill), never by hand-authoring `evidence.json`, `acceptance.json`, or `trust.bundle`. Those bespoke sidecars were retired as the source of truth by ADR 0010 Phase 4c; the `trust.bundle` is the sole verification artifact, and only the sidecar writer performs the evidence classification (`evidenceType`/`method` derivation and manifest reconciliation) the CI trust anchor depends on (ADR 0020). `config-protection.js` blocks direct tool writes to these gate files by design. If the sidecar writer is unavailable, record the exact gap instead of writing the files by hand.
 
+### Critique Generations Across Route-Backs
+
+Each visit to a verification gate establishes a critique generation. Critiques acquired during that visit must target the current implementation snapshot, and every live reviewer slice in the generation participates in the gate decision. A disputed finding therefore cannot be hidden by adding a different reviewer.
+
+When Flow routes back and later re-enters verification, a fresh critique generation is required. Older reviewer slices remain immutable audit history in the trust bundle and evidence manifest, but their prior snapshot hashes are not reinterpreted as reviews of the new implementation. A reviewer handoff must use the public critique writer; it must never require actor impersonation or direct trust-bundle edits.
+
 ## Mutation Testing Runs In A Scratch Copy
 
 Mutation-testing tools (Stryker or equivalent) **must** run against a scratch/throwaway copy of the working tree, never the live working tree. They deliberately introduce defects to measure test-suite sensitivity; running them in place risks leaving mutated source, corrupting the checkout, or tripping the gate/anchor on injected failures. Copy the tree to a temporary directory (or a git worktree/clone) and run the mutation tool there; discard it afterward.

package/dist/base/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "type": "module"
 }

package/dist/base/build/src/builder-flow-runtime.js

@@ -572,7 +572,7 @@ async function bundleGateEvidence(bundle, gate, state, subject, projectRoot, man
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", `is not declared by gate ${String(gate.id ?? "<unknown>")}`);
     }
     if (String(gate.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 };
 }
@@ -602,8 +602,8 @@ function timestampAtOrAfter(value, boundary) {
     const parsed = parseTimestamp(value);
     return parsed !== null && parsed >= boundary;
 }
-async function assertVerifiedTestsTrust(claims, projectRoot) {
-    const testClaims = claims.filter((claim) => isRecord(claim)
+async function assertVerifiedTestsTrust(currentGateClaims, projectRoot) {
+    const testClaims = currentGateClaims.filter((claim) => isRecord(claim)
         && claim.claimType === "builder.verify.tests"
         && claim.value === "pass"
         && isRecord(claim.metadata)
@@ -611,7 +611,12 @@ async function assertVerifiedTestsTrust(claims, projectRoot) {
         && 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) => 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) => isRecord(claim)
         && isRecord(claim.metadata)
         && claim.metadata.origin === "critique"
         && typeof claim.metadata.superseded_by !== "string");
@@ -627,7 +632,7 @@ async function assertVerifiedTestsTrust(claims, projectRoot) {
         await Promise.all(artifacts.map((artifact) => assertReviewedArtifactDigest(artifact, projectRoot)));
         assertReviewedWorkspaceSnapshot(claim, artifacts, projectRoot);
     }));
-    const criteria = claims.filter((claim) => isRecord(claim) && isRecord(claim.metadata) && claim.metadata.origin === "acceptance");
+    const criteria = currentGateClaims.filter((claim) => 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/dist/base/context/contracts/verification-contract.md

@@ -20,6 +20,12 @@ Verifiers and reviewers do not modify source code. They may run commands, inspec
 
 Verifiers write evidence and acceptance status **through** `record-evidence` (directly, or via the orchestrating skill), never by hand-authoring `evidence.json`, `acceptance.json`, or `trust.bundle`. Those bespoke sidecars were retired as the source of truth by ADR 0010 Phase 4c; the `trust.bundle` is the sole verification artifact, and only the sidecar writer performs the evidence classification (`evidenceType`/`method` derivation and manifest reconciliation) the CI trust anchor depends on (ADR 0020). `config-protection.js` blocks direct tool writes to these gate files by design. If the sidecar writer is unavailable, record the exact gap instead of writing the files by hand.
 
+### Critique Generations Across Route-Backs
+
+Each visit to a verification gate establishes a critique generation. Critiques acquired during that visit must target the current implementation snapshot, and every live reviewer slice in the generation participates in the gate decision. A disputed finding therefore cannot be hidden by adding a different reviewer.
+
+When Flow routes back and later re-enters verification, a fresh critique generation is required. Older reviewer slices remain immutable audit history in the trust bundle and evidence manifest, but their prior snapshot hashes are not reinterpreted as reviews of the new implementation. A reviewer handoff must use the public critique writer; it must never require actor impersonation or direct trust-bundle edits.
+
 ## Mutation Testing Runs In A Scratch Copy
 
 Mutation-testing tools (Stryker or equivalent) **must** run against a scratch/throwaway copy of the working tree, never the live working tree. They deliberately introduce defects to measure test-suite sensitivity; running them in place risks leaving mutated source, corrupting the checkout, or tripping the gate/anchor on injected failures. Copy the tree to a temporary directory (or a git worktree/clone) and run the mutation tool there; discard it afterward.

package/dist/base/evals/acceptance/prove-capture-teeth.sh

@@ -246,6 +246,30 @@ codex_banner_teeth(){
   else
     _f "Codex banner CALL_ID: did not record pass/exitCode:0 for the call_id-matched entry: $(cat "$log_callid" 2>/dev/null)"
   fi
+
+  # --- PARALLEL command correlation (#644): current Codex exec_command calls
+  # store arguments under `cmd`. With no hook call_id, each PostToolUse event
+  # must resolve its exact function_call/output pair by normalized command.
+  local proj_parallel; proj_parallel="$(mktemp -d)"
+  mkdir -p "$proj_parallel/.kontourai/flow-agents/cap-codex-parallel"
+  printf '# Repo\n' > "$proj_parallel/AGENTS.md"
+  printf '%s' '{"schema_version":"1.0","task_slug":"cap-codex-parallel","status":"in_progress","phase":"verification","updated_at":"2026-06-23T00:00:00Z"}' > "$proj_parallel/.kontourai/flow-agents/cap-codex-parallel/state.json"
+  local rollout_parallel="$proj_parallel/rollout-parallel.jsonl"
+  printf '%s\n' '{"timestamp":"2026-06-23T00:00:00Z","type":"response_item","payload":{"type":"function_call","call_id":"call_pass","name":"exec_command","arguments":"{\"cmd\":\"find seed -type f\"}"}}' > "$rollout_parallel"
+  printf '%s\n' '{"timestamp":"2026-06-23T00:00:01Z","type":"response_item","payload":{"type":"function_call","call_id":"call_fail","name":"exec_command","arguments":"{\"cmd\":\"cat seed/src/window.js\"}"}}' >> "$rollout_parallel"
+  printf '%s\n' '{"timestamp":"2026-06-23T00:00:02Z","type":"response_item","payload":{"type":"function_call_output","call_id":"call_pass","output":"Process exited with code 0\nOutput:\n..."}}' >> "$rollout_parallel"
+  printf '%s\n' '{"timestamp":"2026-06-23T00:00:03Z","type":"response_item","payload":{"type":"function_call_output","call_id":"call_fail","output":"Process exited with code 1\nOutput:\n..."}}' >> "$rollout_parallel"
+  printf '{"hook_event_name":"PostToolUse","tool_name":"Bash","cwd":"%s","tool_input":{"command":"find seed -type f"},"transcript_path":"%s"}' "$proj_parallel" "$rollout_parallel" \
+    | env CODEX_HOME="$home" CLAUDE_PROJECT_DIR="$home" bash -c "$capcmd" >/dev/null 2>&1 || true
+  printf '{"hook_event_name":"PostToolUse","tool_name":"Bash","cwd":"%s","tool_input":{"command":"cat seed/src/window.js"},"transcript_path":"%s"}' "$proj_parallel" "$rollout_parallel" \
+    | env CODEX_HOME="$home" CLAUDE_PROJECT_DIR="$home" bash -c "$capcmd" >/dev/null 2>&1 || true
+  local log_parallel="$proj_parallel/.kontourai/flow-agents/cap-codex-parallel/command-log.jsonl"
+  if rg -q '"command":"find seed -type f","observedResult":"pass","exitCode":0' "$log_parallel" 2>/dev/null \
+    && rg -q '"command":"cat seed/src/window.js","observedResult":"fail","exitCode":1' "$log_parallel" 2>/dev/null; then
+    _p "Codex banner PARALLEL: cmd correlation keeps each command attached to its own exit code"
+  else
+    _f "Codex banner PARALLEL: command/result attribution crossed or stayed unresolved: $(cat "$log_parallel" 2>/dev/null)"
+  fi
 }
 
 run_bundle "Claude Code" "$ROOT/dist/claude-code/install.sh" ".claude/settings.json" "CLAUDE_PROJECT_DIR"

package/dist/base/evals/integration/test_effective_backlog_settings.sh

@@ -2,13 +2,18 @@
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-SCRIPT="$ROOT/scripts/effective-backlog-settings.js"
-PROJECT="$ROOT/context/settings/backlog-provider-settings.json"
-GLOBAL="$ROOT/evals/fixtures/backlog-provider-settings/global-default.json"
-OVERRIDE="$ROOT/evals/fixtures/backlog-provider-settings/project-override.json"
-EMPTY="$(mktemp)"
-trap 'rm -f "$EMPTY"' EXIT
-printf '{"schema_version":"1.0","projects":[]}\n' > "$EMPTY"
+CLI="$ROOT/build/src/cli.js"
+BACKLOG_SETTINGS="$ROOT/context/settings/backlog-provider-settings.json"
+ASSIGNMENT_SETTINGS="$ROOT/context/settings/assignment-provider-settings.json"
+BACKLOG_GLOBAL="$ROOT/evals/fixtures/backlog-provider-settings/global-default.json"
+BACKLOG_OVERRIDE="$ROOT/evals/fixtures/backlog-provider-settings/project-override.json"
+TMPDIR_EVAL="$(mktemp -d)"
+EMPTY_BACKLOG="$TMPDIR_EVAL/empty-backlog-settings.json"
+EMPTY_ASSIGNMENT="$TMPDIR_EVAL/empty-assignment-settings.json"
+trap 'rm -rf "$TMPDIR_EVAL"' EXIT
+
+printf '{"schema_version":"1.0","projects":[]}\n' > "$EMPTY_BACKLOG"
+printf '{"schema_version":"1.0","projects":[]}\n' > "$EMPTY_ASSIGNMENT"
 
 errors=0
 pass() { echo "  ✓ $1"; }
@@ -18,17 +23,32 @@ json_value() {
   NO_COLOR=1 FORCE_COLOR=0 node -e 'const fs=require("fs"); let cur=JSON.parse(fs.readFileSync(0,"utf8")); for (const part of process.argv[1].split(".")) cur=Array.isArray(cur) ? cur[Number(part)] : cur[part]; console.log(cur);' "$1"
 }
 
-echo "=== Effective Backlog Settings ==="
+echo "=== Effective provider settings ==="
+
+# Build exactly once before calling the actual compiled CLI commands below.
+if (cd "$ROOT" && npm run build --silent); then
+  pass "compiled CLI build succeeds"
+else
+  fail "compiled CLI build succeeds"
+fi
 
-default_result="$(cd "$ROOT" && npm run --silent effective-backlog-settings -- --repo-path . --json)"
-[[ "$(printf '%s' "$default_result" | json_value status)" == "configured" ]] && pass "default project settings resolve through npm command" || fail "default project settings resolve through npm command"
+if [[ ! -f "$CLI" ]]; then
+  fail "compiled CLI is available"
+else
+  pass "compiled CLI is available"
+fi
+
+echo "--- existing backlog precedence and ask-user behavior ---"
+
+default_result="$(node "$CLI" effective-backlog-settings --repo-path "$ROOT" --json 2>/dev/null)"
+[[ "$(printf '%s' "$default_result" | json_value status)" == "configured" ]] && pass "default project settings resolve through compiled CLI" || fail "default project settings resolve through compiled CLI"
 [[ "$(printf '%s' "$default_result" | json_value settings.work_item_provider.kind)" == "github" ]] && pass "default provider kind is github" || fail "default provider kind is github"
 [[ "$(printf '%s' "$default_result" | json_value settings.work_item_provider.repo.owner)" == "kontourai" ]] && pass "default repo owner is kontourai" || fail "default repo owner is kontourai"
 [[ "$(printf '%s' "$default_result" | json_value settings.work_item_provider.repo.name)" == "flow-agents" ]] && pass "default repo name is flow-agents" || fail "default repo name is flow-agents"
 [[ "$(printf '%s' "$default_result" | json_value settings.board_provider.board.number)" == "1" ]] && pass "default project number is 1" || fail "default project number is 1"
 ! printf '%s' "$default_result" | rg -q '/build/context/settings/backlog-provider-settings.json' && pass "default settings path is not build-relative" || fail "default settings path is not build-relative"
 
-configured="$(node "$SCRIPT" --repo-path "$ROOT" --project-settings "$PROJECT" --global-settings "$EMPTY" --json)"
+configured="$(node "$CLI" effective-backlog-settings --repo-path "$ROOT" --project-settings "$BACKLOG_SETTINGS" --global-settings "$EMPTY_BACKLOG" --json)"
 [[ "$(printf '%s' "$configured" | json_value status)" == "configured" ]] && pass "configured repo resolves" || fail "configured repo resolves"
 [[ "$(printf '%s' "$configured" | json_value settings.work_item_provider.kind)" == "github" ]] && pass "provider kind is github" || fail "provider kind is github"
 [[ "$(printf '%s' "$configured" | json_value settings.work_item_provider.repo.owner)" == "kontourai" ]] && pass "repo owner is kontourai" || fail "repo owner is kontourai"
@@ -38,21 +58,104 @@ printf '%s' "$configured" | rg -F -q '"ready_statuses": [' && pass "filters incl
 printf '%s' "$configured" | rg -F -q '"include_labels": []' && pass "filters do not require labels by default" || fail "filters do not require labels by default"
 printf '%s' "$configured" | rg -q '"prefer_finishing_active_work": true' && pass "WIP policy prefers finishing active work" || fail "WIP policy prefers finishing active work"
 
-override_result="$(node "$SCRIPT" --repo-path "$ROOT" --project-settings "$OVERRIDE" --global-settings "$GLOBAL" --json)"
+override_result="$(node "$CLI" effective-backlog-settings --repo-path "$ROOT" --project-settings "$BACKLOG_OVERRIDE" --global-settings "$BACKLOG_GLOBAL" --json)"
 [[ "$(printf '%s' "$override_result" | json_value source)" == "project" ]] && pass "project settings override global defaults" || fail "project settings override global defaults"
 [[ "$(printf '%s' "$override_result" | json_value settings.board_provider.board.number)" == "1" ]] && pass "project override keeps Project 1" || fail "project override keeps Project 1"
 ! printf '%s' "$override_result" | rg -q 'global-ready' && pass "project override replaces global filters" || fail "project override replaces global filters"
 
-missing_output="$(node "$SCRIPT" --repo-path "$ROOT" --project-settings "$EMPTY" --global-settings "$EMPTY" --json 2>/dev/null)"
+missing_output="$(node "$CLI" effective-backlog-settings --repo-path "$ROOT" --project-settings "$EMPTY_BACKLOG" --global-settings "$EMPTY_BACKLOG" --json 2>/dev/null)"
 missing_status=$?
 [[ "$missing_status" -eq 2 ]] && pass "missing settings exits with ask-user status" || fail "missing settings exits with ask-user status"
 [[ "$(printf '%s' "$missing_output" | json_value status)" == "ask_user" ]] && pass "missing settings reports ask_user" || fail "missing settings reports ask_user"
 printf '%s' "$missing_output" | rg -q 'WorkItemProvider and BoardProvider' && pass "missing settings names provider roles" || fail "missing settings names provider roles"
 
+echo "--- public self-configuration and external multi-repository settings ---"
+
+# Product-specific fleet routing belongs in consumer-owned settings. The public package proves
+# that an external settings file can configure multiple repositories without embedding those
+# consumer mappings in Flow Agents source.
+if node --input-type=module - "$ROOT" "$CLI" "$TMPDIR_EVAL/repos" "$BACKLOG_SETTINGS" "$ASSIGNMENT_SETTINGS" "$EMPTY_BACKLOG" "$EMPTY_ASSIGNMENT" <<'NODE'
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import Ajv2020 from "ajv/dist/2020.js";
+
+const [root, cli, reposRoot, publicBacklogPath, publicAssignmentPath, emptyBacklog, emptyAssignment] = process.argv.slice(2);
+const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+const assert = (condition, message) => {
+  if (!condition) throw new Error(message);
+};
+
+const backlogSchema = readJson(path.join(root, "schemas/backlog-provider-settings.schema.json"));
+const assignmentSchema = readJson(path.join(root, "schemas/assignment-provider-settings.schema.json"));
+const ajv = new Ajv2020({ allErrors: true });
+const validateBacklog = ajv.compile(backlogSchema);
+const validateAssignment = ajv.compile(assignmentSchema);
+
+const publicBacklog = readJson(publicBacklogPath);
+const publicAssignment = readJson(publicAssignmentPath);
+assert(validateBacklog(publicBacklog), `public backlog settings schema validation failed: ${ajv.errorsText(validateBacklog.errors)}`);
+assert(validateAssignment(publicAssignment), `public assignment settings schema validation failed: ${ajv.errorsText(validateAssignment.errors)}`);
+assert(publicBacklog.projects.length === 1 && publicBacklog.projects[0]?.project?.repo?.name === "flow-agents", "public backlog settings must remain self-only");
+assert(publicAssignment.projects.length === 1 && publicAssignment.projects[0]?.project?.repo?.name === "flow-agents", "public assignment settings must remain self-only");
+
+const owner = "example-org";
+const targets = ["alpha", "beta"];
+const projectNumber = 42;
+const repoRef = (name) => ({ owner, name, url: `https://github.com/${owner}/${name}` });
+const externalBacklog = {
+  schema_version: "1.0",
+  projects: targets.map((name) => ({
+    project: { repo: repoRef(name) },
+    work_item_provider: { role: "WorkItemProvider", kind: "github", repo: repoRef(name), capabilities: ["issues", "labels", "assignees", "pr_links", "comments"] },
+    board_provider: { role: "BoardProvider", kind: "github", repo: repoRef(name), board: { type: "github_project", owner, number: projectNumber, url: `https://github.com/orgs/${owner}/projects/${projectNumber}` }, capabilities: ["projects_boards", "status_fields", "custom_fields"] },
+    selection: { filters: { issue_state: "open", include_labels: [], ready_statuses: ["ready"], exclude_statuses: ["triage", "in_progress", "blocked", "review", "verification", "done"] }, wip_policy: { prefer_finishing_active_work: true, active_statuses: ["in_progress", "review", "verification"], block_new_work_when_active_count_exceeds: 0 } },
+  })),
+};
+const externalAssignment = {
+  schema_version: "1.0",
+  projects: targets.map((name) => ({
+    project: { repo: repoRef(name) },
+    provider: { kind: "github", repo: repoRef(name), capabilities: ["assignees", "labels", "comments"] },
+    policy: { label_name: "agent:claimed", claim_comment_marker: "<!-- flow-agents:assignment-claim -->", human_assignee_policy: { behavior: "ask_first", idle_threshold_days: 3 }, comment_refresh_on_phase_transition: false },
+  })),
+};
+assert(validateBacklog(externalBacklog), `external backlog settings schema validation failed: ${ajv.errorsText(validateBacklog.errors)}`);
+assert(validateAssignment(externalAssignment), `external assignment settings schema validation failed: ${ajv.errorsText(validateAssignment.errors)}`);
+
+fs.mkdirSync(reposRoot, { recursive: true });
+const externalBacklogPath = path.join(reposRoot, "backlog-provider-settings.json");
+const externalAssignmentPath = path.join(reposRoot, "assignment-provider-settings.json");
+fs.writeFileSync(externalBacklogPath, JSON.stringify(externalBacklog, null, 2));
+fs.writeFileSync(externalAssignmentPath, JSON.stringify(externalAssignment, null, 2));
+
+for (const name of targets) {
+  const repoPath = path.join(reposRoot, name);
+  fs.mkdirSync(repoPath, { recursive: true });
+  fs.writeFileSync(path.join(repoPath, "package.json"), JSON.stringify({ name: `fixture-${name}`, repository: { type: "git", url: `https://github.com/${owner}/${name}.git` } }, null, 2));
+  const resolve = (command, globalPath, emptyProject) => JSON.parse(execFileSync(process.execPath, [cli, command, "--repo-path", repoPath, "--project-settings", emptyProject, "--global-settings", globalPath, "--json"], { encoding: "utf8" }));
+  const backlogResult = resolve("effective-backlog-settings", externalBacklogPath, emptyBacklog);
+  const assignmentResult = resolve("effective-assignment-provider-settings", externalAssignmentPath, emptyAssignment);
+
+  assert(backlogResult.status === "configured" && backlogResult.source === "global", `${name} backlog settings must resolve from the external file`);
+  assert(backlogResult.settings.work_item_provider?.repo?.name === name, `${name} must select its own work item repository`);
+  assert(backlogResult.settings.board_provider?.board?.number === projectNumber, `${name} must select the external board`);
+  assert(assignmentResult.status === "configured" && assignmentResult.source === "global", `${name} assignment settings must resolve from the external file`);
+  assert(assignmentResult.settings.provider?.repo?.name === name, `${name} must select its own assignment repository`);
+}
+
+console.log("Public settings remain self-only and external multi-repository settings resolve through the supported global precedence layer.");
+NODE
+then
+  pass "public settings stay self-only and external multi-repository settings resolve"
+else
+  fail "public settings stay self-only and external multi-repository settings resolve"
+fi
+
 if [[ "$errors" -eq 0 ]]; then
-  echo "Effective backlog settings checks passed"
+  echo "Effective provider settings checks passed"
 else
-  echo "Effective backlog settings checks failed: $errors"
+  echo "Effective provider settings checks failed: $errors"
 fi
 
 exit "$errors"

package/dist/base/install.sh

@@ -72,7 +72,7 @@ if [[ ! -e "$DEST/AGENTS.md" && ! -L "$DEST/AGENTS.md" ]]; then
   rm -f "$instruction_tmp"
 fi
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --stamp-only --version "4.2.0" --install-record "$DEST/.flow-agents/install.json" --runtime "base" || true
+  node "$DEST/scripts/install-merge.js" --stamp-only --version "4.2.1" --install-record "$DEST/.flow-agents/install.json" --runtime "base" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

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

@@ -113,10 +113,13 @@ function normalizeCallArguments(argumentsField) {
     }
   }
   if (!parsed || typeof parsed !== 'object') return null;
-  return normalizeCommandText(parsed.command);
+  // Codex records exec_command arguments under `cmd`; older shell fixtures
+  // and some adapters use `command`.
+  return normalizeCommandText(parsed.cmd) || normalizeCommandText(parsed.command);
 }
 
 const OUTPUT_FIELD_NEEDLE = '"output":"';
+const COMMAND_FUNCTION_NAMES = new Set(['exec_command', 'shell']);
 
 /**
  * parseCandidateLine(line, maxLineHeadBytes) → candidate | null
@@ -149,7 +152,15 @@ function parseCandidateLine(line, maxLineHeadBytes) {
       return { type: 'function_call_output', callId, output: payload.output };
     }
     if (payload.type === 'function_call') {
-      return { type: 'function_call', callId, command: normalizeCallArguments(payload.arguments) };
+      const name = typeof payload.name === 'string' && payload.name.trim() ? payload.name.trim() : null;
+      const command = normalizeCallArguments(payload.arguments);
+      const commandCapable = name === null || COMMAND_FUNCTION_NAMES.has(name) || command !== null;
+      return {
+        type: 'function_call',
+        callId,
+        commandCapable,
+        command,
+      };
     }
     return null;
   }
@@ -214,13 +225,12 @@ function resolveContainedRealPath(transcriptPath) {
  * 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.
+ *   2. Absent a call_id match: pair outputs with calls by rollout call_id and
+ *      select the only pair whose normalized arguments match `command`. Zero
+ *      matches or multiple matches DECLINE (`null`) rather than attribute a
+ *      neighboring or repeated command's exit code.
+ *   3. If no pairing is resolvable at all and the rollout contains exactly one
+ *      output with no function call, use that genuinely unpaired legacy output.
  *
  * Any failure (missing/unreadable/non-regular file, containment violation,
  * malformed JSON lines, no candidate found) yields `null` — never throws.
@@ -271,41 +281,83 @@ function readExitCodeFromRollout(transcriptPath, options) {
   }
   if (truncated && lines.length > 1) lines.shift();
 
-  let matchedByCallId = null;
+  const outputsByRequestedCallId = [];
   let newestOutputEntry = null;
-  let pairedCommand = null;
+  const outputEntries = [];
+  const commandByCallId = new Map();
+  const seenFunctionCallIds = new Set();
+  const ambiguousCallIds = new Set();
+  let functionCallCount = 0;
+  let sawUnclassifiableLine = false;
+  let sawUnresolvableFunctionCall = false;
 
   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) {
+      if (Buffer.byteLength(line, 'utf8') > maxLineHeadBytes) {
+        sawUnclassifiableLine = true;
+      } else {
+        try {
+          JSON.parse(line); // valid non-candidate events do not poison correlation
+        } catch {
+          sawUnclassifiableLine = true;
+        }
+      }
+      continue; // malformed/partial/unrecognized line — skip, keep scanning
+    }
 
     if (candidate.type === 'function_call_output') {
+      outputEntries.push(candidate); // scan order is newest to oldest
       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
+        outputsByRequestedCallId.push(candidate);
       }
     } else if (candidate.type === 'function_call') {
-      if (newestOutputEntry && pairedCommand === null && candidate.callId === newestOutputEntry.callId) {
-        pairedCommand = candidate.command;
+      functionCallCount += 1;
+      if (candidate.callId) {
+        if (seenFunctionCallIds.has(candidate.callId)) ambiguousCallIds.add(candidate.callId);
+        else seenFunctionCallIds.add(candidate.callId);
+      }
+      if (candidate.commandCapable && candidate.callId && candidate.command !== null) {
+        if (!commandByCallId.has(candidate.callId)) commandByCallId.set(candidate.callId, candidate.command);
+      } else if (candidate.commandCapable) {
+        sawUnresolvableFunctionCall = true;
       }
     }
   }
 
   let chosenOutput = null;
-  if (matchedByCallId) {
-    chosenOutput = matchedByCallId.output;
+  if ((callId || command) && sawUnclassifiableLine) return null;
+  if (callId) {
+    if (outputsByRequestedCallId.length === 1 && !ambiguousCallIds.has(callId)) {
+      chosenOutput = outputsByRequestedCallId[0].output;
+    } else {
+      return null; // explicit call ID is unresolved, reused, or has duplicate outputs
+    }
   } else if (newestOutputEntry) {
-    if (pairedCommand !== null && command) {
-      if (pairedCommand === command) {
-        chosenOutput = newestOutputEntry.output;
+    if (command) {
+      if (sawUnresolvableFunctionCall) return null;
+      const matchingCallIds = [...commandByCallId.entries()]
+        .filter(([, candidateCommand]) => candidateCommand === command)
+        .map(([candidateCallId]) => candidateCallId);
+      const matches = outputEntries.filter((entry) => commandByCallId.get(entry.callId) === command);
+      if (matchingCallIds.length === 1
+        && !ambiguousCallIds.has(matchingCallIds[0])
+        && matches.length === 1) {
+        chosenOutput = matches[0].output;
+      } else if (matchingCallIds.length > 0 || matches.length > 0 || commandByCallId.size > 0) {
+        return null; // no unique command correlation
+      } else if (!truncated && outputEntries.length === 1 && functionCallCount === 0) {
+        chosenOutput = newestOutputEntry.output; // genuinely unpaired legacy fallback
       } else {
-        return null; // positive command mismatch — decline rather than mis-attribute
+        return null; // multi-call or partially paired tail
       }
+    } else if (!truncated && outputEntries.length === 1 && functionCallCount === 0) {
+      chosenOutput = newestOutputEntry.output; // genuinely unpaired legacy fallback
     } else {
-      chosenOutput = newestOutputEntry.output; // single-call fallback — no pairing resolvable
+      return null; // no correlation signal for a paired or multi-call tail
     }
   }
 

package/dist/claude-code/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "type": "module"
 }

package/dist/claude-code/build/src/builder-flow-runtime.js

@@ -572,7 +572,7 @@ async function bundleGateEvidence(bundle, gate, state, subject, projectRoot, man
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", `is not declared by gate ${String(gate.id ?? "<unknown>")}`);
     }
     if (String(gate.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 };
 }
@@ -602,8 +602,8 @@ function timestampAtOrAfter(value, boundary) {
     const parsed = parseTimestamp(value);
     return parsed !== null && parsed >= boundary;
 }
-async function assertVerifiedTestsTrust(claims, projectRoot) {
-    const testClaims = claims.filter((claim) => isRecord(claim)
+async function assertVerifiedTestsTrust(currentGateClaims, projectRoot) {
+    const testClaims = currentGateClaims.filter((claim) => isRecord(claim)
         && claim.claimType === "builder.verify.tests"
         && claim.value === "pass"
         && isRecord(claim.metadata)
@@ -611,7 +611,12 @@ async function assertVerifiedTestsTrust(claims, projectRoot) {
         && 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) => 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) => isRecord(claim)
         && isRecord(claim.metadata)
         && claim.metadata.origin === "critique"
         && typeof claim.metadata.superseded_by !== "string");
@@ -627,7 +632,7 @@ async function assertVerifiedTestsTrust(claims, projectRoot) {
         await Promise.all(artifacts.map((artifact) => assertReviewedArtifactDigest(artifact, projectRoot)));
         assertReviewedWorkspaceSnapshot(claim, artifacts, projectRoot);
     }));
-    const criteria = claims.filter((claim) => isRecord(claim) && isRecord(claim.metadata) && claim.metadata.origin === "acceptance");
+    const criteria = currentGateClaims.filter((claim) => 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/dist/claude-code/context/contracts/verification-contract.md

@@ -20,6 +20,12 @@ Verifiers and reviewers do not modify source code. They may run commands, inspec
 
 Verifiers write evidence and acceptance status **through** `record-evidence` (directly, or via the orchestrating skill), never by hand-authoring `evidence.json`, `acceptance.json`, or `trust.bundle`. Those bespoke sidecars were retired as the source of truth by ADR 0010 Phase 4c; the `trust.bundle` is the sole verification artifact, and only the sidecar writer performs the evidence classification (`evidenceType`/`method` derivation and manifest reconciliation) the CI trust anchor depends on (ADR 0020). `config-protection.js` blocks direct tool writes to these gate files by design. If the sidecar writer is unavailable, record the exact gap instead of writing the files by hand.
 
+### Critique Generations Across Route-Backs
+
+Each visit to a verification gate establishes a critique generation. Critiques acquired during that visit must target the current implementation snapshot, and every live reviewer slice in the generation participates in the gate decision. A disputed finding therefore cannot be hidden by adding a different reviewer.
+
+When Flow routes back and later re-enters verification, a fresh critique generation is required. Older reviewer slices remain immutable audit history in the trust bundle and evidence manifest, but their prior snapshot hashes are not reinterpreted as reviews of the new implementation. A reviewer handoff must use the public critique writer; it must never require actor impersonation or direct trust-bundle edits.
+
 ## Mutation Testing Runs In A Scratch Copy
 
 Mutation-testing tools (Stryker or equivalent) **must** run against a scratch/throwaway copy of the working tree, never the live working tree. They deliberately introduce defects to measure test-suite sensitivity; running them in place risks leaving mutated source, corrupting the checkout, or tripping the gate/anchor on injected failures. Copy the tree to a temporary directory (or a git worktree/clone) and run the mutation tool there; discard it afterward.

package/dist/claude-code/evals/acceptance/prove-capture-teeth.sh

@@ -246,6 +246,30 @@ codex_banner_teeth(){
   else
     _f "Codex banner CALL_ID: did not record pass/exitCode:0 for the call_id-matched entry: $(cat "$log_callid" 2>/dev/null)"
   fi
+
+  # --- PARALLEL command correlation (#644): current Codex exec_command calls
+  # store arguments under `cmd`. With no hook call_id, each PostToolUse event
+  # must resolve its exact function_call/output pair by normalized command.
+  local proj_parallel; proj_parallel="$(mktemp -d)"
+  mkdir -p "$proj_parallel/.kontourai/flow-agents/cap-codex-parallel"
+  printf '# Repo\n' > "$proj_parallel/AGENTS.md"
+  printf '%s' '{"schema_version":"1.0","task_slug":"cap-codex-parallel","status":"in_progress","phase":"verification","updated_at":"2026-06-23T00:00:00Z"}' > "$proj_parallel/.kontourai/flow-agents/cap-codex-parallel/state.json"
+  local rollout_parallel="$proj_parallel/rollout-parallel.jsonl"
+  printf '%s\n' '{"timestamp":"2026-06-23T00:00:00Z","type":"response_item","payload":{"type":"function_call","call_id":"call_pass","name":"exec_command","arguments":"{\"cmd\":\"find seed -type f\"}"}}' > "$rollout_parallel"
+  printf '%s\n' '{"timestamp":"2026-06-23T00:00:01Z","type":"response_item","payload":{"type":"function_call","call_id":"call_fail","name":"exec_command","arguments":"{\"cmd\":\"cat seed/src/window.js\"}"}}' >> "$rollout_parallel"
+  printf '%s\n' '{"timestamp":"2026-06-23T00:00:02Z","type":"response_item","payload":{"type":"function_call_output","call_id":"call_pass","output":"Process exited with code 0\nOutput:\n..."}}' >> "$rollout_parallel"
+  printf '%s\n' '{"timestamp":"2026-06-23T00:00:03Z","type":"response_item","payload":{"type":"function_call_output","call_id":"call_fail","output":"Process exited with code 1\nOutput:\n..."}}' >> "$rollout_parallel"
+  printf '{"hook_event_name":"PostToolUse","tool_name":"Bash","cwd":"%s","tool_input":{"command":"find seed -type f"},"transcript_path":"%s"}' "$proj_parallel" "$rollout_parallel" \
+    | env CODEX_HOME="$home" CLAUDE_PROJECT_DIR="$home" bash -c "$capcmd" >/dev/null 2>&1 || true
+  printf '{"hook_event_name":"PostToolUse","tool_name":"Bash","cwd":"%s","tool_input":{"command":"cat seed/src/window.js"},"transcript_path":"%s"}' "$proj_parallel" "$rollout_parallel" \
+    | env CODEX_HOME="$home" CLAUDE_PROJECT_DIR="$home" bash -c "$capcmd" >/dev/null 2>&1 || true
+  local log_parallel="$proj_parallel/.kontourai/flow-agents/cap-codex-parallel/command-log.jsonl"
+  if rg -q '"command":"find seed -type f","observedResult":"pass","exitCode":0' "$log_parallel" 2>/dev/null \
+    && rg -q '"command":"cat seed/src/window.js","observedResult":"fail","exitCode":1' "$log_parallel" 2>/dev/null; then
+    _p "Codex banner PARALLEL: cmd correlation keeps each command attached to its own exit code"
+  else
+    _f "Codex banner PARALLEL: command/result attribution crossed or stayed unresolved: $(cat "$log_parallel" 2>/dev/null)"
+  fi
 }
 
 run_bundle "Claude Code" "$ROOT/dist/claude-code/install.sh" ".claude/settings.json" "CLAUDE_PROJECT_DIR"