@kontourai/flow-agents 3.3.0 → 3.4.1

package/evals/integration/test_telemetry_usage_pipeline.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+# test_telemetry_usage_pipeline.sh — Layer 2: hermetic Stop-hook usage pipeline
+#
+# Proves the full telemetry.sh Stop path (add_stop_data_and_emit_usage) yields
+# a session.usage event with real tokens, a concrete (non-"unknown") model,
+# and a non-null estimated_cost_usd when a runtime transcript is supplied —
+# and that tokens still survive (with estimated_cost_usd null) when the
+# pricing registry is forced unavailable. Also guards the kiro-cli
+# non-regression case: with no transcript, model still resolves via the
+# existing usage_get_model() kiro lookup (unaffected by this fix).
+#
+# Uses the same TELEMETRY_DIR resolution convention as test_telemetry.sh
+# (prefers context/scripts/telemetry when present) so this exercises the same
+# copy CI actually runs, while explicitly pointing TELEMETRY_PRICING_FILE at
+# the canonical bundled registry so pricing resolves regardless of which copy
+# is under test (context/scripts/telemetry ships no bundled pricing.json).
+set -uo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+if [[ -d "$ROOT_DIR/context/scripts/telemetry" ]]; then
+  TELEMETRY_DIR="$ROOT_DIR/context/scripts/telemetry"
+else
+  TELEMETRY_DIR="$HOME/.flow-agents/context/scripts/telemetry"
+fi
+TELEMETRY_SH="${TELEMETRY_DIR}/telemetry.sh"
+PRICING_FILE="$ROOT_DIR/scripts/telemetry/pricing.json"
+FIXTURE_TRANSCRIPT="$ROOT_DIR/evals/fixtures/telemetry/usage-transcript-sample.jsonl"
+
+TMPDIR_EVAL=$(mktemp -d /tmp/eval-telemetry-usage-pipeline.XXXXXX)
+TMPLOG="${TMPDIR_EVAL}/test-output.jsonl"
+FAKE_HOME="${TMPDIR_EVAL}/home"
+mkdir -p "$FAKE_HOME" "$TMPDIR_EVAL/sessions"
+
+pass=0; fail=0
+_pass() { echo "  ✓ $1"; pass=$((pass + 1)); }
+_fail() { echo "  ✗ $1"; fail=$((fail + 1)); }
+
+echo "=== Layer 2: Telemetry Usage Pipeline (hermetic fixture) ==="
+echo ""
+
+if [[ ! -f "$TELEMETRY_SH" ]]; then
+  _fail "telemetry.sh not found at $TELEMETRY_SH"
+  echo "Cannot continue without telemetry script"
+  rm -rf "$TMPDIR_EVAL"
+  exit 1
+fi
+if [[ ! -f "$FIXTURE_TRANSCRIPT" ]]; then
+  _fail "fixture transcript not found at $FIXTURE_TRANSCRIPT"
+  rm -rf "$TMPDIR_EVAL"
+  exit 1
+fi
+
+# Wait for a new line to land in TMPLOG (telemetry.sh's Stop path emits
+# asynchronously even in foreground mode's background-adjacent callers).
+_wait_for_line() {
+  local before_lines="$1" i=0 current_lines
+  while [[ $i -lt 50 ]]; do
+    current_lines=$(wc -l < "$TMPLOG" 2>/dev/null | tr -d ' ')
+    [[ "${current_lines:-0}" -gt "$before_lines" ]] && break
+    sleep 0.1; i=$((i + 1))
+  done
+}
+
+_wait_for_file_line() {
+  local file="$1" i=0 current_lines
+  while [[ $i -lt 50 ]]; do
+    current_lines=$(wc -l < "$file" 2>/dev/null | tr -d ' ')
+    [[ "${current_lines:-0}" -gt 0 ]] && break
+    sleep 0.1; i=$((i + 1))
+  done
+}
+
+# Run a real Stop event against a freshly-established session (agentSpawn
+# first, matching real usage — Claude Code always sends SessionStart before
+# Stop). Returns the emitted session.usage event (jq-compact, one line).
+_run_stop() {
+  local input="$1"; shift
+  local extra_env_count="$#"
+  local extra_env=("$@")
+  local common_env=(
+    HOME="$FAKE_HOME"
+    TELEMETRY_ENABLED=true
+    TELEMETRY_CHANNELS=full
+    TELEMETRY_CHANNEL_FULL_LOG_FILE="$TMPLOG"
+    FLOW_AGENTS_TELEMETRY_FOREGROUND=true
+    TELEMETRY_CONFIG_FILE="$TMPDIR_EVAL/telemetry.conf"
+    TELEMETRY_DATA_DIR="$TMPDIR_EVAL"
+    TELEMETRY_SESSION_DIR="$TMPDIR_EVAL/sessions"
+  )
+
+  local before_lines
+  touch "$TMPLOG"
+  before_lines=$(wc -l < "$TMPLOG" | tr -d ' ')
+  echo '{"cwd":"/tmp"}' | env "${common_env[@]}" bash "$TELEMETRY_SH" agentSpawn dev >/dev/null 2>&1
+  _wait_for_line "$before_lines"
+
+  before_lines=$(wc -l < "$TMPLOG" | tr -d ' ')
+  if [[ "$extra_env_count" -gt 0 ]]; then
+    echo "$input" | env "${common_env[@]}" TELEMETRY_USAGE_TRACKING=true "${extra_env[@]}" \
+      bash "$TELEMETRY_SH" Stop dev 2>/dev/null
+  else
+    echo "$input" | env "${common_env[@]}" TELEMETRY_USAGE_TRACKING=true \
+      bash "$TELEMETRY_SH" Stop dev 2>/dev/null
+  fi
+  _wait_for_line "$before_lines"
+
+  tail -n +"$((before_lines + 1))" "$TMPLOG" 2>/dev/null | jq -c 'select(.event_type=="session.usage")' | tail -1
+}
+
+# --- 1. With transcript + pricing available: real tokens, cost, concrete model
+echo "--- Fixture transcript, pricing available ---"
+input1=$(jq -nc --arg tp "$FIXTURE_TRANSCRIPT" '{session_id:"pipeline-1",transcript_path:$tp,hook_event_name:"Stop"}')
+out1=$(_run_stop "$input1" TELEMETRY_PRICING_FILE="$PRICING_FILE")
+
+if [[ -n "$out1" ]]; then
+  model=$(echo "$out1" | jq -r '.usage.model')
+  it=$(echo "$out1" | jq -r '.usage.input_tokens')
+  ot=$(echo "$out1" | jq -r '.usage.output_tokens')
+  cost=$(echo "$out1" | jq -r '.usage.estimated_cost_usd')
+  by_model_len=$(echo "$out1" | jq -r '.usage.by_model | length')
+
+  [[ "$model" != "unknown" && "$model" != "null" && -n "$model" ]] && _pass "model is concrete (got: $model)" || _fail "model should not be unknown (got: $model)"
+  [[ "$model" == "claude-opus-4-8" ]] && _pass "model is the dominant-by-tokens model (claude-opus-4-8)" || _fail "expected dominant model claude-opus-4-8, got $model"
+  [[ "$it" != "null" && "$it" -gt 0 ]] && _pass "input_tokens is real and non-null (got: $it)" || _fail "input_tokens should be non-null/positive (got: $it)"
+  [[ "$ot" != "null" && "$ot" -gt 0 ]] && _pass "output_tokens is real and non-null (got: $ot)" || _fail "output_tokens should be non-null/positive (got: $ot)"
+  cost_positive=$(echo "$out1" | jq -r '(.usage.estimated_cost_usd // 0) > 0')
+  [[ "$cost" != "null" && "$cost_positive" == "true" ]] && _pass "estimated_cost_usd is real and non-null (got: $cost)" || _fail "estimated_cost_usd should be non-null/positive (got: $cost)"
+  [[ "$by_model_len" == "2" ]] && _pass "by_model has 2 entries" || _fail "expected 2 by_model entries, got $by_model_len"
+else
+  _fail "no session.usage event emitted for fixture transcript"
+fi
+
+# --- 1b. Economics attribution: canonical current pointer beats stale legacy
+echo ""
+echo "--- Economics attribution uses canonical current pointer ---"
+ATTR_CWD="${TMPDIR_EVAL}/workspace"
+CANON_SLUG="canonical-task"
+LEGACY_SLUG="legacy-task"
+ECON_LOG="${TMPDIR_EVAL}/economics.jsonl"
+mkdir -p "$ATTR_CWD/.kontourai/flow-agents/$CANON_SLUG" "$ATTR_CWD/.flow-agents/$LEGACY_SLUG"
+: > "$ECON_LOG"
+printf '%s\n' "{\"active_slug\":\"$CANON_SLUG\"}" > "$ATTR_CWD/.kontourai/flow-agents/current.json"
+printf '%s\n' "{\"active_slug\":\"$LEGACY_SLUG\"}" > "$ATTR_CWD/.flow-agents/current.json"
+printf '%s\n' '{"schema_version":"1.0","task_slug":"canonical-task","phase":"execution","verification_verdict":"PASS"}' > "$ATTR_CWD/.kontourai/flow-agents/$CANON_SLUG/state.json"
+printf '%s\n' '{"schema_version":"1.0","task_slug":"legacy-task","phase":"execution","verification_verdict":"PASS"}' > "$ATTR_CWD/.flow-agents/$LEGACY_SLUG/state.json"
+input_attr=$(jq -nc --arg tp "$FIXTURE_TRANSCRIPT" --arg cwd "$ATTR_CWD" '{session_id:"pipeline-attribution",transcript_path:$tp,hook_event_name:"Stop",cwd:$cwd}')
+TELEMETRY_SH_SAVED="$TELEMETRY_SH"
+TELEMETRY_SH="$ROOT_DIR/scripts/telemetry/telemetry.sh"
+out_attr=$(_run_stop "$input_attr" TELEMETRY_PRICING_FILE="$PRICING_FILE" TELEMETRY_ECONOMICS_LOG_FILE="$ECON_LOG")
+TELEMETRY_SH="$TELEMETRY_SH_SAVED"
+_wait_for_file_line "$ECON_LOG"
+
+if [[ -n "$out_attr" && -s "$ECON_LOG" ]]; then
+  attr_task=$(tail -1 "$ECON_LOG" | jq -r '.task_slug')
+  attr_phase=$(tail -1 "$ECON_LOG" | jq -r '.phases[0].phase')
+  [[ "$attr_task" == "$CANON_SLUG" ]] && _pass "economics record task_slug comes from canonical .kontourai current pointer" || _fail "expected canonical task_slug '$CANON_SLUG', got '$attr_task'"
+  [[ "$attr_phase" == "execution" ]] && _pass "economics record phase comes from canonical state.json" || _fail "expected canonical phase execution, got '$attr_phase'"
+else
+  _fail "economics attribution record was not emitted for canonical-current test"
+fi
+
+# --- 2. Pricing forced unavailable: tokens survive, cost is null ------------
+echo ""
+echo "--- Fixture transcript, pricing forced unavailable ---"
+input2=$(jq -nc --arg tp "$FIXTURE_TRANSCRIPT" '{session_id:"pipeline-2",transcript_path:$tp,hook_event_name:"Stop"}')
+out2=$(_run_stop "$input2" TELEMETRY_PRICING_FILE=/nonexistent/pricing.json TELEMETRY_PRICING_URL="" FLOW_AGENTS_PRICING_FILE="" FLOW_AGENTS_PRICING_URL="")
+
+if [[ -n "$out2" ]]; then
+  it2=$(echo "$out2" | jq -r '.usage.input_tokens')
+  ot2=$(echo "$out2" | jq -r '.usage.output_tokens')
+  cost2=$(echo "$out2" | jq -r '.usage.estimated_cost_usd')
+  pv2=$(echo "$out2" | jq -r '.usage.pricing_version')
+  model2=$(echo "$out2" | jq -r '.usage.model')
+
+  [[ "$it2" != "null" && "$it2" -gt 0 ]] && _pass "tokens survive when pricing unavailable (input_tokens=$it2)" || _fail "tokens should survive when pricing unavailable (got input_tokens=$it2)"
+  [[ "$ot2" != "null" && "$ot2" -gt 0 ]] && _pass "output_tokens survive when pricing unavailable (got: $ot2)" || _fail "output_tokens should survive when pricing unavailable (got: $ot2)"
+  [[ "$cost2" == "null" ]] && _pass "estimated_cost_usd is null when pricing unavailable (cost degrades, tokens don't)" || _fail "estimated_cost_usd should be null when pricing unavailable (got: $cost2)"
+  [[ "$pv2" == "null" ]] && _pass "pricing_version is null when pricing unavailable" || _fail "pricing_version should be null when pricing unavailable (got: $pv2)"
+  [[ "$model2" == "claude-opus-4-8" ]] && _pass "model still resolves from transcript when pricing unavailable" || _fail "expected model claude-opus-4-8, got $model2"
+else
+  _fail "no session.usage event emitted when pricing forced unavailable"
+fi
+
+# --- 3. No transcript (kiro-cli style): model still resolves via kiro fallback, no regression
+echo ""
+echo "--- No transcript (kiro-cli non-regression) ---"
+input3='{"session_id":"pipeline-3","hook_event_name":"Stop"}'
+out3=$(_run_stop "$input3")
+
+if [[ -n "$out3" ]]; then
+  model3=$(echo "$out3" | jq -r '.usage.model')
+  it3=$(echo "$out3" | jq -r '.usage.input_tokens')
+  by_model3=$(echo "$out3" | jq -r '.usage.by_model')
+
+  # FAKE_HOME has no ~/.kiro/agents spec, so usage_get_model's kiro lookup
+  # falls through to "unknown" — this is the pre-existing, unfixed kiro path
+  # and must be untouched by the transcript-model override (transcript_usage
+  # is null here, so model is never overridden).
+  [[ "$model3" == "unknown" ]] && _pass "no-transcript path still resolves via usage_get_model kiro fallback (unknown, no regression)" || _fail "expected kiro fallback 'unknown' with no transcript, got $model3"
+  [[ "$it3" == "null" ]] && _pass "input_tokens is null with no transcript (expected)" || _fail "expected null input_tokens with no transcript, got $it3"
+  [[ "$by_model3" == "null" ]] && _pass "by_model is null with no transcript (expected)" || _fail "expected null by_model with no transcript, got $by_model3"
+else
+  _fail "no session.usage event emitted for no-transcript case"
+fi
+
+# --- 4. Empty transcript + TELEMETRY_USAGE_DEBUG=1: debug reason is emitted -
+echo ""
+echo "--- Empty transcript, TELEMETRY_USAGE_DEBUG=1 (debug path) ---"
+EMPTY_TRANSCRIPT="${TMPDIR_EVAL}/empty-transcript.jsonl"
+: > "$EMPTY_TRANSCRIPT"
+DEBUG_DRIFT_LOG="${TMPDIR_EVAL}/debug-drift.log"
+input4=$(jq -nc --arg tp "$EMPTY_TRANSCRIPT" '{session_id:"pipeline-4",transcript_path:$tp,hook_event_name:"Stop"}')
+out4=$(_run_stop "$input4" TELEMETRY_USAGE_DEBUG=1 TELEMETRY_DRIFT_LOG="$DEBUG_DRIFT_LOG")
+
+if grep -q '\[telemetry\] usage_parse_transcript:' "$DEBUG_DRIFT_LOG" 2>/dev/null; then
+  _pass "debug reason line emitted for empty-transcript no-usage scenario"
+else
+  _fail "expected a usage_parse_transcript debug reason line in $DEBUG_DRIFT_LOG"
+fi
+
+model4=$(echo "$out4" | jq -r '.usage.model // "unknown"' 2>/dev/null)
+[[ -z "$out4" || "$model4" == "unknown" ]] && _pass "empty-transcript path emits no real usage (no regression)" || _fail "expected no/unknown usage for empty transcript, got model=$model4"
+
+rm -rf "$TMPDIR_EVAL"
+
+echo ""
+echo "Telemetry usage pipeline: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/evals/integration/test_trust_reconcile_negatives.sh

