@kontourai/flow-agents 3.2.0 → 3.3.0

package/evals/integration/test_ci_actor_identity.sh

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# test_ci_actor_identity.sh — CI-runtime actor identity tier (issue #398, extends #287; ADR 0021 §2).
+#
+# Proves a CI-triggered session gets a STABLE actor derived from the CI provider's published
+# run/job identifiers, sitting ABOVE process-ancestry and BELOW an explicit override / native
+# runtime session id in resolveActor()'s chain. The payoff: the #293 verify-hold gate now ENFORCES
+# for CI sessions (stable identity) instead of degrading to advisory — the root fix for the CI
+# false-block #293 had to work around.
+#
+# Part A — resolveActor() resolution (pure): stability + byte-identity, precedence (override /
+#   native runtime win), per-provider detection (GitHub, GitLab), conservative generic fallthrough,
+#   recognized-provider-missing-id fallthrough, and env-var injection sanitization.
+# Part B — verify-hold integration: a STABLE CI actor BLOCKS a differing assignment-backed holder
+#   (ENFORCE — contrast the ancestry/advisory case in test_verify_hold.sh §1d), and a CI actor's
+#   OWN claim is recognized as self and PASSES (the reconstruction-seam fix in resolveEnsureSessionActor).
+#
+# Deterministic, no model spend, self-cleaning, no network, no `gh` process anywhere.
+# Usage: bash evals/integration/test_ci_actor_identity.sh
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+WRITER="workflow-sidecar"
+ACTOR_IDENTITY_HELPER="$ROOT/scripts/hooks/lib/actor-identity.js"
+
+TMPDIR_EVAL="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_EVAL"' EXIT
+ARTIFACT_ROOT="$TMPDIR_EVAL/artifact-root"
+
+errors=0
+pass() { echo "  [PASS] $1"; }
+fail() { echo "  [FAIL] $1"; errors=$((errors + 1)); }
+
+json_query() {
+  node -e 'const fs=require("fs"); let cur=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); for (const part of process.argv[2].split(".")) cur=part==="length" ? cur.length : (Array.isArray(cur) ? cur[Number(part)] : cur[part]); console.log(cur);' "$1" "$2"
+}
+
+# resolve_field <field:actor|source> <env-assignments...> — run resolveActor under a CLEAN env
+# (only the passed assignments + HOME) so no ambient FLOW_AGENTS_ACTOR/CLAUDE_CODE_SESSION_ID from
+# the eval host leaks into the resolution. Prints the requested field.
+resolve_field() {
+  local field="$1"; shift
+  # env -i gives a CLEAN slate (no ambient FLOW_AGENTS_ACTOR / CLAUDE_CODE_SESSION_ID / real
+  # GITHUB_* from the CI host leaking in); PATH is preserved so `node` resolves.
+  env -i HOME="$HOME" PATH="$PATH" "$@" node -e '
+const { resolveActor } = require(process.argv[1]);
+const r = resolveActor(process.env);
+process.stdout.write(process.argv[2] === "source" ? r.source : r.actor);
+' "$ACTOR_IDENTITY_HELPER" "$field"
+}
+
+# verify_hold_under_ci <dir> <KEY=VAL...> — run verify-hold with a CONTROLLED CI identity.
+# flow_agents_node is a bash FUNCTION (from node.sh), so it cannot be launched via `env -i`; instead
+# run in a subshell that unsets every identity source that would out-rank the CI tier (an explicit
+# override or a native runtime session id — including the eval host's own, since this suite itself
+# runs under a coding agent) and exports the provided CI vars. When this suite runs in real GitHub
+# Actions, the exported fake ids override the ambient real ones so the assertions stay deterministic.
+verify_hold_under_ci() {
+  local dir="$1"; shift
+  (
+    unset FLOW_AGENTS_ACTOR CLAUDE_CODE_SESSION_ID CODEX_SESSION_ID OPENCODE_SESSION_ID PI_SESSION_ID CLAUDECODE
+    while [[ $# -gt 0 ]]; do export "${1?}"; shift; done
+    flow_agents_node "$WRITER" verify-hold "$dir"
+  )
+}
+
+# append_liveness_event / write_assignment_record — the proven fixture writers from
+# test_verify_hold.sh (kept byte-identical in shape so the join fixtures behave the same).
+append_liveness_event() {
+  local root="$1" subject="$2" actor="$3" at="$4" ttl="${5:-1800}"
+  mkdir -p "$root/liveness"
+  node -e '
+const fs = require("fs");
+const evt = { type: "claim", subjectId: process.argv[1], actor: process.argv[2], at: process.argv[3], ttlSeconds: Number(process.argv[4]) };
+fs.appendFileSync(process.argv[5], JSON.stringify(evt) + "\n");
+' "$subject" "$actor" "$at" "$ttl" "$root/liveness/events.jsonl"
+}
+
+write_assignment_record() {
+  local root="$1" slug="$2" sessionId="$3" actorKey="$4"
+  mkdir -p "$root/assignment"
+  node -e '
+const fs = require("fs");
+const [dest, slug, sessionId, actorKey] = process.argv.slice(1);
+const now = new Date().toISOString();
+const actor = { runtime: "github-actions", session_id: sessionId, host: "eval-host" };
+const rec = {
+  schema_version: "1.0", role: "AssignmentClaimRecord", subject_id: slug,
+  actor, actor_key: actorKey, claimed_at: now, ttl_seconds: 1800, branch: "main",
+  artifact_dir: slug, status: "claimed",
+  audit_trail: [{ at: now, transition: "claim", from_actor: null, to_actor: actor, reason: "claim" }],
+};
+fs.writeFileSync(dest, JSON.stringify(rec, null, 2));
+' "$root/assignment/$slug.json" "$slug" "$sessionId" "$actorKey"
+}
+
+# GitHub Actions env used across the file (a single job's stable identifiers).
+GHA=(GITHUB_ACTIONS=true GITHUB_RUN_ID=555 GITHUB_RUN_ATTEMPT=1 GITHUB_JOB=deliver)
+
+echo "=== CI actor identity (#398) ==="
+
+# ─── Part A: resolveActor() resolution ───────────────────────────────────────────────────────
+echo "--- A1. GitHub Actions -> stable ci-runtime actor, byte-identical across invocations ---"
+GH_SRC="$(resolve_field source "${GHA[@]}")"
+GH_ACTOR_1="$(resolve_field actor "${GHA[@]}")"
+GH_ACTOR_2="$(resolve_field actor "${GHA[@]}")"
+[[ "$GH_SRC" == "ci-runtime:github-actions" ]] && pass "source is ci-runtime:github-actions" || fail "source was not ci-runtime:github-actions: '$GH_SRC'"
+[[ "$GH_ACTOR_1" == github-actions:555-1-deliver:* ]] && pass "actor is github-actions:<run>-<attempt>-<job>:<host> ('$GH_ACTOR_1')" || fail "actor shape unexpected: '$GH_ACTOR_1'"
+[[ "$GH_ACTOR_1" == "$GH_ACTOR_2" ]] && pass "actor is byte-identical across repeated invocations (stable)" || fail "actor differed across invocations: '$GH_ACTOR_1' vs '$GH_ACTOR_2'"
+
+echo "--- A2. precedence: explicit override and native runtime session id both WIN over CI ---"
+OVR_SRC="$(resolve_field source "${GHA[@]}" FLOW_AGENTS_ACTOR=alice)"
+[[ "$OVR_SRC" == "explicit-override" ]] && pass "FLOW_AGENTS_ACTOR under CI still resolves explicit-override (CI does not win)" || fail "override did not win under CI: '$OVR_SRC'"
+NATIVE_SRC="$(resolve_field source "${GHA[@]}" CLAUDE_CODE_SESSION_ID=sess-xyz)"
+[[ "$NATIVE_SRC" == runtime-session-id:* ]] && pass "native runtime session id under CI still resolves runtime-session-id (CI does not win)" || fail "native runtime id did not win under CI: '$NATIVE_SRC'"
+
+echo "--- A3. GitLab CI -> stable gitlab-ci actor from CI_JOB_ID ---"
+GL_SRC="$(resolve_field source GITLAB_CI=true CI_JOB_ID=9988)"
+GL_ACTOR="$(resolve_field actor GITLAB_CI=true CI_JOB_ID=9988)"
+[[ "$GL_SRC" == "ci-runtime:gitlab-ci" ]] && pass "source is ci-runtime:gitlab-ci" || fail "source was not ci-runtime:gitlab-ci: '$GL_SRC'"
+[[ "$GL_ACTOR" == gitlab-ci:9988:* ]] && pass "actor is gitlab-ci:<job-id>:<host> ('$GL_ACTOR')" || fail "gitlab actor shape unexpected: '$GL_ACTOR'"
+
+echo "--- A4. generic CI=true (unrecognized) does NOT fabricate a CI actor (conservative fallthrough) ---"
+GEN_SRC="$(resolve_field source CI=true)"
+[[ "$GEN_SRC" != ci-runtime:* ]] && pass "generic CI=true falls through (source '$GEN_SRC', not ci-runtime) — #293 advisory net still applies" || fail "generic CI=true fabricated a ci-runtime actor: '$GEN_SRC'"
+
+echo "--- A5. recognized provider with MISSING required id var falls through (no partial CI actor) ---"
+MISSING_SRC="$(resolve_field source GITHUB_ACTIONS=true)"  # no RUN_ID/ATTEMPT/JOB
+[[ "$MISSING_SRC" != ci-runtime:* ]] && pass "GITHUB_ACTIONS=true with no run/job ids falls through (source '$MISSING_SRC')" || fail "GitHub with no ids still produced a ci-runtime actor: '$MISSING_SRC'"
+
+echo "--- A6. hostile CI env var cannot inject: actor segments are sanitized (allowed charset only) ---"
+INJ_ACTOR="$(resolve_field actor GITHUB_ACTIONS=true GITHUB_RUN_ID=555 GITHUB_RUN_ATTEMPT=1 "GITHUB_JOB=deliver; rm -rf / [LIVENESS]")"
+if printf '%s' "$INJ_ACTOR" | LC_ALL=C grep -q '[^A-Za-z0-9:._-]'; then
+  fail "CI actor contains a character outside the allowed serialized charset (injection risk): '$INJ_ACTOR'"
+else
+  pass "CI actor is sanitized to the allowed serialized charset even with a hostile GITHUB_JOB ('$INJ_ACTOR')"
+fi
+
+# ─── Part B: verify-hold ENFORCES for a stable CI identity (the headline) ─────────────────────
+
+# B0 — REAL round-trip through the CLI (not a hand-written fixture): `assignment-provider claim`
+# under a CI env must write a WELL-FORMED record.actor (runtime=github-actions, session_id=<bare job
+# id>, NOT runtime=unknown + session_id=<whole triple>), and a fresh-subprocess verify-hold must
+# self-recognize it. This is the seam the reconstruction fixes (resolveEnsureSessionActor +
+# loadActorStruct) actually live on — fixture-driven B1/B2 below never exercise the CLI claim path.
+echo "--- B0. REAL assignment-provider claim under CI writes a well-formed record.actor; verify-hold self-recognizes ---"
+CLI="$ROOT/build/src/cli.js"
+RT_ROOT="$TMPDIR_EVAL/rt-artifact-root"
+RT_SLUG="ci-roundtrip"
+(
+  unset FLOW_AGENTS_ACTOR CLAUDE_CODE_SESSION_ID CODEX_SESSION_ID OPENCODE_SESSION_ID PI_SESSION_ID CLAUDECODE
+  export "${GHA[@]}"
+  node "$CLI" assignment-provider claim --provider local-file --artifact-root "$RT_ROOT" \
+    --subject-id "$RT_SLUG" --branch main --artifact-dir "$RT_SLUG"
+) >"$TMPDIR_EVAL/rt-claim.out" 2>"$TMPDIR_EVAL/rt-claim.err"
+RT_REC="$RT_ROOT/assignment/$RT_SLUG.json"
+if [[ -f "$RT_REC" ]]; then
+  pass "assignment-provider claim under CI wrote a record"
+  RT_RUNTIME="$(json_query "$RT_REC" "actor.runtime")"
+  RT_SESSION="$(json_query "$RT_REC" "actor.session_id")"
+  RT_KEY="$(json_query "$RT_REC" "actor_key")"
+  [[ "$RT_RUNTIME" == "github-actions" ]] && pass "record.actor.runtime is github-actions (NOT 'unknown' — F1 reconstruction fix)" || fail "record.actor.runtime was '$RT_RUNTIME', expected github-actions (F1 regressed: loadActorStruct not CI-aware)"
+  [[ "$RT_SESSION" == "555-1-deliver" ]] && pass "record.actor.session_id is the bare CI job id 555-1-deliver (NOT the whole triple — F1 fix)" || fail "record.actor.session_id was '$RT_SESSION', expected 555-1-deliver (F1 regressed)"
+  [[ "$RT_KEY" == github-actions:555-1-deliver:* ]] && pass "record.actor_key is the canonical CI key ('$RT_KEY')" || fail "record.actor_key was '$RT_KEY', expected github-actions:555-1-deliver:<host>"
+else
+  fail "assignment-provider claim under CI wrote NO record: $(cat "$TMPDIR_EVAL/rt-claim.out" "$TMPDIR_EVAL/rt-claim.err")"
+fi
+# Fresh-subprocess verify-hold under the same CI env → the actor written by the real claim is self.
+mkdir -p "$RT_ROOT/$RT_SLUG"
+if verify_hold_under_ci "$RT_ROOT/$RT_SLUG" "${GHA[@]}" >"$TMPDIR_EVAL/rt-vh.out" 2>"$TMPDIR_EVAL/rt-vh.err"; then
+  pass "verify-hold self-recognizes the CI actor from a REAL claim across subprocesses (end-to-end seam)"
+else
+  fail "verify-hold FALSE-BLOCKED the CI actor's own real claim across subprocesses: $(cat "$TMPDIR_EVAL/rt-vh.out" "$TMPDIR_EVAL/rt-vh.err")"
+fi
+[[ "$(json_query "$TMPDIR_EVAL/rt-vh.out" "reason")" == "self_is_holder" ]] && pass "real-round-trip verify-hold reason is self_is_holder" || fail "real-round-trip verify-hold reason was not self_is_holder: $(cat "$TMPDIR_EVAL/rt-vh.out")"
+
+echo "--- B1. a stable CI actor BLOCKS a differing, assignment-backed holder (ENFORCE, not advisory) ---"
+BLOCK_SLUG="ci-verify-hold-block"
+BLOCK_DIR="$ARTIFACT_ROOT/$BLOCK_SLUG"
+mkdir -p "$BLOCK_DIR"
+# Held (fresh) by a clearly different actor -> a durable, assignment-backed conflict.
+write_assignment_record "$ARTIFACT_ROOT" "$BLOCK_SLUG" "other-session" "eval-actor-ci-other-holder"
+append_liveness_event "$ARTIFACT_ROOT" "$BLOCK_SLUG" "eval-actor-ci-other-holder" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" 1800
+# Current actor: a STABLE CI identity (GitHub env), NO FLOW_AGENTS_ACTOR — before #398 this would
+# have fallen to ancestry (unstable) and the gate would have degraded to advisory/PASS.
+if verify_hold_under_ci "$BLOCK_DIR" "${GHA[@]}" >"$TMPDIR_EVAL/ci-block.out" 2>"$TMPDIR_EVAL/ci-block.err"; then
+  fail "verify-hold under a stable CI identity should BLOCK a differing assignment-backed holder (ENFORCE) — got exit 0: $(cat "$TMPDIR_EVAL/ci-block.out" "$TMPDIR_EVAL/ci-block.err")"
+else
+  pass "verify-hold under a stable CI identity BLOCKS a differing assignment-backed holder (the #398 enforce payoff)"
+fi
+[[ "$(json_query "$TMPDIR_EVAL/ci-block.out" "ok")" == "false" ]] && pass "CI-block verify-hold JSON reports ok:false" || fail "CI-block verify-hold JSON did not report ok:false: $(cat "$TMPDIR_EVAL/ci-block.out")"
+CI_BLOCK_REASON="$(json_query "$TMPDIR_EVAL/ci-block.out" "reason")"
+[[ "$CI_BLOCK_REASON" != "actor-identity-unstable-advisory-only" ]] && pass "CI-block reason is NOT the unstable-advisory degradation ('$CI_BLOCK_REASON') — the gate genuinely enforces" || fail "CI actor still degraded to advisory (reason=$CI_BLOCK_REASON) — #398 did not make the CI identity stable"
+
+echo "--- B2. a CI actor's OWN claim is recognized as self and PASSES (the reconstruction-seam fix) ---"
+SELF_SLUG="ci-verify-hold-self"
+SELF_DIR="$ARTIFACT_ROOT/$SELF_SLUG"
+mkdir -p "$SELF_DIR"
+# The holder's actor_key IS the CI actor resolveActor() produces under the GitHub env — so the
+# claim written in one CI step is recognized as self at publish in a later step. If the
+# resolveEnsureSessionActor reconstruction diverged (rebuilt an ancestry struct), this would
+# FALSE-BLOCK — exactly the bug #398 removes.
+write_assignment_record "$ARTIFACT_ROOT" "$SELF_SLUG" "self-session" "$GH_ACTOR_1"
+if verify_hold_under_ci "$SELF_DIR" "${GHA[@]}" >"$TMPDIR_EVAL/ci-self.out" 2>"$TMPDIR_EVAL/ci-self.err"; then
+  pass "verify-hold PASSES when the CI actor is the holder (self recognized across subprocesses — seam fix)"
+else
+  fail "verify-hold FALSE-BLOCKED a CI actor on its OWN claim (the reconstruction seam regressed): $(cat "$TMPDIR_EVAL/ci-self.out" "$TMPDIR_EVAL/ci-self.err")"
+fi
+[[ "$(json_query "$TMPDIR_EVAL/ci-self.out" "ok")" == "true" ]] && pass "CI-self verify-hold JSON reports ok:true" || fail "CI-self verify-hold JSON did not report ok:true: $(cat "$TMPDIR_EVAL/ci-self.out")"
+[[ "$(json_query "$TMPDIR_EVAL/ci-self.out" "reason")" == "self_is_holder" ]] && pass "CI-self verify-hold reason is self_is_holder (the CI actor matched the stored actor_key)" || fail "CI-self verify-hold reason was not self_is_holder: $(cat "$TMPDIR_EVAL/ci-self.out")"
+
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "ALL CI ACTOR IDENTITY CHECKS PASSED"
+  exit 0
+else
+  echo "$errors CHECK(S) FAILED"
+  exit 1
+fi

package/evals/integration/test_fixture_retirement_audit.sh

@@ -21,9 +21,9 @@ json_query() {
   node -e 'const fs=require("fs"); let cur=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); for (const part of process.argv[2].split(".")) cur=Array.isArray(cur) ? cur[Number(part)] : cur[part]; console.log(cur);' "$1" "$2"
 }
 
-[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.scanned")" == "15" ]] && pass "audit scans all fixture groups" || fail "audit scans all fixture groups"
+[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.scanned")" == "16" ]] && pass "audit scans all fixture groups" || fail "audit scans all fixture groups"
 [[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.retire_candidates")" == "0" ]] && pass "audit finds no unowned retire candidates" || fail "audit finds no unowned retire candidates"
