forgedock 1.16.2 → 1.18.0

package/scripts/fixtures/cost-report/a-merged1.jsonl

@@ -0,0 +1,6 @@
+{"seq":1,"event":"RUN_START","issue":1,"run":"r_1_staging","lane":"staging","version":"2.0.0","repo":"o/a"}
+{"seq":2,"event":"PHASE_COMMIT","phase":"investigate","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":10000}}
+{"seq":3,"event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":100000}}
+{"seq":4,"event":"PHASE_COMMIT","phase":"review","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":200000}}
+{"seq":5,"event":"PHASE_COMMIT","phase":"close","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":20000}}
+{"seq":6,"event":"RUN_TERMINAL","reason":"merged"}

package/scripts/fixtures/cost-report/a-merged2-remediated.jsonl

@@ -0,0 +1,7 @@
+{"seq":1,"event":"RUN_START","issue":2,"run":"r_2_staging","lane":"staging","version":"2.0.0","repo":"o/a"}
+{"seq":2,"event":"PHASE_COMMIT","phase":"investigate","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":10000}}
+{"seq":3,"event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":200000}}
+{"seq":4,"event":"PHASE_COMMIT","phase":"review","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":300000}}
+{"seq":5,"event":"PHASE_COMMIT","phase":"remediate","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":40000}}
+{"seq":6,"event":"PHASE_COMMIT","phase":"close","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":10000}}
+{"seq":7,"event":"RUN_TERMINAL","reason":"merged"}

package/scripts/fixtures/cost-report/a-needs-human.jsonl

@@ -0,0 +1,4 @@
+{"seq":1,"event":"RUN_START","issue":3,"run":"r_3_staging","lane":"staging","version":"2.0.0","repo":"o/a"}
+{"seq":2,"event":"PHASE_COMMIT","phase":"investigate","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":10000}}
+{"seq":3,"event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":90000}}
+{"seq":4,"event":"RUN_TERMINAL","reason":"needs-human"}

package/scripts/fixtures/cost-report/b-merged.jsonl

@@ -0,0 +1,3 @@
+{"seq":1,"event":"RUN_START","issue":4,"run":"r_4_staging","lane":"staging","version":"2.0.0","repo":"o/b"}
+{"seq":2,"event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":1000000}}
+{"seq":3,"event":"RUN_TERMINAL","reason":"merged"}

package/scripts/fixtures/cost-report/c-merged-attempt-usage.jsonl