@@ -9,21 +9,23 @@
 #
 #   1. no-label-bypass       (finding 1) → not-run: a test_output claim with no
 #      manifest-matched execution.label is a divergence, never session-local.
-#   2. skip-assumed-bypass   (finding 2) → unwaived-assumed: 'assumed' alone is not a pass.
-#   3. status-misassertion   (finding 3) → status-misassertion: CI re-derives status; a
+#   2. mcp-degrade           (issue 492) → not-run: an MCP-shaped execution.label is not a
+#      manifest command and can never be RECONCILED as a CI-verified command check.
+#   3. skip-assumed-bypass   (finding 2) → unwaived-assumed: 'assumed' alone is not a pass.
+#   4. status-misassertion   (finding 3) → status-misassertion: CI re-derives status; a
 #      self-reported status that does not match the bundle's own evidence is rejected.
-#   4. waived-command-check  (finding 4) → waiver-on-command-check: a command-backed
+#   5. waived-command-check  (finding 4) → waiver-on-command-check: a command-backed
 #      (test_output) check cannot be waived.
-#   5. ws3-old-style-bundle  (AC6) → old all-test_output bundle FAILS the same way (exit 1,
+#   6. ws3-old-style-bundle  (AC6) → old all-test_output bundle FAILS the same way (exit 1,
 #      divergences) under the new reconciler as under the old one — no soundness regression.