-[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.kept")" == "15" ]] && pass "audit keeps all owned fixture groups" || fail "audit keeps all owned fixture groups"
+[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.kept")" == "16" ]] && pass "audit keeps all owned fixture groups" || fail "audit keeps all owned fixture groups"
 
 node - "$TMPDIR_EVAL/audit.json" <<'NODE'
 const fs = require("node:fs");

package/evals/integration/test_publish_delivery.sh

@@ -9,6 +9,9 @@
 #   4. RECONCILE-MATCHING: delivery trust.bundle (+ matching-sha checkpoint sibling) + CI
 #      pass -> exit 0.
 #   5. FAIL-SOFT: no trust.bundle -> publishDelivery skips, record-release exits 0.
+#   6. AC6 SHAPE-INVALID-REFUSED (#356): a shape-invalid trust.bundle (test_output claim
+#      naming a non-manifest command) is REFUSED by publishDelivery() -- non-zero exit, loud
+#      message, nothing copied to delivery/. Distinct from FAIL-SOFT (bundle absent).
 #
 # Deterministic, no model spend, self-cleaning.
 # Usage: bash evals/integration/test_publish_delivery.sh
@@ -118,7 +121,14 @@ FIXTURE1="$TMP/fixture1.json"
 write_bundle_to "$FIXTURE1" "node --version" "true"
 setup_session "$AROOT1" "$SLUG1" "$FIXTURE1"
 