@@ -0,0 +1,8 @@
+{"seq":1,"ts":"2026-10-10T00:00:00.000Z","event":"RUN_START","issue":5,"run":"r_5_staging","lane":"staging","version":"2.0.0","forge_version":"2.0.0","repo":"o/c"}
+{"seq":2,"ts":"2026-10-10T00:00:01.000Z","event":"PHASE_ATTEMPT_USAGE","phase":"investigate","attempt":1,"usage":{"input_tokens":1,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":10000},"duration_ms":900,"cost_usd":null,"model":null,"turns":null}
+{"seq":3,"ts":"2026-10-10T00:00:02.000Z","event":"PHASE_COMMIT","phase":"investigate","outputs":{},"usage":{"input_tokens":1,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":10000},"last_attempt_usage":{"input_tokens":1,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":10000}}
+{"seq":4,"ts":"2026-10-10T00:00:03.000Z","event":"PHASE_ATTEMPT_USAGE","phase":"build","attempt":1,"usage":{"input_tokens":1,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":100000},"duration_ms":900,"cost_usd":null,"model":null,"turns":null}
+{"seq":5,"ts":"2026-10-10T00:00:04.000Z","event":"PHASE_FAILED","phase":"build","attempt":1,"reason":"no commits","maxAttempts":3,"usage":{"input_tokens":1,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":100000}}
+{"seq":6,"ts":"2026-10-10T00:00:05.000Z","event":"PHASE_ATTEMPT_USAGE","phase":"build","attempt":2,"usage":{"input_tokens":1,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":50000},"duration_ms":900,"cost_usd":null,"model":null,"turns":null}
+{"seq":7,"ts":"2026-10-10T00:00:06.000Z","event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":1,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":150000},"last_attempt_usage":{"input_tokens":1,"output_tokens":1,"cache_creation_input_tokens":0,"cache_read_input_tokens":50000}}
+{"seq":8,"ts":"2026-10-10T00:00:07.000Z","event":"RUN_TERMINAL","reason":"merged"}

package/scripts/fixtures/cost-report/hydrated-no-usage.jsonl

@@ -0,0 +1,3 @@
+{"seq":1,"event":"RUN_START","issue":7,"run":"r_7_staging","lane":"staging","version":"2.0.0","repo":"o/a","hydrated":true}
+{"seq":2,"event":"PHASE_COMMIT","phase":"build","outputs":{}}
+{"seq":3,"event":"RUN_TERMINAL","reason":"merged"}

package/scripts/fixtures/cost-report/old-log-no-version.jsonl

@@ -0,0 +1,3 @@
+{"seq":1,"event":"RUN_START","issue":8,"run":"r_8_staging","lane":"staging"}
+{"seq":2,"event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":70000}}
+{"seq":3,"event":"RUN_TERMINAL","reason":"merged"}

package/scripts/fixtures/cost-report/unfinished-no-terminal.jsonl

@@ -0,0 +1,2 @@
+{"seq":1,"event":"RUN_START","issue":5,"run":"r_5_staging","lane":"staging","version":"2.0.0","repo":"o/a"}
+{"seq":2,"event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":9999000}}

package/scripts/fixtures/cost-report/unfinished-reopened.jsonl

@@ -0,0 +1,5 @@
+{"seq":1,"event":"RUN_START","issue":6,"run":"r_6_staging","lane":"staging","version":"2.0.0","repo":"o/a"}
+{"seq":2,"event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":9999000}}
+{"seq":3,"event":"RUN_TERMINAL","reason":"needs-human"}
+{"seq":4,"event":"RUN_REOPEN","issue":6}
+{"seq":5,"event":"PHASE_COMMIT","phase":"build","outputs":{},"usage":{"input_tokens":10,"output_tokens":5,"cache_creation_input_tokens":1,"cache_read_input_tokens":9999000}}

package/scripts/forge-root.test.sh

@@ -95,8 +95,8 @@ fi
 # forge#3758 (hgate is a fixture of its own: the loop runs once per shell and h14 is reused below with other versions): deploy-gate script resolves on a plugin-only install (cache only, no symlink, no FORGE_* env).
 # The gate-script line is taken verbatim from the spec so the test exercises exactly what ships.
 mkscripts "$T/hgate/.claude/plugins/cache/forgedock/forgedock/1.0.0"; : > "$T/hgate/.claude/plugins/cache/forgedock/forgedock/1.0.0/scripts/resolve-deploy-gate.sh"
-# review-pr.md resolves the gate script through the forge_resolve stub (#3780): the locator and the call line are taken verbatim from the spec.
-sed 's/^[[:space:]]*//' "$ROOT/commands/review-pr.md" | grep '^GATE_SCRIPT=\$(forge_resolve resolve-deploy-gate.sh)$' | sort -u > "$T/gs"
+# review-finalize.sh (the review-pr.md Phase 8 gate) resolves the gate script through forge_resolve (#3780): the locator and the call line are taken verbatim from the script.
+sed 's/^[[:space:]]*//' "$ROOT/scripts/review-finalize.sh" | grep '^GATE_SCRIPT=\$(forge_resolve resolve-deploy-gate.sh)$' | sort -u > "$T/gs"
 expect "gate-script resolver line is identical across sites" 1 "$(wc -l < "$T/gs" | tr -d ' ')"
 { sed 's/^[[:space:]]*//' "$ROOT/commands/review-pr.md" | grep -m1 '^type forge_resolve >/dev/null'; cat "$T/gs"; } > "$T/gs_full"
 gate_run() { ( cd "$T/consumer" && env -i PATH="$PATH" HOME="$1" "$SH" -c "$(cat "$T/gs_full"); printf %s \"\$GATE_SCRIPT\"" ); }
@@ -271,23 +271,28 @@ extract_helper_block() { # file var -> block on stdout
 extract_helper_fn() { # file -> function on stdout
   awk '/^resolve_extract_affected_files\(\) \{/ {inb=1} inb {print} inb && /^\}$/ {exit}' "$1"
 }
-# review-pr.md resolves its helpers through the forge_resolve stub (#3780): the pinned locator plus the call line, taken from the spec.
+# review-pr.md resolves its helpers through the forge_resolve stub (#3780); since #3841 the classify, cap, milestone, priority and dedup helpers are resolved inside
+# scripts/review-finalize.sh and the code-index helper inside scripts/review-prepare.sh: the pinned locator plus the call line, taken from those scripts.
 stub_block() { # file var -> locator + the first `var=$(forge_resolve ...)` line, indentation stripped
   sed 's/^[[:space:]]*//' "$1" | grep -m1 '^type forge_resolve >/dev/null'; sed 's/^[[:space:]]*//' "$1" | grep -m1 "^$2=\$(forge_resolve "
 }
-HR_CLASSIFY="$ROOT/commands/review-pr.md"
+HR_CLASSIFY="$ROOT/scripts/review-finalize.sh"
+HR_PREPARE="$ROOT/scripts/review-prepare.sh"
 HR_AMP="$ROOT/commands/orchestrate/phase-4-execution.md"
 HR_EX3="$ROOT/commands/orchestrate/phase-3-dependency.md"
 stub_block "$HR_CLASSIFY" CLASSIFY_SCRIPT > "$T/hr_classify.sh"
+stub_block "$HR_CLASSIFY" CAP_SCRIPT > "$T/hr_cap.sh"
 extract_helper_block "$HR_AMP" AMP_SCRIPT > "$T/hr_amp.sh"
 extract_helper_fn "$HR_AMP" > "$T/hr_ex4.sh"
 extract_helper_fn "$HR_EX3" > "$T/hr_ex3.sh"
 expect "CLASSIFY_SCRIPT resolver stub found" 1 "$(grep -c '^CLASSIFY_SCRIPT=\$(forge_resolve classify-finding.sh)$' "$T/hr_classify.sh")"
+expect "CAP_SCRIPT resolver stub found" 1 "$(grep -c '^CAP_SCRIPT=\$(forge_resolve cap-findings.sh)$' "$T/hr_cap.sh")"
+expect "review-pr-staging.md no longer carries a CAP_SCRIPT resolver stub (review-finalize.sh owns the cap helper, #3841)" 0 "$(sed 's/^[[:space:]]*//' "$ROOT/commands/review-pr-staging.md" | grep -c '^CAP_SCRIPT=\$(forge_resolve cap-findings.sh)$')"
 expect "AMP_SCRIPT resolver block found" 1 "$(grep -c '^AMP_SCRIPT=""' "$T/hr_amp.sh")"
 expect "extract-affected-files resolver found in phase-4" 1 "$(grep -c 'resolve_extract_affected_files() {' "$T/hr_ex4.sh")"
 expect "extract-affected-files resolver found in phase-3" 1 "$(grep -c 'resolve_extract_affected_files() {' "$T/hr_ex3.sh")"
 cmp -s "$T/hr_ex3.sh" "$T/hr_ex4.sh" && ok || bad 'resolve_extract_affected_files copies differ between phase-3 and phase-4'
-for hr in classify amp ex3 ex4; do
+for hr in classify cap amp ex3 ex4; do
   grep -qF 'plugins/cache/forgedock/forgedock' "$T/hr_$hr.sh" && ok || bad "$hr helper resolver lacks the plugin-cache scan"
   grep -qF 'CLAUDE_CONFIG_DIR' "$T/hr_$hr.sh" && ok || bad "$hr helper resolver lacks CLAUDE_CONFIG_DIR"
   grep -qE '\$PWD|\$REPO_PATH|\$\{PWD|\$\{REPO_PATH' "$T/hr_$hr.sh" && bad "$hr helper resolver lists the working directory or repo path" || ok
@@ -298,7 +303,7 @@ if grep -rnE 'PWD/scripts/|^\$PWD$|REPO_PATH/scripts/extract' "$ROOT/commands" >
 # Behavior (#3483): a planted scripts/<helper>.sh in the cwd must never be selected; a cache-only install must resolve.
 mkdir -p "$T/hrwork/scripts" "$T/hrhome/.claude/plugins/cache/forgedock/forgedock/1.12.0/scripts/lib"
 cp "$ROOT/scripts/lib/forge-resolve.sh" "$T/hrhome/.claude/plugins/cache/forgedock/forgedock/1.12.0/scripts/lib/forge-resolve.sh"
-for h in classify-finding amplification-breaker extract-affected-files; do
+for h in classify-finding cap-findings amplification-breaker extract-affected-files; do
   : > "$T/hrwork/scripts/$h.sh"; : > "$T/hrhome/.claude/plugins/cache/forgedock/forgedock/1.12.0/scripts/$h.sh"
 done
 CACHE_SCRIPTS="$T/hrhome/.claude/plugins/cache/forgedock/forgedock/1.12.0/scripts"
@@ -307,6 +312,8 @@ hr_run() { # home blockfile expr
 }
 expect "CLASSIFY_SCRIPT: cache-only install resolves (cwd copy ignored)" "$CACHE_SCRIPTS/classify-finding.sh" "$(hr_run "$T/hrhome" "$T/hr_classify.sh" 'printf %s "$CLASSIFY_SCRIPT"')"
 expect "CLASSIFY_SCRIPT: no install resolves empty (cwd copy ignored)" "" "$(hr_run "$T/nohome" "$T/hr_classify.sh" 'printf %s "$CLASSIFY_SCRIPT"')"
+expect "CAP_SCRIPT: cache-only install resolves (cwd copy ignored)" "$CACHE_SCRIPTS/cap-findings.sh" "$(hr_run "$T/hrhome" "$T/hr_cap.sh" 'printf %s "$CAP_SCRIPT"')"
+expect "CAP_SCRIPT: no install resolves empty (cwd copy ignored)" "" "$(hr_run "$T/nohome" "$T/hr_cap.sh" 'printf %s "$CAP_SCRIPT"')"
 expect "AMP_SCRIPT: cache-only install resolves (cwd copy ignored)" "$CACHE_SCRIPTS/amplification-breaker.sh" "$(hr_run "$T/hrhome" "$T/hr_amp.sh" 'printf %s "$AMP_SCRIPT"')"
 expect "AMP_SCRIPT: no install resolves empty (cwd copy ignored)" "" "$(hr_run "$T/nohome" "$T/hr_amp.sh" 'printf %s "$AMP_SCRIPT"')"
 expect "extract-affected-files: cache-only install resolves (cwd and REPO_PATH copies ignored)" "$CACHE_SCRIPTS/extract-affected-files.sh" "$(hr_run "$T/hrhome" "$T/hr_ex4.sh" 'resolve_extract_affected_files')"
@@ -332,7 +339,7 @@ hr_check_stub() { # label file var script: the spec calls the script through the
 }
 hr_check_stub review-pr "$HR_CLASSIFY" DERIVE_MILESTONE_SCRIPT derive-finding-milestone.sh
 hr_check_stub review-pr "$HR_CLASSIFY" PRIORITY_SCRIPT severity-to-priority.sh
-hr_check_stub review-pr "$HR_CLASSIFY" CODE_INDEX_SCRIPT code-index.sh
+hr_check_stub review-prepare "$HR_PREPARE" CODE_INDEX_SCRIPT code-index.sh
 hr_check_stub review-pr "$HR_CLASSIFY" DEDUP_SCRIPT issue-dedup.sh
 hr_check_block issue "$ROOT/commands/issue.md" DEDUP_SCRIPT issue-dedup.sh
 stub_block "$HR_CLASSIFY" DERIVE_MILESTONE_SCRIPT > "$T/hr_dm.sh"
@@ -409,7 +416,7 @@ FR="$ROOT/scripts/lib/forge-resolve.sh"; FB="$ROOT/scripts/lib/fence-bootstrap.s
 [ -f "$FR" ] && [ -f "$FB" ] && ok || bad "scripts/lib/forge-resolve.sh and scripts/lib/fence-bootstrap.sh must exist"
 sed 's/^[[:space:]]*//' "$STG_SPEC" | grep '^type forge_resolve >/dev/null' | sort | uniq -c > "$T/loc_uniq"
 [ "$(wc -l < "$T/loc_uniq" | tr -d ' ')" = 1 ] && ok || bad "forge_resolve locator line must be byte-identical across every stub in review-pr-staging.md"
-[ "$(awk '{print $1}' "$T/loc_uniq")" -ge 30 ] && ok || bad "expected a locator on every bootstrap (21) and resolver (11) stub"
+[ "$(awk '{print $1}' "$T/loc_uniq")" -ge 25 ] && ok || bad "expected a locator on every bootstrap (21) and resolver (5) stub"
 grep -qE 'PWD|\$\(pwd\)|REPO_PATH' "$T/locator.sh" && bad "stub locator must not consult the cwd or repo under review" || ok
 [ "$(grep -c '# FENCE_BOOTSTRAP$' "$STG_SPEC")" = 21 ] && ok || bad "expected 21 fence bootstrap stubs"
 [ "$(grep '# FENCE_BOOTSTRAP$' "$STG_SPEC" | sort -u | wc -l | tr -d ' ')" = 1 ] && ok || bad "fence bootstrap stubs must be byte-identical"
@@ -419,11 +426,11 @@ grep -qE '^[[:space:]]*(TRUSTED_SCRIPT|[A-Z_]+_SCRIPT)=""$|_tc="\$\(printf' "$ST
 # no $PWD / $(pwd) tier in the helper (comments aside)
 grep -nE '\$PWD|\$\(pwd\)|\$\{PWD' "$FR" | grep -vE '^[0-9]+:[[:space:]]*#' | grep -q . && bad "forge-resolve.sh must have no PWD tier" || ok
 
-# Guard (#3779): remediate.md carries the same byte-identical locator stub (7 fences: 5 gate sites, trusted-comments, CI gate) and none of the old inlined resolvers.
+# Guard (#3779): remediate.md carries the same byte-identical locator stub (9 fences: M4 ancestry, merged-first transition-label (the merge-branch one reuses the CI-gate fence locator), 5 gate sites, trusted-comments, CI gate) and none of the old inlined resolvers.
 REM_SPEC="$ROOT/commands/work-on/remediate.md"
 sed 's/^[[:space:]]*//' "$REM_SPEC" | grep '^type forge_resolve >/dev/null' | sort | uniq -c > "$T/rem_uniq"
 [ "$(wc -l < "$T/rem_uniq" | tr -d ' ')" = 1 ] && ok || bad "remediate.md locator lines must be byte-identical"
-expect "remediate.md locator count (one per fence that resolves a script)" 7 "$(awk '{print $1}' "$T/rem_uniq")"
+expect "remediate.md locator count (one per fence that resolves a script)" 9 "$(awk '{print $1}' "$T/rem_uniq")"
 [ "$(sed 's/^[[:space:]]*//' "$REM_SPEC" | grep '^type forge_resolve >/dev/null' | sed 1q)" = "$(cat "$T/locator.sh")" ] && ok || bad "remediate.md locator differs from the pinned review-pr-staging.md locator"
 expect "remediate.md inlined FORGE_ROOT bootstrap copies" 0 "$(grep -c '# FORGE_ROOT bootstrap' "$REM_SPEC" || true)"
 grep -qE '^[[:space:]]*(TRUSTED_SCRIPT|[A-Z_]+_SCRIPT)=""|_tc="\$\(printf|^[[:space:]]*GATE_SCRIPT=""' "$REM_SPEC" && bad "remediate.md still carries an inlined resolver block" || ok
@@ -436,7 +443,7 @@ expect "remediate.md: forge_resolve calls without a preceding locator in the sam
 RP_SPEC="$ROOT/commands/review-pr.md"
 sed 's/^[[:space:]]*//' "$RP_SPEC" | grep '^type forge_resolve >/dev/null' | sort | uniq -c > "$T/rp_uniq"
 [ "$(wc -l < "$T/rp_uniq" | tr -d ' ')" = 1 ] && ok || bad "review-pr.md locator lines must be byte-identical"
-[ "$(awk '{print $1}' "$T/rp_uniq")" -ge 15 ] && ok || bad "expected a locator in every review-pr.md fence that resolves a script (>=15)"
+[ "$(awk '{print $1}' "$T/rp_uniq")" -ge 10 ] && ok || bad "expected a locator in every review-pr.md fence that resolves a script (>=10; the classify/file/prepare helpers resolve inside the review scripts since #3841)"
 [ "$(sed 's/^[[:space:]]*//' "$RP_SPEC" | grep '^type forge_resolve >/dev/null' | sed 1q)" = "$(cat "$T/locator.sh")" ] && ok || bad "review-pr.md locator differs from the pinned review-pr-staging.md locator"
 expect "review-pr.md inlined FORGE_ROOT bootstrap copies" 0 "$(grep -c 'FORGE_ROOT bootstrap' "$RP_SPEC" || true)"
 # (SCOPE_SCRIPT="" is a sibling path derived from the resolved trusted script's own directory, not a resolver accumulator)

package/scripts/lib/fence-bootstrap.sh

@@ -10,7 +10,8 @@ CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
 [ -n "${GH_REPO:-}" ] || GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE" 2>/dev/null)
 [ -n "${DEFAULT_BRANCH:-}" ] || DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE" 2>/dev/null)
 [ -n "${STAGING_BRANCH:-}" ] || STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE" 2>/dev/null)
-# numeric-validated: a tampered file never reaches gh
-[ -n "${PR_NUMBER:-}" ] || { [ -r "$_SD/staging_pr_number" ] && PR_NUMBER=$(sed -n '1{/^[0-9][0-9]*$/p;q}' "$_SD/staging_pr_number"); }
+# run-keyed pointer (concurrent runs share $_SD); numeric-validated: a tampered file never reaches gh
+FORGE_RUN_KEY="${FORGE_RUN_KEY:-${FORGE_RUN_ID:-${CLAUDE_CODE_SESSION_ID:-${CLAUDE_SESSION_ID:-${CODEX_THREAD_ID:-${OPENCODE_SESSION_ID:-$PPID}}}}}}"; FORGE_RUN_KEY=$(printf '%s' "$FORGE_RUN_KEY" | tr -c 'A-Za-z0-9_-' '_')
+[ -n "${PR_NUMBER:-}" ] || { [ -r "$_SD/staging_pr_number.${FORGE_RUN_KEY}" ] && PR_NUMBER=$(sed -n '1{/^[0-9][0-9]*$/p;q}' "$_SD/staging_pr_number.${FORGE_RUN_KEY}"); }
 [ -n "${ALL_PR_NUMBERS:-}" ] || { [ -n "${PR_NUMBER:-}" ] && [ -r "$_SD/${PR_NUMBER}_bundle-prs.txt" ] && ALL_PR_NUMBERS=$(grep -E '^[0-9]+$' "$_SD/${PR_NUMBER}_bundle-prs.txt"); }
-[ -n "${PR_NUMBER:-}" ] || echo "WARNING: PR_NUMBER is empty after reload (no staging_pr_number in $_SD): this fence cannot key its scratch files or post to a PR."
+[ -n "${PR_NUMBER:-}" ] || echo "WARNING: PR_NUMBER is empty after reload (no staging_pr_number.${FORGE_RUN_KEY} in $_SD): this fence cannot key its scratch files or post to a PR."

package/scripts/lib/pr-issue-number.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# pr-issue-number.sh: sourced helper — the ONE numeric-validated "Closes #N" extractor for a PR body.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Source it, never exec it (resolve with `forge_resolve lib/pr-issue-number.sh`).
+#   pr_issue_number            reads the PR body on stdin
+#   pr_issue_number_of <body>  same, body as an argument
+# Prints the number of the FIRST `Closes|Fixes|Resolves #N` reference (any keyword form, any case), or NOTHING when the body
+# has none. The output is always ^[0-9]+$ or empty, so it is safe to place in an API path. A hand-rolled jq `gsub` returns the
+# whole input when the pattern does not match, which is why every extraction goes through this helper instead.
+pr_issue_number() {
+    local n
+    n=$(grep -oiE '(close[sd]?|fix(e[sd])?|resolve[sd]?):?[[:space:]]+#[0-9]+' 2>/dev/null | head -n 1 | grep -oE '[0-9]+$' | head -n 1)
+    case "$n" in ''|*[!0-9]*) return 0 ;; esac
+    printf '%s\n' "$n"
+}
+pr_issue_number_of() { printf '%s\n' "${1:-}" | pr_issue_number; }

package/scripts/lib/review-template-resolve.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# review-template-resolve.sh: sourced helper — the ONE resolution chain for the review-pr-agents persona templates.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Source it, never exec it. `review_template_resolve [repo_path]` sets:
+#   TEMPLATE_SOURCE    plugin_root | forge_home | repo_path | monolithic_catalog | none
+#   TEMPLATE_BASE      directory holding protocols.md and the persona files (empty for monolithic_catalog / none)
+#   MONOLITHIC_CATALOG path of the last-resort catalog (monolithic_catalog only)
+# Chain: the running plugin root (CLAUDE_PLUGIN_ROOT, absolute only), then FORGE_HOME, then the trusted install root from
+# forge_root when the resolver is loaded, then the repo path argument, then the monolithic catalog (it must contain `### Agent:`
+# headers: a post-split repo ships a router stub at that path that points back to the missing directory). `none` is a fatal setup
+# error: the caller must stop and never review inline. The repo path is data, only ever read for template files.
+review_template_resolve() {
+    local _plugin _root _repo="${1:-}"
+    TEMPLATE_BASE=""; TEMPLATE_SOURCE="none"; MONOLITHIC_CATALOG=""
+    _plugin="${CLAUDE_PLUGIN_ROOT:-}"; case "$_plugin" in /*) ;; *) _plugin="" ;; esac
+    if [ -n "$_plugin" ] && [ -f "$_plugin/commands/review-pr-agents/protocols.md" ]; then
+        TEMPLATE_BASE="$_plugin/commands/review-pr-agents"; TEMPLATE_SOURCE="plugin_root"; return 0
+    fi
+    case "${FORGE_HOME:-}" in
+        /*) if [ -f "$FORGE_HOME/commands/review-pr-agents/protocols.md" ]; then
+                TEMPLATE_BASE="$FORGE_HOME/commands/review-pr-agents"; TEMPLATE_SOURCE="forge_home"; return 0
+            fi ;;
+    esac
+    if type forge_root >/dev/null 2>&1; then
+        _root=$(forge_root)
+        if [ -n "$_root" ] && [ -f "$_root/commands/review-pr-agents/protocols.md" ]; then
+            TEMPLATE_BASE="$_root/commands/review-pr-agents"; TEMPLATE_SOURCE="forge_home"; return 0
+        fi
+    fi
+    if [ -n "$_repo" ]; then
+        if [ -f "$_repo/commands/review-pr-agents/protocols.md" ]; then
+            TEMPLATE_BASE="$_repo/commands/review-pr-agents"; TEMPLATE_SOURCE="repo_path"; return 0
+        fi
+        if [ -f "$_repo/commands/review-pr-agents.md" ] && grep -q "^### Agent:" "$_repo/commands/review-pr-agents.md" 2>/dev/null; then
+            MONOLITHIC_CATALOG="$_repo/commands/review-pr-agents.md"; TEMPLATE_SOURCE="monolithic_catalog"; return 0
+        fi
+    fi
+    return 0
+}

package/scripts/lib/telemetry.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# telemetry.sh — fail-safe structured telemetry emitter (sourced helper, or exec'd as a CLI).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+#   . scripts/lib/telemetry.sh;  forge_emit <event> key=value...      # sourced
+#   bash scripts/lib/telemetry.sh <event> key=value...                 # exec'd (spec call sites)
+#
+# One compact JSON line per call: v, ts, forge_version, repo, issue, pr, run, phase, event + payload. GitHub is the
+# canonical store: the line is appended to the trusted `<!-- FORGE:TELEMETRY v1 -->` comment on the issue (or PR for
+# review-side events), edited in place (JSONL inside a fenced block), rolling over to `... v1 part=N` near 60000 chars.
+# A failed write is appended to a local buffer and flushed by the next emit for the same target; the buffer is only
+# a cache, everything flushed is recoverable from GitHub alone. The emitter NEVER fails or changes the caller:
+# always returns 0, all output is discarded, `FORGE_TELEMETRY=off` disables it. It records ids, counts and codes only,
+# never comment bodies, file contents or secrets (values are charset-restricted and truncated).
+#
+# Context env: FORGE_REPO (default: parsed from `git remote get-url origin`), FORGE_ISSUE, FORGE_PR, FORGE_RUN,
+# FORGE_PHASE; null when unset. With no repo or no numeric target the record is dropped (nothing to write to).
+# Test hooks: FORGE_TELEMETRY_GH (gh replacement), FORGE_TELEMETRY_BUFFER_DIR, FORGE_TELEMETRY_MAX_CHARS.
+# Comment trust is decided by scripts/trusted-comments.sh (the one trust predicate), resolved next to this file.
+# bash 3.2 portable.
+
+_FORGE_TEL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd)"
+
+_forge_tel_clean() { # sanitize a payload value: restricted charset, max 200 chars
+  printf '%s' "$1" | tr '\n\r\t' '   ' | tr -c 'A-Za-z0-9 _.:/#@+=,-' '_' | cut -c1-200
+}
+
+_forge_tel_record() { # event k=v... -> one JSON line on stdout
+  local ev="$1"; shift
+  local ver="" repo="${FORGE_REPO:-}" args=() kv k v
+  if [ -z "$repo" ]; then
+    repo=$(git remote get-url origin 2>/dev/null | sed -E 's#^.*[:/]([^/:]+/[^/]+)$#\1#; s#\.git$##')
+  fi
+  ver=$(jq -r '.version // empty' "$_FORGE_TEL_DIR/../../package.json" 2>/dev/null)
+  for kv in "$@"; do
+    k="${kv%%=*}"; v="${kv#*=}"
+    case "$kv" in *=*) ;; *) continue ;; esac
+    case "$k" in ''|*[!A-Za-z0-9_]*) continue ;; esac
+    case "$k" in v|ts|forge_version|repo|issue|pr|run|phase|event|eid) continue ;; esac
+    args+=("$k" "$(_forge_tel_clean "$v")")
+  done
+  jq -nc --arg ev "$ev" --arg ver "$ver" --arg repo "$repo" --arg issue "${FORGE_ISSUE:-}" --arg pr "${FORGE_PR:-}" \
+    --arg run "${FORGE_RUN:-}" --arg phase "${FORGE_PHASE:-}" --arg eid "$(date +%s)-$$-${RANDOM}${RANDOM}${RANDOM}" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
+    def num: if test("^[0-9]+$") then tonumber else null end;
+    def str: if . == "" then null else . end;
+    ($ARGS.positional | [range(0; length; 2) as $i | {key: .[$i], value: .[$i+1]}]
+      | map(.value |= (if test("^-?[0-9]+$") then tonumber elif . == "true" then true elif . == "false" then false else . end))
+      | from_entries) as $p
+    | {v: 1, ts: $ts, forge_version: ($ver | str), repo: ($repo | str), issue: ($issue | num), pr: ($pr | num),
+       run: ($run | str), phase: ($phase | str), event: $ev, eid: $eid} + $p' --args "${args[@]}"
+}
+
+# Prints "<number> <repo>" of the comment target (issue or PR) for this event, or nothing when none is usable.
+_forge_tel_target() {
+  local ev="$1" repo="$2" n
+  case "$ev" in
+    review_panel|finding_disposition|ci_gate) n="${FORGE_PR:-}"; case "$n" in ''|*[!0-9]*) n="${FORGE_ISSUE:-}" ;; esac ;;
+    *) n="${FORGE_ISSUE:-}"; case "$n" in ''|*[!0-9]*) n="${FORGE_PR:-}" ;; esac ;;
+  esac
+  case "$n" in ''|*[!0-9]*) return 0 ;; esac
+  case "$repo" in */*) ;; *) return 0 ;; esac
+  printf '%s %s\n' "$n" "$repo"
+}
+
+# Appends the JSONL lines on stdin to the trusted telemetry comment of <repo>#<n>; returns non-zero on any failure.
+_forge_tel_upsert() {
+  local repo="$1" n="$2" gh="${FORGE_TELEMETRY_GH:-gh}" max="${FORGE_TELEMETRY_MAX_CHARS:-60000}"
+  local nl fence new comments cand id body part best_id="" best_part=0 best_body="" all_bodies="" lines hdr out tc
+  new=$(cat); [ -n "$new" ] || return 0
+  tc="$_FORGE_TEL_DIR/../trusted-comments.sh"; [ -f "$tc" ] || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+  local to=""; command -v timeout >/dev/null 2>&1 && to="timeout 30"
+  comments=$($to "$gh" api --paginate "repos/$repo/issues/$n/comments" 2>/dev/null) || return 1
+  [ -n "$comments" ] || comments='[]'
+  # Candidates carry the marker; each is then checked individually against the trust predicate.
+  while IFS= read -r cand; do
+    [ -n "$cand" ] || continue
+    id=$(printf '%s' "$cand" | jq -r '.id')
+    [ "$(printf '[%s]' "$cand" | bash "$tc" count '^<!-- FORGE:TELEMETRY v1( part=[0-9]+)? -->' 2>/dev/null)" = "1" ] || continue
+    body=$(printf '%s' "$cand" | jq -r '.body')
+    all_bodies="${all_bodies}${body}"$'\n'
+    part=$(printf '%s' "$body" | sed -n '1s/^<!-- FORGE:TELEMETRY v1 part=\([0-9]*\) -->.*/\1/p'); part="${part:-1}"
+    if [ "$part" -ge "$best_part" ]; then best_part="$part"; best_id="$id"; best_body="$body"; fi
+  done < <(printf '%s' "$comments" | jq -c -s '.[][] | select((.body // "") | test("^<!-- FORGE:TELEMETRY v1( part=[0-9]+)? -->")) | {id, body, user, author_association}' 2>/dev/null)
+  # Drop lines any part already holds (a PATCH whose reply was lost, or a re-flushed buffer). Every record carries a
+  # unique eid, so two distinct same-second events are never byte-identical and are never dropped by this check.
+  lines=""
+  while IFS= read -r l; do
+    [ -n "$l" ] || continue
+    case "$all_bodies" in *"$l"*) continue ;; esac
+    lines="${lines}${l}"$'\n'
+  done <<< "$new"
+  [ -n "$lines" ] || return 0
+  # bash 3.2: $'..' inside a double-quoted ${..%..} is NOT expanded (and backticks there start a command
+  # substitution), so the newline and fence live in variables and the pattern quotes them.
+  nl=$'\n'; fence='```'
+  lines="${lines%"$nl"}"
+  if [ -n "$best_id" ]; then
+    local cur="${best_body%"$nl$fence"*}"            # body up to the closing fence
+    out="${cur}"$'\n'"${lines}"$'\n```'
+    if [ "${#out}" -le "$max" ]; then
+      $to "$gh" api -X PATCH "repos/$repo/issues/comments/$best_id" -f body="$out" >/dev/null 2>&1; return $?
+    fi
+    hdr="<!-- FORGE:TELEMETRY v1 part=$((best_part + 1)) -->"
+  else
+    hdr="<!-- FORGE:TELEMETRY v1 -->"
+  fi
+  out="${hdr}"$'\n```jsonl\n'"${lines}"$'\n```'
+  $to "$gh" api -X POST "repos/$repo/issues/$n/comments" -f body="$out" >/dev/null 2>&1
+}
+
+_forge_tel_impl() {
+  local ev="${1:-}"; shift
+  [ "${FORGE_TELEMETRY:-on}" = "off" ] && return 0
+  case "$ev" in ''|*[!A-Za-z0-9_.-]*) return 0 ;; esac
+  command -v jq >/dev/null 2>&1 || return 0
+  local rec repo tgt n buf bdir pending
+  rec=$(_forge_tel_record "$ev" "$@") && [ -n "$rec" ] || return 0
+  repo=$(printf '%s' "$rec" | jq -r '.repo // ""')
+  tgt=$(_forge_tel_target "$ev" "$repo"); [ -n "$tgt" ] || return 0
+  n="${tgt%% *}"
+  bdir="${FORGE_TELEMETRY_BUFFER_DIR:-$HOME/.forge/telemetry-buffer}"
+  buf="$bdir/$(printf '%s' "$repo" | tr '/' '_')__${n}.jsonl"
+  # Serialize emitters on this host per target: the GitHub read-modify-write has no version check, so two overlapping
+  # emitters would each PATCH a stale snapshot (lost record) or both POST a first/rollover part (duplicate comments).
+  # Bounded wait (every loop pass counts, 50 x 0.1s); a lock over 5 min old (longer than any bounded hold: two 30s gh
+  # calls plus trust checks) is stale and reclaimed by an atomic rename so only one waiter wins; the holder writes an
+  # owner token and releases only its own lock. A non-writable buffer dir skips locking. On timeout the record is
+  # buffered, never dropped.
+  local lock="$bdir/.lock-$(printf '%s' "$repo" | tr '/' '_')__${n}" tries=0 got="" token="$$.${RANDOM}${RANDOM}"
+  if ! { mkdir -p "$bdir" 2>/dev/null && [ -w "$bdir" ]; }; then tries=50; got=nolock; fi
+  while [ "$tries" -lt 50 ]; do
+    if mkdir "$lock" 2>/dev/null; then printf '%s' "$token" > "$lock/owner" 2>/dev/null; got=1; break; fi
+    if [ -n "$(find "$lock" -maxdepth 0 -mmin +5 2>/dev/null)" ]; then
+      mv "$lock" "$lock.stale.$token" 2>/dev/null && rm -rf "$lock.stale.$token" 2>/dev/null
+    else
+      sleep 0.1 2>/dev/null || sleep 1
+    fi
+    tries=$((tries + 1))
+  done
+  if [ -z "$got" ]; then printf '%s\n' "$rec" >> "$buf" 2>/dev/null; return 0; fi
+  _forge_tel_unlock() { [ "$got" = 1 ] && [ "$(cat "$lock/owner" 2>/dev/null)" = "$token" ] && rm -rf "$lock" 2>/dev/null; got=""; }
+  trap '_forge_tel_unlock' EXIT; trap '_forge_tel_unlock; exit 1' HUP INT TERM
+  # Claim the buffer by renaming it first: a record appended by another emitter after this point lands in a fresh
+  # buffer file and survives. Holding the lock, any other "$buf.flush.*" is an orphan of a killed emitter: fold it in.
+  local claimed="$buf.flush.$token" f
+  pending="$rec"
+  if [ -s "$buf" ]; then mv "$buf" "$claimed" 2>/dev/null; fi
+  for f in "$buf".flush.*; do
+    [ -f "$f" ] && [ "$f" != "$claimed" ] && cat "$f" >> "$claimed" 2>/dev/null && rm -f "$f" 2>/dev/null
+  done
+  if [ -s "$claimed" ]; then pending="$(cat "$claimed")"$'\n'"$rec"; fi
+  if printf '%s\n' "$pending" | _forge_tel_upsert "$repo" "$n"; then
+    rm -f "$claimed" 2>/dev/null
+  else
+    if [ -f "$claimed" ]; then cat "$claimed" >> "$buf" 2>/dev/null; rm -f "$claimed" 2>/dev/null; fi
+    printf '%s\n' "$rec" >> "$buf" 2>/dev/null
+  fi
+  _forge_tel_unlock
+  return 0
+}
+
+# Subshell + discarded output: no option, variable, trap or stream of the caller can be changed or polluted.
+forge_emit() { ( set +eu +o pipefail 2>/dev/null; _forge_tel_impl "$@" ) >/dev/null 2>&1 </dev/null || true; return 0; }
+
+# Exec'd as a CLI (spec call sites); sourcing only defines functions.
+if [ -n "${BASH_SOURCE[0]:-}" ] && [ "${BASH_SOURCE[0]}" = "$0" ]; then forge_emit "$@"; exit 0; fi

package/scripts/publish-staging-sync.test.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# publish-staging-sync.test.sh — guards the publish.yml "Sync version to staging" step (forge#3695)
+# and the deploy-pr Phase 2A.5 version-sync pre-flight. Static assertions, no network.
+# Usage: bash scripts/publish-staging-sync.test.sh
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+PUB="$ROOT/.github/workflows/publish.yml"
+DEP="$ROOT/commands/deploy-pr.md"
+
+PASS=0; FAILN=0
+ok()  { PASS=$((PASS+1)); echo "ok   - $1"; }
+bad() { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
+has() { if grep -qF -e "$2" "$3"; then ok "$1"; else bad "$1 (missing '$2')"; fi; }
+
+# Extract the sync step block (from its name line to the next step's name line).
+STEP=$(awk '/- name: Sync version to staging/{f=1;print;next} f&&/^      - name: /{exit} f{print}' "$PUB")
+[ -n "$STEP" ] && ok "publish.yml has the Sync version to staging step" || bad "publish.yml has the Sync version to staging step"
+
+L_PUSH=$(grep -n -- '- name: Push version bump' "$PUB" | head -1 | cut -d: -f1)
+L_SYNC=$(grep -n -- '- name: Sync version to staging' "$PUB" | head -1 | cut -d: -f1)
+L_REL=$(grep -n -- '- name: Create GitHub Release' "$PUB" | head -1 | cut -d: -f1)
+if [ -n "$L_PUSH" ] && [ -n "$L_SYNC" ] && [ -n "$L_REL" ] && [ "$L_PUSH" -lt "$L_SYNC" ] && [ "$L_SYNC" -lt "$L_REL" ]; then
+  ok "sync step sits between Push version bump and Create GitHub Release"
+else bad "sync step sits between Push version bump and Create GitHub Release"; fi
+
+stepHas() { if printf '%s\n' "$STEP" | grep -qF -e "$2"; then ok "$1"; else bad "$1 (missing '$2')"; fi; }
+stepHas "step fetches origin/staging" "origin/staging"
+stepHas "step pushes HEAD to staging" "git push origin HEAD:staging"
+stepHas "step is non-fatal" "continue-on-error: true"
+stepHas "step is guarded by SKIP_PUBLISH" "env.SKIP_PUBLISH != 'true'"
+stepHas "commit carries [skip ci]" "[skip ci]"
+stepHas "only version files are staged" "git add package.json .claude-plugin/plugin.json"
+stepHas "failure emits a warning" "::warning::"
+if printf '%s\n' "$STEP" | grep -qE 'git (merge|pull)'; then bad "step must not merge main (version-only commit)"; else ok "step does not merge main"; fi
+
+has "deploy-pr has the 2A.5 pre-flight" "### 2A.5: Version Sync Pre-flight" "$DEP"
+has "deploy-pr pre-flight compares package.json" "package.json" "$DEP"
+
+if git -C "$ROOT" rev-parse --verify -q origin/main >/dev/null 2>&1; then
+  if git -C "$ROOT" diff --quiet origin/main -- .github/workflows/version-guard.yml; then ok "version-guard.yml unchanged"; else bad "version-guard.yml unchanged"; fi
+fi
+
+echo "passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/remediate-liveness.sh

@@ -12,7 +12,9 @@
 #       lease.by that is not the dispatching holder and not a provably dead same-host engine pid. An until past
 #       the TTL cap is not a lease an engine could have written (the issue body is author-editable), so it is dead.
 #   (b) review: the newest trusted FORGE:REVIEW_ROUTE comment is younger than REVIEW_PENDING_MAX_S and no trusted
-#       FORGE:REVIEW-AGENT:* comment carries a Reviewed-SHA that prefix-matches the routed sha (either direction).
+#       FORGE:REVIEW-AGENT:* or FORGE:REVIEW-CARRIED comment carries a Reviewed-SHA that prefix-matches the routed sha (either direction),
+#       and no trusted FORGE:{CI|INPR|BASESYNC}_REMEDIATION: pr=<pr> bound marker on the issue is at or after that route
+#       (a review that handed off to remediation, even before dispatching a panel, is never in flight).
 #   A deferral is bounded: after MAX_DEFERRALS trusted FORGE:REMEDIATION_DEFERRED records for this PR the answer is
 #   EXHAUSTED (a human is needed), so a flapping lease or a dead review can never park a PR forever.
 #
@@ -23,6 +25,10 @@
 #   LIVENESS: ERROR <why>              exit 2   unreadable state; fail closed (never "no lease", never delete)
 # Trust predicate for comments: Bot, or OWNER/MEMBER/COLLABORATOR (same default as scripts/trusted-comments.sh).
 set -uo pipefail
+# Telemetry (forge#3834): best-effort decision record; never changes stdout, stderr or the exit code.
+_TEL="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/telemetry.sh"; [ -f "$_TEL" ] && . "$_TEL" 2>/dev/null
+type forge_emit >/dev/null 2>&1 || forge_emit() { :; }
+[ -z "${DRY_RUN:-}" ] || FORGE_TELEMETRY=off
 
 PR="${1:-}"; ISSUE="${2:-}"; REPO="${3:-}"; HOLDER="${4:-}"
 MAX_LEASE_TTL_MS=1800000      # 3x the engine's 10 min lease TTL
@@ -39,7 +45,28 @@ NOW_S=$(( NOW_MS / 1000 ))
 
 TRUST='((.user.type // "") == "Bot" or ((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR")))'
 
-ISSUE_JSON=$(gh issue view "$ISSUE" -R "$REPO" --json body 2>/dev/null) || err "issue unreadable"
+# Body + provenance (issue-body FORGE:STATE trust gate): the LAST EDITOR (editor // author) must be a Bot,
+# or the creator with OWNER/MEMBER/COLLABORATOR, or a distinct editor with write/maintain/admin permission.
+# Unreadable provenance fails closed. An untrusted body is treated as having no FORGE:STATE (no lease).
+OWNER_PART="${REPO%%/*}"; NAME_PART="${REPO#*/}"
+PROV_Q='query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){issue(number:$number){body authorAssociation author{login __typename} editor{login __typename}}}}'
+PROV=$(gh api graphql -f query="$PROV_Q" -F owner="$OWNER_PART" -F name="$NAME_PART" -F number="$ISSUE" 2>/dev/null) || err "issue unreadable"
+ISSUE_JSON=$(printf '%s' "$PROV" | jq -c '.data.repository.issue | {body: (.body // "")}' 2>/dev/null) || err "issue unreadable"
+ACTOR_ROW=$(printf '%s' "$PROV" | jq -r '.data.repository.issue | (.editor // .author) as $a | [($a.__typename // ""), ($a.login // ""), (if .editor != null and .editor.login != .author.login then "EDITOR" else (.authorAssociation // "NONE") end)] | @tsv' 2>/dev/null) || err "issue unreadable"
+A_TYPE=$(printf '%s' "$ACTOR_ROW" | cut -f1); A_LOGIN=$(printf '%s' "$ACTOR_ROW" | cut -f2); A_ASSOC=$(printf '%s' "$ACTOR_ROW" | cut -f3)
+BODY_TRUSTED=false
+if [ "$A_TYPE" = "Bot" ]; then BODY_TRUSTED=true
+else
+  case "$A_ASSOC" in
+    OWNER|MEMBER|COLLABORATOR) BODY_TRUSTED=true ;;
+    EDITOR)
+      if printf '%s' "$A_LOGIN" | grep -qE '^[A-Za-z0-9-]{1,39}$'; then
+        PERM=$(gh api "repos/$REPO/collaborators/$A_LOGIN/permission" --jq .permission 2>/dev/null || true)
+        case "$PERM" in admin|maintain|write) BODY_TRUSTED=true ;; esac
+      fi ;;
+  esac
+fi
+[ "$BODY_TRUSTED" = "true" ] || ISSUE_JSON='{"body":""}'
 ISSUE_COMMENTS=$(gh api --paginate "repos/$REPO/issues/$ISSUE/comments" 2>/dev/null) || err "issue comments unreadable"
 PR_COMMENTS=$(gh api --paginate "repos/$REPO/issues/$PR/comments" 2>/dev/null) || err "PR comments unreadable"
 [ -n "$PR_COMMENTS" ] || err "PR comments unreadable"