-#   6. fabricated-attestation (iteration-4, converged iteration-3 finding, both gates) → a
+#   7. fabricated-attestation (iteration-4, converged iteration-3 finding, both gates) → a
 #      fully self-consistent, hand-fabricated no-command 'security' claim+evidence+event
 #      triple (indistinguishable from a genuine attestation at the reconciler's own
 #      re-derivation layer) MUST still pass (exit 0 — blocking attestations at L0 would break
 #      every honest human-attestation use) BUT MUST be loudly, distinctly marked
 #      'ATTESTED (not independently verifiable at L0)' plus the summary count line — never a
 #      quiet SESSION-LOCAL OK indistinguishable from a reconciled check. See ADR 0020 Residuals.
-#   7. delivery/DECLARED marker regressions (ADR 0022 §1/§2, section 7 below) — bundle-absent
+#   8. delivery/DECLARED marker regressions (ADR 0022 §1/§2, section 7 below) — bundle-absent
 #      fail-closed default, malformed/empty-array/missing-field diagnostics, and all four
 #      matchesScope() forms (ref:, commit: single + range, author:, branch-prefix:) including
 #      positive AND near-miss coverage, plus the compound (space-separated AND) scope form a
@@ -49,10 +51,12 @@ errors=0
 _pass() { echo "  PASS: $1"; }
 _fail() { echo "  FAIL: $1"; errors=$((errors + 1)); }
 