-rr_out1=$(flow_agents_node "$WRITER" record-release "$SESSION_DIR1" \
+# #356: the fixture bundle's evidence.execution.label is "node --version" (a real,
+# deterministic command, not a manifest-registered one in this scratch repo) — the new
+# reconcile-preflight gate inside publishDelivery() resolves the manifest the SAME way
+# trust-reconcile.js itself does, whose legacy fallback tier folds TRUST_RECONCILE_COMMANDS
+# into the manifest. Setting it here makes this fixture genuinely shape-valid (a
+# manifest-matched command claim), matching what CI would actually accept for a repo whose
+# canonical verify is "node --version" — not a preflight-specific carve-out.
+rr_out1=$(TRUST_RECONCILE_COMMANDS="node --version" flow_agents_node "$WRITER" record-release "$SESSION_DIR1" \
   --decision merge \
   --gate-json '{"name":"merge","status":"pass","summary":"Ready."}' \
   --summary "Release." --repo-root "$REPO1" \
@@ -168,7 +178,9 @@ FIXTURE2="$TMP/fixture2.json"
 write_bundle_to "$FIXTURE2" "node --version" "true"
 setup_session "$AROOT2" "$SLUG2" "$FIXTURE2"
 
-pd_out=$(flow_agents_node "$WRITER" publish-delivery "$SESSION_DIR2" \
+# #356: same rationale as TEST 1 above — make the fixture genuinely shape-valid for the
+# new reconcile-preflight gate inside publishDelivery().
+pd_out=$(TRUST_RECONCILE_COMMANDS="node --version" flow_agents_node "$WRITER" publish-delivery "$SESSION_DIR2" \
   --repo-root "$REPO2" 2>&1)
 pd_exit=$?
 
@@ -282,6 +294,51 @@ else
   _fail "FAIL-SOFT: delivery/trust.bundle was created unexpectedly"
 fi
 
+# ==== TEST 6: AC6 SHAPE-INVALID-REFUSED (#356) ======================
+# publishDelivery() now runs the reconcile-preflight shape check BEFORE copying anything
+# into delivery/ (#356 Wave 3, AC6). A bundle whose test_output-evidenced claim names a
+# command that is not in the resolved manifest (no TRUST_RECONCILE_COMMANDS/run-baseline.sh
+# entry naming it here) is shape-invalid and must be REFUSED: publish-delivery exits
+# non-zero, loudly, and nothing is copied to delivery/. This must never be confused with the
+# FAIL-SOFT (bundle-absent) case above, which stays a soft, exit-0 no-op.
+echo ""
+echo "=== TEST 6: AC6 SHAPE-INVALID-REFUSED ==="
+
+REPO6="$TMP/repo6"
+AROOT6="$REPO6/.flow-agents"
+SLUG6="pd-shape-invalid-test"
+SESSION_DIR6="$AROOT6/$SLUG6"
+mkdir -p "$REPO6/kits"
+
+FIXTURE6="$TMP/fixture6.json"
+write_bundle_to "$FIXTURE6" "node --version" "true"
+setup_session "$AROOT6" "$SLUG6" "$FIXTURE6"
+
+# Deliberately NO TRUST_RECONCILE_COMMANDS env var here — "node --version" resolves to no
+# manifest entry in this scratch repo (no run-baseline.sh/package.json manifest source
+# either), so the bundle is shape-invalid (not-run: command not in the reconcile manifest).
+shape_out=$(flow_agents_node "$WRITER" publish-delivery "$SESSION_DIR6"   --repo-root "$REPO6" 2>&1)
+shape_exit=$?
+
+if [[ $shape_exit -ne 0 ]]; then
+  _pass "AC6 SHAPE-INVALID-REFUSED: publish-delivery exits non-zero for a shape-invalid bundle"
+else
+  _fail "AC6 SHAPE-INVALID-REFUSED: expected non-zero exit, got 0 -- $shape_out"
+fi
+
+if echo "$shape_out" | grep -q "REFUSING to publish"; then
+  _pass "AC6 SHAPE-INVALID-REFUSED: output names the refusal loudly (REFUSING to publish)"
+else
+  _fail "AC6 SHAPE-INVALID-REFUSED: expected a loud REFUSING to publish message, got: $shape_out"
+fi
+
+DELIVERY_BUNDLE6="$REPO6/delivery/$SLUG6/trust.bundle"
+if [[ ! -f "$DELIVERY_BUNDLE6" ]]; then
+  _pass "AC6 SHAPE-INVALID-REFUSED: delivery/$SLUG6/trust.bundle NOT created for a shape-invalid bundle"
+else
+  _fail "AC6 SHAPE-INVALID-REFUSED: delivery/$SLUG6/trust.bundle was created despite invalid shape"
+fi
+
 # ---- Summary ----
 echo ""
 echo "----------------------------------------------"

package/evals/integration/test_reconcile_preflight.sh

@@ -0,0 +1,304 @@
+#!/usr/bin/env bash
+# test_reconcile_preflight.sh — #356 (Local Reconcile-Shape Preflight) proof.
+#
+# Proves `workflow-sidecar reconcile-preflight <artifact-dir>` catches every documented
+# ADR-0020-invalid trust.bundle shape LOCALLY, before git push — reusing (never forking)
+# scripts/lib/reconcile-shape.js's own classification (the same module
+# scripts/ci/trust-reconcile.js requires), so the local check can never silently drift from
+# what CI enforces. Mirrors evals/integration/test_trust_reconcile_negatives.sh's
+# fixture-per-case + run_case() helper shape.
+#
+#   1. non-manifest command-backed claim (reuses trust-reconcile-exploits/no-label-bypass.json)
+#      → not-run divergence + fix hint to name the exact manifest command.
+#   2. unwaived assumed claim (reuses trust-reconcile-exploits/skip-assumed-bypass.json)
+#      → unwaived-assumed divergence + fix hint (also carries Q2's root-cause hint for shape 5).
+#   3. un-superseded disputed critique (new fixture: disputed-critique-unsuperseded.json)
+#      → session-local-failed divergence (a workflow.critique.review claim, no superseded_by).
+#   4. standalone fail/disputed session-local claim, non-critique (#292/#384 variant; new
+#      fixture: standalone-disputed-session-local.json) → the SAME session-local-failed
+#      divergence type as case 3, proving a disjoint pre-existing failure can never be
+#      smuggled in as a standalone claim either way.
+#   5. waiver-voided-by-mixed-call — reproduced via the REAL producer CLI (record-evidence),
+#      not a hand-built fixture. Confirms the actual current behavior: the command-backed-
+#      waiver guard at src/cli/workflow-sidecar.ts's recordEvidence() dies at RECORD time
+#      when --accepted-gap-reason/--waived-by is combined with ANY command-backed check in
+#      the same call (even alongside other, session-local checks in the same --check-json
+#      set) — so there is no "silently voided" bundle to reconcile in this repo's current
+#      producer; this is documented, correct, prevention-at-the-source, not a preflight gap.
+#   6. dropped waiver metadata round-trip (AC2) — a regression PROOF, not a preflight
+#      detection: record-evidence (waiver on a session-local check) → record-critique
+#      (rebuilds via checksFromBundle) → the bundle's claim STILL has metadata.waiver.
+#
+# Plus: CLEAN-BUNDLE (AC4, reuses trust-reconcile-mixed-bundle/mixed-bundle.json) → exit 0,
+# no issues. AC5 (local/fast, no CI spawn): a --manifest override naming a sentinel-writing
+# command is never invoked by the preflight on the clean bundle.
+#
+# Deterministic, no model spend, self-cleaning.
+# Usage: bash evals/integration/test_reconcile_preflight.sh
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+WRITER="workflow-sidecar"
+FX_EXPLOITS="$ROOT/evals/fixtures/trust-reconcile-exploits"
+FX_PREFLIGHT="$ROOT/evals/fixtures/reconcile-preflight"
+MIXED_BUNDLE="$ROOT/evals/fixtures/trust-reconcile-mixed-bundle/mixed-bundle.json"
+
+TMP="$(mktemp -d)"
+errors=0
+
+_pass() { echo "  PASS: $1"; }
+_fail() { echo "  FAIL: $1"; errors=$((errors + 1)); }
+
+cleanup() { rm -rf "$TMP"; }
+trap cleanup EXIT
+
+# run_case <label> <bundle> <needle...>
+# Copies <bundle> into a fresh session dir as trust.bundle, runs reconcile-preflight, and
+# asserts: exit non-zero AND stdout/stderr contains EVERY needle passed after <bundle>.
+run_case() {
+  local label="$1" bundle="$2"
+  shift 2
+  echo "=== $label ==="
+  if [[ ! -f "$bundle" ]]; then _fail "$label: fixture not found at $bundle"; return; fi
+  local session="$TMP/case-$RANDOM$RANDOM"
+  mkdir -p "$session"
+  cp "$bundle" "$session/trust.bundle"
+  local out code
+  out="$(flow_agents_node "$WRITER" reconcile-preflight "$session" --repo-root "$ROOT" 2>&1)"
+  code=$?
+  if [[ $code -ne 0 ]]; then
+    _pass "$label: reconcile-preflight exits non-zero ($code)"
+  else
+    _fail "$label: expected non-zero exit, got 0 — output: $out"
+  fi
+  local needle
+  for needle in "$@"; do
+    if echo "$out" | grep -qF "$needle"; then
+      _pass "$label: output contains \"$needle\""
+    else
+      _fail "$label: expected \"$needle\" in output — output: $out"
+    fi
+  done
+}
+
+# ==== Case 1: non-manifest command-backed claim (reused fixture) ====================
+run_case "case 1: non-manifest command-backed claim" "$FX_EXPLOITS/no-label-bypass.json" \
+  "c-fabricated-test" \
+  "no manifest-matched execution.label" \
+  "FIX: fold this into a non-command summary"
+
+# ==== Case 2: unwaived assumed claim (reused fixture) ================================
+run_case "case 2: unwaived assumed claim" "$FX_EXPLOITS/skip-assumed-bypass.json" \
+  "c-skipped" \
+  "re-derived status 'assumed' but carries no waiver" \
+  "requires a documented waiver (--accepted-gap-reason/--waived-by)"
+
+# ==== Case 3: un-superseded disputed critique (new fixture) ==========================
+run_case "case 3: un-superseded disputed critique" "$FX_PREFLIGHT/disputed-critique-unsuperseded.json" \
+  "c-disputed-critique" \
+  "workflow.critique.review" \
+  "has re-derived status 'disputed'" \
+  "FIX: a disputed/failing claim always blocks reconcile. Document a disjoint pre-existing failure as prose in a WAIVED non-command summary, not as a standalone claim."
+
+# ==== Case 4: standalone fail/disputed session-local claim, non-critique (#292/#384) =
+run_case "case 4: standalone disputed session-local claim (non-critique)" "$FX_PREFLIGHT/standalone-disputed-session-local.json" \
+  "c-standalone-disputed" \
+  "has re-derived status 'disputed'" \
+  "FIX: a disputed/failing claim always blocks reconcile. Document a disjoint pre-existing failure as prose in a WAIVED non-command summary, not as a standalone claim."
+
+# ==== Case 5: waiver-voided-by-mixed-call — REAL PRODUCER CLI reproduction ===========
+# Q2 resolution: shape #5 is NOT a distinct predicate — per the plan, confirm the ACTUAL
+# current behavior first. This repo's guard at record-evidence time (the command-backed-
+# waiver check ahead of any bundle write) dies loudly BEFORE a bundle is ever written when
+# --accepted-gap-reason/--waived-by is combined with a command-backed check in the same
+# call — including when a session-local check is ALSO present in the same call. That is the
+# correct prevention (fail at the source, not a silently-voided bundle downstream) — assert
+# the die message is clear and that no trust.bundle is produced.
+echo "=== case 5: waiver-voided-by-mixed-call (real producer CLI reproduction) ==="
+
+AROOT5="$TMP/repo5/.flow-agents"
+SLUG5="case5-mixed-call"
+SESSION_DIR5="$AROOT5/$SLUG5"
+mkdir -p "$TMP/repo5/kits" "$AROOT5"
+
+flow_agents_node "$WRITER" ensure-session --artifact-root "$AROOT5" --task-slug "$SLUG5" \
+  --title "Case 5" --summary "waiver-voided-by-mixed-call repro" --criterion "x" \
+  --timestamp "2026-07-04T10:00:00Z" >/dev/null 2>&1
+flow_agents_node "$WRITER" init-plan "$SESSION_DIR5/${SLUG5}--deliver.md" \
+  --source-request "t" --summary "t" --timestamp "2026-07-04T10:01:00Z" >/dev/null 2>&1
+
+# 5a. Single command-backed check + waiver flags in the SAME call → dies at record time.
+case5a_out="$(flow_agents_node "$WRITER" record-evidence "$SESSION_DIR5" --verdict pass \
+  --check-json '{"id":"cmdcheck","kind":"test","status":"pass","summary":"cmd ran","command":"npm run validate:source --"}' \
+  --accepted-gap-reason "load test env unavailable" --waived-by "brian" \
+  --timestamp "2026-07-04T10:02:00Z" 2>&1)"
+case5a_code=$?
+if [[ $case5a_code -ne 0 ]]; then
+  _pass "case 5a: record-evidence dies at RECORD time for a mixed waiver+command-backed call ($case5a_code)"
+else
+  _fail "case 5a: expected record-evidence to die (non-zero exit), got 0 — output: $case5a_out"
+fi
+if echo "$case5a_out" | grep -qF "cannot be applied to a command-backed check"; then
+  _pass "case 5a: die message clearly names the command-backed-waiver rejection"
+else
+  _fail "case 5a: expected the command-backed-waiver die message — output: $case5a_out"
+fi
+if [[ ! -f "$SESSION_DIR5/trust.bundle" ]]; then
+  _pass "case 5a: no trust.bundle written (dies BEFORE any bundle write — no silently-voided waiver bundle downstream)"
+else
+  _fail "case 5a: a trust.bundle was written despite the mixed-call guard firing"
+fi
+
+# 5b. TWO checks in the SAME call (one command-backed, one session-local) + waiver flags →
+#     the guard scans ALL checks in the call, so this ALSO dies at record time (proves the
+#     guard is not scoped only to a single-check call — the exact "mixed call" shape).
+case5b_out="$(flow_agents_node "$WRITER" record-evidence "$SESSION_DIR5" --verdict pass \
+  --check-json '{"id":"cmdcheck2","kind":"test","status":"pass","summary":"cmd ran","command":"npm run validate:source --"}' \
+  --check-json '{"id":"sessioncheck2","kind":"external","status":"skip","summary":"manual load test skip"}' \
+  --accepted-gap-reason "load test env unavailable" --waived-by "brian" \
+  --timestamp "2026-07-04T10:03:00Z" 2>&1)"
+case5b_code=$?
+if [[ $case5b_code -ne 0 ]]; then
+  _pass "case 5b: record-evidence ALSO dies for a two-check mixed call (command-backed + session-local, one waiver) ($case5b_code)"
+else
+  _fail "case 5b: expected record-evidence to die (non-zero exit), got 0 — output: $case5b_out"
+fi
+if echo "$case5b_out" | grep -qF "cannot be applied to a command-backed check"; then
+  _pass "case 5b: die message clearly names the command-backed-waiver rejection"
+else
+  _fail "case 5b: expected the command-backed-waiver die message — output: $case5b_out"
+fi
+if [[ ! -f "$SESSION_DIR5/trust.bundle" ]]; then
+  _pass "case 5b: no trust.bundle written"
+else
+  _fail "case 5b: a trust.bundle was written despite the mixed-call guard firing"
+fi
+
+# 5c. Sanity: the Q2 root-cause hint IS reachable via reconcile-preflight's message for an
+#     honest (non-mixed-call) unwaived-assumed divergence — i.e. an agent who DOES end up
+#     with an unwaived-assumed claim (by whatever path) gets pointed at the mixed-call guard
+#     as a likely root cause. Reuses case 2's fixture; restated here for traceability to
+#     shape #5 per Q2's resolution (shape #5 is #2 enriched with a root-cause hint, not a
+#     distinct predicate).
+Q2_SESSION="$TMP/q2-check"
+mkdir -p "$Q2_SESSION"
+cp "$FX_EXPLOITS/skip-assumed-bypass.json" "$Q2_SESSION/trust.bundle"
+q2_out="$(flow_agents_node "$WRITER" reconcile-preflight "$Q2_SESSION" --repo-root "$ROOT" 2>&1)"
+if echo "$q2_out" | grep -qF "voids/rejects the waiver"; then
+  _pass "case 5c (Q2 traceability): unwaived-assumed's preflight message carries the mixed-call root-cause hint"
+else
+  _fail "case 5c (Q2 traceability): expected the mixed-call root-cause hint on an unwaived-assumed divergence — output: $q2_out"
+fi
+
+# ==== Case 6 (AC2): dropped waiver metadata round-trip — regression PROOF, not detection ==
+echo "=== case 6 (AC2): waiver metadata round-trip survives record-critique rebuild ==="
+
+AROOT6="$TMP/repo6/.flow-agents"
+SLUG6="case6-waiver-roundtrip"
+SESSION_DIR6="$AROOT6/$SLUG6"
+mkdir -p "$TMP/repo6/kits" "$AROOT6"
+
+flow_agents_node "$WRITER" ensure-session --artifact-root "$AROOT6" --task-slug "$SLUG6" \
+  --title "Case 6" --summary "waiver round-trip repro" --criterion "x" \
+  --timestamp "2026-07-04T10:00:00Z" >/dev/null 2>&1
+flow_agents_node "$WRITER" init-plan "$SESSION_DIR6/${SLUG6}--deliver.md" \
+  --source-request "t" --summary "t" --timestamp "2026-07-04T10:01:00Z" >/dev/null 2>&1
+
+flow_agents_node "$WRITER" record-evidence "$SESSION_DIR6" --verdict pass \
+  --check-json '{"id":"loadtest","kind":"external","status":"skip","summary":"load test skip"}' \
+  --accepted-gap-reason "load test env unavailable" --waived-by "brian" \
+  --timestamp "2026-07-04T10:02:00Z" >/dev/null 2>&1
+
+flow_agents_node "$WRITER" record-critique "$SESSION_DIR6" --verdict pass --summary "ok." \
+  --timestamp "2026-07-04T10:03:00Z" >/dev/null 2>&1
+
+if [[ -f "$SESSION_DIR6/trust.bundle" ]]; then
+  _pass "case 6: trust.bundle exists after record-evidence -> record-critique rebuild"
+  bundle_json="$(cat "$SESSION_DIR6/trust.bundle")"
+  if echo "$bundle_json" | grep -qF '"waiver"'; then
+    _pass "case 6: rebuilt trust.bundle's claim STILL carries metadata.waiver (AC2 fix holds — pre-fix this silently dropped)"
+  else
+    _fail "case 6: rebuilt trust.bundle's claim LOST metadata.waiver — AC2 round-trip regressed. bundle: $bundle_json"
+  fi
+  if echo "$bundle_json" | grep -qF '"approved_by": "brian"'; then
+    _pass "case 6: waiver's approved_by ('brian') survives the rebuild"
+  else
+    _fail "case 6: expected waiver.approved_by 'brian' to survive the rebuild — bundle: $bundle_json"
+  fi
+else
+  _fail "case 6: trust.bundle was not found at $SESSION_DIR6/trust.bundle after the round-trip sequence"
+fi
+
+# Reconcile-preflight must ALSO pass cleanly on the rebuilt (waiver-intact) bundle —
+# an accepted-gap waiver on a session-local check is a shape-clean, WAIVED divergence-free
+# bundle by ADR 0020's own rules.
+preflight6_out="$(flow_agents_node "$WRITER" reconcile-preflight "$SESSION_DIR6" --repo-root "$ROOT" 2>&1)"
+preflight6_code=$?
+if [[ $preflight6_code -eq 0 ]]; then
+  _pass "case 6: reconcile-preflight exits 0 on the round-tripped, waiver-intact bundle"
+else
+  _fail "case 6: expected reconcile-preflight exit 0 on the round-tripped bundle, got $preflight6_code — output: $preflight6_out"
+fi
+
+# ==== CLEAN-BUNDLE (AC4) ==============================================================
+echo "=== CLEAN-BUNDLE (AC4): a valid ADR-0020-conformant bundle passes ==="
+
+CLEAN_SESSION="$TMP/clean-bundle"
+mkdir -p "$CLEAN_SESSION"
+cp "$MIXED_BUNDLE" "$CLEAN_SESSION/trust.bundle"
+
+clean_out="$(flow_agents_node "$WRITER" reconcile-preflight "$CLEAN_SESSION" --repo-root "$ROOT" 2>&1)"
+clean_code=$?
+if [[ $clean_code -eq 0 ]]; then
+  _pass "CLEAN-BUNDLE: reconcile-preflight exits 0 for a valid bundle"
+else
+  _fail "CLEAN-BUNDLE: expected exit 0, got $clean_code — output: $clean_out"
+fi
+if echo "$clean_out" | grep -qF "OK — no shape issues found"; then
+  _pass "CLEAN-BUNDLE: output reports no issues"
+else
+  _fail "CLEAN-BUNDLE: expected the no-issues OK line — output: $clean_out"
+fi
+
+# ==== AC5: preflight never spawns a manifest command =================================
+echo "=== AC5: reconcile-preflight never spawns a fresh manifest command ==="
+
+AC5_SESSION="$TMP/ac5-bundle"
+mkdir -p "$AC5_SESSION"
+cp "$MIXED_BUNDLE" "$AC5_SESSION/trust.bundle"
+SENTINEL="$TMP/ac5-sentinel-should-not-exist"
+rm -f "$SENTINEL"
+
+# --manifest override: the mixed bundle's real command ("npm run check:content-boundary --")
+# PLUS a second entry whose command WRITES a sentinel file if actually executed. Since
+# reconcile-preflight resolves the manifest (a pure, local, no-command-execution lookup) but
+# never calls runCommand/spawns a manifest entry's command to prove reconciliation, the
+# sentinel must never appear.
+AC5_MANIFEST='[{"id":"content-boundary","command":"npm run check:content-boundary --"},{"id":"sentinel","command":"touch '"$SENTINEL"'"}]'
+
+ac5_out="$(flow_agents_node "$WRITER" reconcile-preflight "$AC5_SESSION" --repo-root "$ROOT" --manifest "$AC5_MANIFEST" 2>&1)"
+ac5_code=$?
+if [[ $ac5_code -eq 0 ]]; then
+  _pass "AC5: reconcile-preflight exits 0 on the clean bundle with the sentinel manifest override"
+else
+  _fail "AC5: expected exit 0, got $ac5_code — output: $ac5_out"
+fi
+if [[ ! -f "$SENTINEL" ]]; then
+  _pass "AC5: sentinel file absent after the preflight run — no manifest command was spawned"
+else
+  _fail "AC5: sentinel file EXISTS — reconcile-preflight spawned a manifest command (AC5 violated)"
+fi
+
+# ---- Summary ----
+echo ""
+echo "----------------------------------------------"
+if [[ $errors -eq 0 ]]; then
+  echo "test_reconcile_preflight: all checks passed."
+  exit 0
+else
+  echo "test_reconcile_preflight: $errors check(s) failed."
+  exit 1
+fi