@@ -63,22 +90,30 @@ if [ -n "$STATE_JSON" ]; then
   fi
 fi
 
-# (b) a routed review that is still inside its window and has produced no verdict for the routed sha.
+# (b) a routed review that is still inside its window and has produced no verdict (FORGE:REVIEW-AGENT or, for BASE_SYNC_ONLY, FORGE:REVIEW-CARRIED) for the routed sha.
 ROUTE=$(printf '%s' "$PR_COMMENTS" | jq -rs "[.[][] | select($TRUST) | select((.body // \"\") | test(\"^<!-- FORGE:REVIEW_ROUTE mode=[^ ]+ spec=review-pr.md sha=[0-9a-f]{7,40} -->\")) | select((.body | test(\"mode=spec-evolution-blocked\")) | not)] | last | if . == null then \"\" else ((.body | capture(\"sha=(?<s>[0-9a-f]{7,40})\").s) + \" \" + ((.created_at // \"\") | fromdateiso8601? // 0 | tostring)) end" 2>/dev/null) \
   || err "review comments unparseable"
 ROUTE_SHA="${ROUTE%% *}"; ROUTE_AT="${ROUTE##* }"; REVIEW_PENDING=false
 if [ -n "$ROUTE_SHA" ]; then
   case "$ROUTE_AT" in ''|*[!0-9]*) ROUTE_AT=0 ;; esac