-# run_case <label> <bundle> <needle>
-# Asserts: reconciler exits non-zero AND stdout/stderr contains <needle>.
+# run_case <label> <bundle> <needle> [forbidden]
+# Asserts: reconciler exits non-zero, stdout/stderr contains <needle>, and optionally does
+# NOT contain <forbidden>.
 run_case() {
   local label="$1" bundle="$2" needle="$3"
+  local forbidden="${4:-}"
   echo "=== $label ==="
   if [[ ! -f "$bundle" ]]; then _fail "$label: fixture not found at $bundle"; return; fi
   local out code
@@ -69,25 +73,38 @@ run_case() {
   else
     _fail "$label: expected divergence \"$needle\" not found — output: $out"
   fi
+  if [[ -n "$forbidden" ]]; then
+    if echo "$out" | grep -qF "$forbidden"; then
+      _fail "$label: must NOT emit \"$forbidden\" — output: $out"
+    else
+      _pass "$label: does not emit \"$forbidden\""
+    fi
+  fi
 }
 
 # 1. Reviewer's no-label exploit → not-run (test_output must reconcile against the manifest).
 run_case "no-label-bypass (finding 1)" "$FX/no-label-bypass.json" \
   "no manifest-matched execution.label"
 
-# 2. Verifier's skip->assumed exploit → unwaived-assumed.
+# 2. Issue #492: MCP-shaped self-reported pass → not-run (not manifest-matched), never
+#    RECONCILED as a CI-verified command check.
+run_case "mcp-degrade (issue 492)" "$FX/mcp-degrade.json" \
+  "command is not in the reconcile manifest" \
+  "RECONCILED"
+
+# 3. Verifier's skip->assumed exploit → unwaived-assumed.
 run_case "skip-assumed-bypass (finding 2)" "$FX/skip-assumed-bypass.json" \
   "[unwaived-assumed]"
 
-# 3. Status-misassertion exploit → status re-derived CI-side; asserted != derived.
+# 4. Status-misassertion exploit → status re-derived CI-side; asserted != derived.
 run_case "status-misassertion (finding 3)" "$FX/status-misassertion.json" \
   "[status-misassertion]"
 
-# 4. Waived command-backed check → waiver-on-command-check.
+# 5. Waived command-backed check → waiver-on-command-check.
 run_case "waived-command-check (finding 4)" "$FX/waived-command-check.json" \
   "[waiver-on-command-check]"
 
-# 5. AC6 backward-compat regression: the real ws3-kit-dependencies-namespacing/trust.bundle
+# 6. AC6 backward-compat regression: the real ws3-kit-dependencies-namespacing/trust.bundle
 #    (an old-style all-test_output bundle whose commands are not manifest-matched) FAILS the
 #    same way under the new reconciler as under the old one — same FAIL verdict, divergences
 #    present, no silent pass introduced.
@@ -115,7 +132,7 @@ else
   fi
 fi
 
-# 6. Fabricated-attestation (iteration-4): passes (exit 0) but MUST carry the loud ATTESTED
+# 7. Fabricated-attestation (iteration-4): passes (exit 0) but MUST carry the loud ATTESTED
 #    marker and the summary count line — NOT the old quiet SESSION-LOCAL OK. This is a
 #    visibility assertion, not a divergence assertion (unlike run_case above): a fabricated
 #    self-consistent attestation bundle is, by construction, indistinguishable from a genuine

package/evals/integration/test_trust_reconcile_trailer_diagnostic.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# test_trust_reconcile_trailer_diagnostic.sh — Integration eval for scripts/ci/
+# trust-reconcile.js's runtime-session commit-trailer diagnostic (issue #305, ADR 0022 §1).
+#
+# Proves the diagnostic added in findRuntimeSessionTrailers()/logRuntimeSessionTrailers()
+# is audit-only:
+#   AC5  trailer-diagnostic-positive: a commit with a Claude-Session: trailer in the
+#        resolved range produces the exact line
+#        `[trust-reconcile] identified: runtime-session trailer 'Claude-Session' on <ref>`
+#        — the trailer KEY only, never the VALUE (session URL) — printed for the range's
+#        commit-with-trailer.
+#   AC6  trailer-diagnostic-negative: a commit range with no runtime-session trailer
+#        produces NO such diagnostic line, and the reconciler's exit code is IDENTICAL
+#        to the positive case (same canonical command, same bundle/DECLARED absence,
+#        differing only in trailer presence) — the diagnostic never changes the exit path.
+#   AC7  trailer-diagnostic-checkout-depth-verified: .github/workflows/trust-reconcile.yml
+#        already carries fetch-depth: 0 (no .yml edit needed for #305's depth ask).
+#   Base-ref-range vs narrower-fallback: both range-resolution paths
+#        (TRUST_RECONCILE_BASE_REF/GITHUB_BASE_REF resolvable vs unresolvable, falling back
+#        to just the head commit) are exercised directly against the exported
+#        findRuntimeSessionTrailers() helper (unit-style, no reconciler wrapper needed for
+#        this sub-case) as well as through the full reconciler CLI (integration-style).
+#
+# Eval-authoring hazards observed (per plan/goal constraints):
+#   - No self-recursive harness invocation: this eval shells out to trust-reconcile.js and
+#     to git only; it never invokes evals/run.sh or any other eval-suite entry point.
+#   - No legacy/deprecated-path literals: trailer fixture values are synthetic/generic
+#     (a https://claude.ai/code/session_test-fixture-only placeholder), never a copy of a
+#     real committed session URL or a legacy flat delivery/trust.bundle-style literal.
+#
+# Deterministic, no model spend, self-cleaning.
+# Usage: bash evals/integration/test_trust_reconcile_trailer_diagnostic.sh
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+RECONCILE="$ROOT/scripts/ci/trust-reconcile.js"
+
+errors=0
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+echo "=== trust-reconcile.js runtime-session trailer diagnostic — integration eval ==="
+
+# Synthetic-only trailer value — never a real/legacy committed session URL.
+TRAILER_VALUE="https://claude.ai/code/session_test-fixture-only"
+RECONCILE_CMD="node -e 'process.exit(0)'"
+
+# ─── Fixture: a real scratch git repo with two commits (base, then head) ─────────
+build_repo() {
+  local repo_dir="$1"
+  local with_trailer="$2"  # "true" or "false"
+  mkdir -p "$repo_dir"
+  git init -q "$repo_dir"
+  git -C "$repo_dir" config user.email "eval@local"
+  git -C "$repo_dir" config user.name "eval"
+  echo "base" > "$repo_dir/f.txt"
+  git -C "$repo_dir" add -A
+  git -C "$repo_dir" commit -qm "base commit"
+  echo "change" >> "$repo_dir/f.txt"
+  git -C "$repo_dir" add -A
+  if [[ "$with_trailer" == "true" ]]; then
+    git -C "$repo_dir" commit -qm "$(printf 'feat: trailer test commit\n\nClaude-Session: %s\n' "$TRAILER_VALUE")"
+  else
+    git -C "$repo_dir" commit -qm "feat: no-trailer test commit"
+  fi
+}
+
+POS_REPO="$TMP_DIR/positive-repo"
+NEG_REPO="$TMP_DIR/negative-repo"
+build_repo "$POS_REPO" "true"
+build_repo "$NEG_REPO" "false"
+
+POS_BASE="$(git -C "$POS_REPO" rev-list --max-parents=0 HEAD)"
+POS_HEAD="$(git -C "$POS_REPO" rev-parse HEAD)"
+NEG_BASE="$(git -C "$NEG_REPO" rev-list --max-parents=0 HEAD)"
+NEG_HEAD="$(git -C "$NEG_REPO" rev-parse HEAD)"
+
+# A THIRD repo where the range-distinguishing case actually differs from POS_REPO/NEG_REPO:
+# the trailer lives on a MIDDLE commit (between base and a later, trailer-free head commit)
+# -- reachable ONLY via the ranged `git log <base>..<head>` walk, never via the narrower
+# head-commit-only fallback. This is the genuine base-ref-range-vs-fallback distinguisher;
+# POS_REPO/NEG_REPO above (trailer-or-not on the head commit itself) would pass under
+# EITHER code path and do not by themselves prove the ranged branch is exercised.
+RANGE_REPO="$TMP_DIR/range-only-repo"
+mkdir -p "$RANGE_REPO"
+git init -q "$RANGE_REPO"
+git -C "$RANGE_REPO" config user.email "eval@local"
+git -C "$RANGE_REPO" config user.name "eval"
+echo "base" > "$RANGE_REPO/f.txt"
+git -C "$RANGE_REPO" add -A
+git -C "$RANGE_REPO" commit -qm "base commit"
+RANGE_BASE="$(git -C "$RANGE_REPO" rev-parse HEAD)"
+echo "middle" >> "$RANGE_REPO/f.txt"
+git -C "$RANGE_REPO" add -A
+git -C "$RANGE_REPO" commit -qm "$(printf 'feat: middle commit carries the trailer
+
+Claude-Session: %s
+' "$TRAILER_VALUE")"
+echo "head" >> "$RANGE_REPO/f.txt"
+git -C "$RANGE_REPO" add -A
+git -C "$RANGE_REPO" commit -qm "feat: head commit itself has no trailer"
+RANGE_HEAD="$(git -C "$RANGE_REPO" rev-parse HEAD)"
+
+# --- AC5: positive case — exact diagnostic line, key only, no value leak --------
+echo "--- AC5: positive — Claude-Session trailer present ---"
+pos_out="$(TRUST_RECONCILE_BASE_REF="$POS_BASE" TRUST_RECONCILE_SHA="$POS_HEAD" TRUST_RECONCILE_REF="test-branch" \
+  TRUST_RECONCILE_COMMANDS="$RECONCILE_CMD" node "$RECONCILE" --repo-root "$POS_REPO" 2>&1)"
+pos_code=$?
+
+if echo "$pos_out" | grep -qF "[trust-reconcile] identified: runtime-session trailer 'Claude-Session' on test-branch"; then
+  pass "AC5: exact diagnostic line printed for the Claude-Session trailer"
+else
+  fail "AC5: expected diagnostic line not found — output: $pos_out"
+fi
+
+if echo "$pos_out" | grep -qF "$TRAILER_VALUE"; then
+  fail "AC5: trailer VALUE ($TRAILER_VALUE) leaked into stdout — diagnostic must log the KEY only"
+else
+  pass "AC5: trailer VALUE does not appear anywhere in stdout (key-only logging, per ADR 0022 §1's exact quoted format)"
+fi
+
+# --- AC6: negative case — no trailer, no line, same canonical command/DECLARED state --
+echo "--- AC6: negative — no runtime-session trailer present ---"
+neg_out="$(TRUST_RECONCILE_BASE_REF="$NEG_BASE" TRUST_RECONCILE_SHA="$NEG_HEAD" TRUST_RECONCILE_REF="test-branch" \
+  TRUST_RECONCILE_COMMANDS="$RECONCILE_CMD" node "$RECONCILE" --repo-root "$NEG_REPO" 2>&1)"
+neg_code=$?
+
+if echo "$neg_out" | grep -q "identified: runtime-session trailer"; then
+  fail "AC6: an 'identified: runtime-session trailer' line was printed with no trailer present"
+else
+  pass "AC6: no 'identified: runtime-session trailer' line printed (no trailer present)"
+fi
+
+if [[ "$pos_code" == "$neg_code" ]]; then
+  pass "AC6: reconciler exit code is IDENTICAL between the trailer-present and no-trailer cases (both: $pos_code) — diagnostic never changes the exit path"
+else
+  fail "AC6: reconciler exit code DIVERGED between trailer-present ($pos_code) and no-trailer ($neg_code) cases — the diagnostic must never affect the exit path"
+fi
+
+# --- Base-ref-range vs narrower-fallback, exercised directly on the exported helper --
+# RANGE_REPO's trailer lives on a MIDDLE commit, absent from the head commit itself — this
+# genuinely distinguishes the two code paths (see RANGE_REPO fixture comment above).
+echo "--- base-ref-range vs narrower-fallback (direct helper exercise, genuinely distinguishing fixture) ---"
+range_result="$(TRUST_RECONCILE_BASE_REF="$RANGE_BASE" node -e "
+const { findRuntimeSessionTrailers } = require('$RECONCILE');
+const found = findRuntimeSessionTrailers('$RANGE_REPO', { sha: '$RANGE_HEAD', ref: 'test-branch' });
+console.log(JSON.stringify(found));
+" 2>&1)"
+if echo "$range_result" | grep -q '"trailerName":"Claude-Session"'; then
+  pass "base-ref-range path: findRuntimeSessionTrailers finds a trailer on a MIDDLE commit (base..head range) that is absent from the head commit itself, when TRUST_RECONCILE_BASE_REF resolves"
+else
+  fail "base-ref-range path: findRuntimeSessionTrailers did not find the middle-commit trailer via the ranged walk — output: $range_result"
+fi
+
+# Narrower fallback: no base ref env var set at all (helper's own internal base-ref
+# resolution reads process.env directly, so unset both env vars for this call) — against
+# the SAME range-only repo, this must NOT find the middle-commit trailer (it is invisible
+# to a head-commit-only scan), proving the fallback is genuinely narrower, not just an
+# equivalent restatement of the ranged path.
+fallback_result="$(env -u TRUST_RECONCILE_BASE_REF -u GITHUB_BASE_REF node -e "
+const { findRuntimeSessionTrailers } = require('$RECONCILE');
+const found = findRuntimeSessionTrailers('$RANGE_REPO', { sha: '$RANGE_HEAD', ref: 'test-branch' });
+console.log(JSON.stringify(found));
+" 2>&1)"
+if [[ "$fallback_result" == "[]" ]]; then
+  pass "narrower-fallback path: findRuntimeSessionTrailers does NOT find the middle-commit-only trailer when no base ref is resolvable (head-commit-only scan is genuinely narrower)"
+else
+  fail "narrower-fallback path: expected an empty array (middle-commit trailer invisible to head-only scan), got: $fallback_result"
+fi
+
+# Narrower fallback, positive: against POS_REPO (trailer ON the head commit itself), the
+# no-base-ref fallback still finds it — proving the fallback is not simply "always empty".
+fallback_pos_result="$(env -u TRUST_RECONCILE_BASE_REF -u GITHUB_BASE_REF node -e "
+const { findRuntimeSessionTrailers } = require('$RECONCILE');
+const found = findRuntimeSessionTrailers('$POS_REPO', { sha: '$POS_HEAD', ref: 'test-branch' });
+console.log(JSON.stringify(found));
+" 2>&1)"
+if echo "$fallback_pos_result" | grep -q '"trailerName":"Claude-Session"'; then
+  pass "narrower-fallback path: still finds a trailer that IS on the head commit itself (fallback scans the head commit, not nothing)"
+else
+  fail "narrower-fallback path: did not find the head-commit trailer with no base ref set — output: $fallback_pos_result"
+fi
+
+# Narrower-fallback negative: no base ref, no trailer on the head commit itself (NEG_REPO).
+fallback_neg_result="$(env -u TRUST_RECONCILE_BASE_REF -u GITHUB_BASE_REF node -e "
+const { findRuntimeSessionTrailers } = require('$RECONCILE');
+const found = findRuntimeSessionTrailers('$NEG_REPO', { sha: '$NEG_HEAD', ref: 'test-branch' });
+console.log(JSON.stringify(found));
+" 2>&1)"
+if [[ "$fallback_neg_result" == "[]" ]]; then
+  pass "narrower-fallback path: findRuntimeSessionTrailers returns an empty array when the head commit itself has no trailer and no base ref is resolvable"
+else
+  fail "narrower-fallback path: expected an empty array, got: $fallback_neg_result"
+fi
+
+# --- No-crash: unresolvable sha degrades to empty array, never throws -----------
+degrade_result="$(node -e "
+const { findRuntimeSessionTrailers } = require('$RECONCILE');
+const found = findRuntimeSessionTrailers('$POS_REPO', { sha: '', ref: 'test-branch' });
+console.log(JSON.stringify(found));
+" 2>&1)"
+if [[ "$degrade_result" == "[]" ]]; then
+  pass "empty sha degrades to an empty array (never throws, never crashes the caller)"
+else
+  fail "empty sha did not degrade cleanly — got: $degrade_result"
+fi
+
+# --- AC7: checkout-depth already verified (no .yml edit needed) -----------------
+echo "--- AC7: .github/workflows/trust-reconcile.yml already carries fetch-depth: 0 ---"
+WORKFLOW_FILE="$ROOT/.github/workflows/trust-reconcile.yml"
+if grep -n "fetch-depth: 0" "$WORKFLOW_FILE" >/dev/null 2>&1; then
+  pass "AC7: fetch-depth: 0 already present in trust-reconcile.yml (Addendum part 3) — no .yml change needed for #305's depth ask"
+else
+  fail "AC7: fetch-depth: 0 not found in trust-reconcile.yml — expected it to already be present"
+fi
+
+if command -v python3 >/dev/null 2>&1 && python3 -c "import yaml" 2>/dev/null; then
+  if python3 - "$WORKFLOW_FILE" << 'PY' 2>/dev/null
+import sys, yaml
+try:
+    yaml.safe_load(open(sys.argv[1]).read())
+    sys.exit(0)
+except yaml.YAMLError:
+    sys.exit(1)
+PY
+  then
+    pass "AC7: trust-reconcile.yml parses as valid YAML (python3 yaml)"
+  else
+    fail "AC7: trust-reconcile.yml failed python3 yaml parse"
+  fi
+else
+  grep -q "^name:" "$WORKFLOW_FILE" && grep -q "trust-reconcile" "$WORKFLOW_FILE" && \
+    pass "AC7: trust-reconcile.yml has expected structural fields (yaml parser unavailable, structural fallback)" || \
+    fail "AC7: trust-reconcile.yml missing expected structural fields"
+fi
+
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "PASS: trust-reconcile.js runtime-session trailer diagnostic (audit-only, key-only, exit-code-identical)"
+  exit 0
+else
+  echo "FAIL: $errors check(s) failed"
+  exit 1
+fi