@kontourai/flow-agents 4.1.0 → 4.2.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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)
+
+
+### Features
+
+* **liveness:** conf-driven console relay enablement ([#567](https://github.com/kontourai/flow-agents/issues/567)) + richer real-liveness signals ([#705](https://github.com/kontourai/flow-agents/issues/705)) ([b1dd5b0](https://github.com/kontourai/flow-agents/commit/b1dd5b081280d49c07d4e92ff2ffc5103dc89800))
+
 ## [4.1.0](https://github.com/kontourai/flow-agents/compare/v4.0.0...v4.1.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/context/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/dist/base/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "4.1.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/context/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/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/evals/integration/test_liveness_console_relay.sh

@@ -18,6 +18,13 @@ source "$ROOT/evals/lib/node.sh"
 
 TMPDIR_EVAL="$(mktemp -d)"
 trap 'rm -rf "$TMPDIR_EVAL"; [[ -n "${STUB_PID:-}" ]] && kill "$STUB_PID" 2>/dev/null' EXIT
+
+# Hermetic HOME: the conf-driven relay resolver (#567) reads <bundle-root>/telemetry-console.conf
+# as a resolution slot. Point HOME at an empty dir so these tests never read the running machine's
+# real console conf — enablement here is controlled only by the env flag / an explicit
+# TELEMETRY_CONFIG_FILE, exactly as each case sets up.
+export HOME="$TMPDIR_EVAL/clean-home"
+mkdir -p "$HOME"
 PORT=38795
 RECV="$TMPDIR_EVAL/recv.jsonl"
 
@@ -29,6 +36,12 @@ fail() { echo "  [FAIL] $1"; errors=$((errors + 1)); }
 # controls the response — "ok" (200) or "fail" (500) — to exercise the relay-failure path.
 start_stub() {
   local mode="$1"
+  # Fresh port per stub: the relay POST is detached/async, so a late POST from a PRIOR "on" case
+  # could otherwise race into the next case's freshly-cleared RECV on a reused port and cause a
+  # spurious "a POST happened" failure in a "no POST" assertion. A new port each time sends any
+  # stray prior-case POST to a now-dead port (connection refused), never into this case's RECV.
+  PORT=$((PORT + 1))
+  ENDPOINT="http://127.0.0.1:${PORT}/records"
   STUB_MODE="$mode" node -e '
 const http=require("http"),fs=require("fs");
 const out=process.argv[1], mode=process.env.STUB_MODE||"ok";
@@ -67,7 +80,7 @@ echo "=== console liveness relay (#295) ==="
 echo "--- 1. relay on+configured: liveness emit mirrors to the Console with Bearer + tenant ---"
 : > "$RECV"; start_stub ok || { fail "stub server did not start"; }
 ROOT_A="$TMPDIR_EVAL/a"
-EVT1='{"type":"claim","subjectId":"relay-subj-1","actor":"claude-code:sessA:host","actor_key":"claude-code:sessA:host","at":"2026-07-05T00:00:00Z","ttlSeconds":1800,"host":"host","branch":"agent/a/relay-subj-1","artifact_dir":"relay-subj-1"}'
+EVT1='{"type":"claim","subjectId":"relay-subj-1","actor":"claude-code:sessA:host","actor_key":"claude-code:sessA:host","at":"2026-07-05T00:00:00Z","ttlSeconds":1800,"host":"host","branch":"agent/a/relay-subj-1","artifact_dir":"relay-subj-1","source":"tool-activity","activity":{"tool":"Bash"}}'
 (
   export FLOW_AGENTS_CONSOLE_LIVENESS_RELAY=1
   export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
@@ -92,6 +105,8 @@ const checks=[
   ["subjectId", b.subjectId==="relay-subj-1"],
   ["actor", b.actor==="claude-code:sessA:host"],
   ["branch", b.branch==="agent/a/relay-subj-1"],
+  ["source tool-activity", b.source==="tool-activity"],
+  ["activity.tool Bash (richer real-liveness rides to the Console)", !!b.activity && b.activity.tool==="Bash"],
 ];
 for(const [name,ok] of checks) console.log((ok?"OK ":"BAD ")+name);
 ' "$RECV" > "$TMPDIR_EVAL/checks.txt" 2>&1
@@ -156,6 +171,81 @@ console.log(hasRawCtl?"RAW":"ESCAPED");
 if grep -q ESCAPED "$TMPDIR_EVAL/inj.txt"; then pass "hostile actor/branch control bytes are JSON-escaped, never raw in the POST body (injection discipline)"; else fail "raw control bytes reached the POST body: $(cat "$TMPDIR_EVAL/inj.txt")"; fi
 stop_stub
 
+# ─── 6. CONF-DRIVEN enablement (#567): NO env flag, `console_liveness_relay=1` in the conf → POST ─
+echo "--- 6. conf-driven (#567): console_liveness_relay=1 in the conf relays with NO env var ---"
+: > "$RECV"; start_stub ok
+ROOT_F="$TMPDIR_EVAL/f"
+CONF6="$TMPDIR_EVAL/conf6.conf"
+printf 'console_telemetry_url=https://example.invalid\nconsole_liveness_relay=1\n' > "$CONF6"
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY   # the whole point: no env var
+  export TELEMETRY_CONFIG_FILE="$CONF6"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"   # POST target (stub)
+  emit_event "$ROOT_F" '{"type":"claim","subjectId":"conf-on-1","actor":"a","at":"t"}'
+)
+[[ -s "$ROOT_F/liveness/events.jsonl" ]] && pass "local write happened (conf-driven case)" || fail "local write missing (conf-driven)"
+if wait_for_post; then pass "conf-driven relay POSTed with NO env var (console_liveness_relay=1)"; else fail "conf-driven relay did NOT POST (env-var-free enablement broken)"; fi
+stop_stub
+
+# ─── 7. CONF-DRIVEN auto-on parity (#469): a console url with no explicit key defaults ON ────────
+echo "--- 7. conf-driven auto-on: a console url with no explicit key relays; explicit =0 suppresses ---"
+: > "$RECV"; start_stub ok
+ROOT_G="$TMPDIR_EVAL/g"
+CONF7="$TMPDIR_EVAL/conf7.conf"
+printf 'console_telemetry_url=https://example.invalid\n' > "$CONF7"   # url only, no explicit key
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  export TELEMETRY_CONFIG_FILE="$CONF7"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
+  emit_event "$ROOT_G" '{"type":"claim","subjectId":"auto-on-1","actor":"a","at":"t"}'
+)
+if wait_for_post; then pass "auto-on: a configured console url defaults the relay ON (#469 parity)"; else fail "auto-on did NOT POST (console-url default-on broken)"; fi
+stop_stub
+
+: > "$RECV"; start_stub ok
+ROOT_H="$TMPDIR_EVAL/h"
+CONF8="$TMPDIR_EVAL/conf8.conf"
+printf 'console_telemetry_url=https://example.invalid\nconsole_liveness_relay=0\n' > "$CONF8"   # explicit off wins
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  export TELEMETRY_CONFIG_FILE="$CONF8"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
+  emit_event "$ROOT_H" '{"type":"claim","subjectId":"conf-off-1","actor":"a","at":"t"}'
+)
+sleep 1
+[[ -s "$ROOT_H/liveness/events.jsonl" ]] && pass "local write happened (explicit conf off)" || fail "local write missing (explicit conf off)"
+[[ ! -s "$RECV" ]] && pass "explicit console_liveness_relay=0 suppresses the relay even with a url (opt-out wins)" || fail "a POST happened despite console_liveness_relay=0"
+stop_stub
+
+# ─── 8. EXFIL DEFENSE: an UNTRUSTED (mode 644) default-path conf must NOT relay (trust gate) ─────
+# The cases above drive enablement through TELEMETRY_CONFIG_FILE, which is trusted BY DESIGN (an
+# explicit env override bypasses the mode-600 gate). This case exercises the actual supply-chain
+# defense end-to-end: a conf planted at the user-global default slot (<bundle-root>/…, reached via
+# the hermetic HOME set at the top) pointing at an attacker stub with console_liveness_relay=1, but
+# mode 644 — exactly what a non-operator drop (clone/tarball/local tool) can produce, since git can
+# only ship 644/755, never 600. relay.sh re-sources config.sh, whose telemetry_conf_trusted gate
+# (mode 600 + owner + not-a-symlink) rejects it, so no URL resolves and nothing is POSTed — while
+# the durable local write still happens. NO env flag, NO TELEMETRY_CONFIG_FILE, NO endpoint env:
+# the untrusted conf is the ONLY possible signal, so a POST here would be a real exfil regression.
+echo "--- 8. exfil defense: an untrusted (mode 644) <bundle-root> conf with an attacker url never relays ---"
+: > "$RECV"; start_stub ok
+ROOT_X="$TMPDIR_EVAL/x"
+mkdir -p "<bundle-root>"
+UNTRUSTED_CONF="<bundle-root>/telemetry-console.conf"
+printf 'console_telemetry_url=http://127.0.0.1:%s\nconsole_liveness_relay=1\n' "$PORT" > "$UNTRUSTED_CONF"
+chmod 644 "$UNTRUSTED_CONF"
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  unset TELEMETRY_CONFIG_FILE
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL
+  emit_event "$ROOT_X" '{"type":"claim","subjectId":"exfil-x","actor":"a","at":"t"}'
+)
+sleep 1
+[[ -s "$ROOT_X/liveness/events.jsonl" ]] && pass "local write happened (untrusted-conf case, local-first intact)" || fail "local write missing (untrusted conf)"
+[[ ! -s "$RECV" ]] && pass "an untrusted (644) default-path conf naming an attacker url NEVER relays (trust gate holds, no exfil)" || fail "EXFIL: a POST reached the attacker stub from an untrusted 644 conf"
+rm -f "$UNTRUSTED_CONF"
+stop_stub
+
 echo ""
 if [[ "$errors" -eq 0 ]]; then
   echo "test_liveness_console_relay: all checks passed."