-  VERDICTS=$(printf '%s' "$PR_COMMENTS" | jq -rs --arg r "$ROUTE_SHA" "[.[][] | select($TRUST) | select((.body // \"\") | test(\"^<!-- FORGE:REVIEW-AGENT:[a-z-]+ -->\")) | ((.body | capture(\"(^|\\\\n)Reviewed-SHA: (?<s>[0-9a-f]{7,40})\")? // {s: \"\"}).s) as \$s | select(\$s != \"\" and ((\$r | startswith(\$s)) or (\$s | startswith(\$r))))] | length" 2>/dev/null) || err "reviewer comments unreadable"
-  [ "${VERDICTS:-0}" -eq 0 ] && [ "$ROUTE_AT" -gt 0 ] && [ $(( NOW_S - ROUTE_AT )) -lt "$REVIEW_PENDING_MAX_S" ] && REVIEW_PENDING=true
+  VERDICTS=$(printf '%s' "$PR_COMMENTS" | jq -rs --arg r "$ROUTE_SHA" "[.[][] | select($TRUST) | select((.body // \"\") | test(\"^<!-- FORGE:REVIEW-(AGENT:[a-z-]+|CARRIED) -->\")) | ((.body | capture(\"(^|\\\\n)Reviewed-SHA: (?<s>[0-9a-f]{7,40})\")? // {s: \"\"}).s) as \$s | select(\$s != \"\" and ((\$r | startswith(\$s)) or (\$s | startswith(\$r))))] | length" 2>/dev/null) || err "reviewer comments unreadable"
+  # Handoff: the dispatcher posts FORGE:CI_REMEDIATION / FORGE:INPR_REMEDIATION / FORGE:BASESYNC_REMEDIATION: pr=N on the issue right before dispatching remediation, so a
+  # trusted marker at or after the route means the review handed off (possibly before any panel) and nothing is in flight. A route newer than the marker is a re-review.
+  HANDOFF_Q='[.[][] | select('"$TRUST"') | select((.body // "") | test("(^|\\n)[ \\t]*<!-- FORGE:(CI|INPR|BASESYNC)_REMEDIATION: " + $m + " -->[ \\t\\r]*(\\n|$)")) | ((.created_at // "") | fromdateiso8601? // 0)] | max // 0'
+  HANDOFF_AT=$(printf '%s' "$ISSUE_COMMENTS" | jq -rs --arg m "pr=$PR" "$HANDOFF_Q" 2>/dev/null) || err "handoff markers unreadable"
+  case "$HANDOFF_AT" in ''|*[!0-9]*) HANDOFF_AT=0 ;; esac
+  [ "${VERDICTS:-0}" -eq 0 ] && [ "$ROUTE_AT" -gt 0 ] && [ $(( NOW_S - ROUTE_AT )) -lt "$REVIEW_PENDING_MAX_S" ] \
+    && { [ "$HANDOFF_AT" -eq 0 ] || [ "$HANDOFF_AT" -lt "$ROUTE_AT" ]; } && REVIEW_PENDING=true
 fi
 
 if [ "$LEASE_LIVE" != "true" ] && [ "$REVIEW_PENDING" != "true" ]; then
+  FORGE_REPO="${FORGE_REPO:-$REPO}" FORGE_ISSUE="${FORGE_ISSUE:-$ISSUE}" FORGE_PR="${FORGE_PR:-$PR}" forge_emit liveness decision=PROCEED why=dead
   echo "LIVENESS: DEAD"; exit 0
 fi
 
 PRIOR=$(printf '%s' "$ISSUE_COMMENTS" | jq -rs --arg pr "pr=$PR" "[.[][] | select($TRUST) | select((.body // \"\") | startswith(\"<!-- FORGE:REMEDIATION_DEFERRED -->\")) | select((.body | split(\"\\n\") | index(\$pr)) != null)] | length" 2>/dev/null) || err "deferral records unreadable"
-if [ "${PRIOR:-0}" -ge "$MAX_DEFERRALS" ]; then echo "LIVENESS: EXHAUSTED ${PRIOR}"; exit 11; fi
+if [ "${PRIOR:-0}" -ge "$MAX_DEFERRALS" ]; then FORGE_REPO="${FORGE_REPO:-$REPO}" FORGE_ISSUE="${FORGE_ISSUE:-$ISSUE}" FORGE_PR="${FORGE_PR:-$PR}" forge_emit liveness decision=EXHAUSTED why=deferrals-${PRIOR}
+  echo "LIVENESS: EXHAUSTED ${PRIOR}"; exit 11; fi
 
 if [ "$LEASE_LIVE" = "true" ]; then KIND=lease; DETAIL="lease held by ${LEASE_BY} until ${LEASE_UNTIL}"
 else KIND=review; DETAIL="re-review of ${ROUTE_SHA} has no reviewer verdicts yet"; fi
@@ -93,4 +128,5 @@ lease_by=${LEASE_BY:-none}
 lease_until=${LEASE_UNTIL}"
 if [ -n "${DRY_RUN:-}" ]; then printf 'DRY_RUN: would post:\n%s\n' "$BODY"
 else gh issue comment "$ISSUE" -R "$REPO" --body "$BODY" >/dev/null 2>&1 || err "could not post deferral record"; fi
+FORGE_REPO="${FORGE_REPO:-$REPO}" FORGE_ISSUE="${FORGE_ISSUE:-$ISSUE}" FORGE_PR="${FORGE_PR:-$PR}" forge_emit liveness decision=DEFER why="$KIND"
 echo "LIVENESS: DEFER ${KIND} ${DETAIL}"; exit 10