forgedock 1.16.2 → 1.17.0

package/scripts/cost-report.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# cost-report.sh — pipeline token cost per ForgeDock version and repo (forge#3824).
+#
+# Reads the engine run logs (<runs-dir>/*.jsonl) and prints a markdown table, one row per
+# (version, repo): finished-run count n, mean/median cache-read tokens per issue, mean per
+# phase, remediated %, merged %, and cache-read tokens per merged issue.
+#
+# Rules:
+#   - A run counts only when finished: the last RUN_START..end slice of a log has a
+#     RUN_TERMINAL after any RUN_REOPEN / RUN_NEXT_CYCLE. A log is counted once.
+#   - Runs with no usage events, or with a hydrated (reconstructed) RUN_START, are excluded:
+#     they carry no usage and would drag the means down.
+#   - Tokens = usage.cache_read_input_tokens summed per phase over PHASE_ATTEMPT_USAGE when the
+#     phase has any (PHASE_COMMIT.usage is then cumulative, so it is not added again), else over
+#     PHASE_COMMIT and PHASE_FAILED (older logs).
+#     Per-phase means divide by n (a run that skipped a phase counts 0), so the phase
+#     columns add up to the per-issue mean. "merged" is RUN_TERMINAL.reason == "merged".
+#   - Version/repo come from RUN_START. Older logs lack them: repo becomes "unknown", and the
+#     version is estimated from the log's mtime against release times (marked with "~").
+#   - Groups with n < --min-n (default 10) are flagged low-n.
+#
+# Usage: bash scripts/cost-report.sh [--runs-dir DIR] [--last N] [--versions a,b] [--min-n N]
+#                                    [--release-times FILE]
+#   --runs-dir        default $FORGE_RUNS_DIR, else ~/.forge/runs
+#   --last N          only the N highest versions (unknown excluded)
+#   --versions        comma list of versions (a trailing "~" in the data is ignored)
+#   --release-times   file of "<version> <epoch-seconds>" lines; default: git tags v* of this repo
+# Exit: 0 report printed (also when there are no finished runs) | 2 bad usage / missing runs dir
+# Portable: bash 3.2, jq, POSIX stat/git.
+
+set -u
+
+RUNS_DIR="${FORGE_RUNS_DIR:-$HOME/.forge/runs}"
+LAST=""
+VERSIONS=""
+MIN_N=10
+REL_FILE=""
+
+die() { echo "cost-report: $1" >&2; exit 2; }
+is_uint() { case "$1" in ''|*[!0-9]*) return 1 ;; *) return 0 ;; esac; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --runs-dir) [ $# -ge 2 ] || die "--runs-dir needs a value"; RUNS_DIR="$2"; shift 2 ;;
+    --last) [ $# -ge 2 ] || die "--last needs a value"; LAST="$2"; shift 2 ;;
+    --versions) [ $# -ge 2 ] || die "--versions needs a value"; VERSIONS="$2"; shift 2 ;;
+    --min-n) [ $# -ge 2 ] || die "--min-n needs a value"; MIN_N="$2"; shift 2 ;;
+    --release-times) [ $# -ge 2 ] || die "--release-times needs a value"; REL_FILE="$2"; shift 2 ;;
+    -h|--help) sed -n '2,32p' "$0"; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[ -d "$RUNS_DIR" ] || die "runs dir not found: $RUNS_DIR"
+command -v jq >/dev/null 2>&1 || die "jq is required"
+is_uint "$MIN_N" || die "--min-n must be a non-negative integer"
+if [ -n "$LAST" ]; then is_uint "$LAST" || die "--last must be a non-negative integer"; fi
+if [ -n "$REL_FILE" ] && [ ! -f "$REL_FILE" ]; then die "release-times file not found: $REL_FILE"; fi
+
+# Release times: "<version> <epoch>" lines, from the file or this repo's v* tags (fail-soft: none).
+if [ -n "$REL_FILE" ]; then
+  REL_RAW=$(cat "$REL_FILE")
+else
+  ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+  REL_RAW=$(git -C "$ROOT" for-each-ref refs/tags --format='%(refname:short) %(creatordate:unix)' 2>/dev/null \
+    | sed -n 's/^v\([0-9][0-9.]*\) /\1 /p')
+fi
+REL_JSON=$(printf '%s\n' "$REL_RAW" | jq -R -s -c '
+  split("\n") | map(split(" ") | select(length == 2 and (.[1] | test("^[0-9]+$"))) | {v: .[0], t: (.[1] | tonumber)})
+  | sort_by(.t)')
+[ -n "$REL_JSON" ] || REL_JSON='[]'
+
+mtime_of() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo 0; }
+
+# Pass 1: one summary object per log (empty for logs that cannot be parsed or have no RUN_START).
+ROWS=""
+for f in "$RUNS_DIR"/*.jsonl; do
+  [ -f "$f" ] || continue
+  mt=$(mtime_of "$f")
+  row=$(jq -c -s --argjson mt "$mt" '
+    . as $all
+    | ([range(0; length) | select($all[.].event == "RUN_START")] | last) as $s
+    | if $s == null then empty else
+      $all[$s:] as $ev
+      | $ev[0] as $start
+      | ([range(0; $ev | length) | select($ev[.].event == "RUN_TERMINAL")] | last) as $t
+      | ([range(0; $ev | length) | select($ev[.].event == "RUN_REOPEN" or $ev[.].event == "RUN_NEXT_CYCLE")] | last) as $r
+      | ([$ev[] | select(.event == "PHASE_ATTEMPT_USAGE") | .phase] | unique) as $ap
+      | [$ev[] | select(((.event == "PHASE_ATTEMPT_USAGE")
+                         or ((.event == "PHASE_COMMIT" or .event == "PHASE_FAILED") and ((.phase as $p | $ap | index($p)) == null)))
+                        and (.usage | type) == "object")] as $u
+      | {
+          version: ($start.version // null), repo: ($start.repo // null), mt: $mt,
+          hydrated: ($start.hydrated == true),
+          finished: ($t != null and ($r == null or $t > $r)),
+          reason: (if $t == null then null else $ev[$t].reason end),
+          usage_events: ($u | length),
+          remediated: ([$ev[] | select(.event == "PHASE_COMMIT" and .phase == "remediate")] | length > 0),
+          cr: ([$u[] | .usage.cache_read_input_tokens // 0] | add // 0),
+          out: ([$u[] | .usage.output_tokens // 0] | add // 0),
+          phase: ($u | group_by(.phase) | map({key: (.[0].phase // "other"), value: ([.[] | .usage.cache_read_input_tokens // 0] | add)}) | from_entries)
+        }
+      end' "$f" 2>/dev/null) || row=""
+  [ -n "$row" ] && ROWS="$ROWS$row
+"
+done
+
+printf '%s' "$ROWS" | jq -s -r \
+  --argjson rel "$REL_JSON" --argjson minn "$MIN_N" \
+  --arg last "$LAST" --arg versions "$VERSIONS" '
+  def vkey: (sub("~$"; "") | split(".") | map(tonumber? // 0));
+  def mean: if length == 0 then 0 else add / length end;
+  def median: sort | if length == 0 then 0 elif length % 2 == 1 then .[length / 2 | floor] else (.[length / 2 - 1] + .[length / 2]) / 2 end;
+  def k: ((. / 1000) | round | tostring) + "k";
+  def pct: ((. * 100) | round | tostring) + "%";
+  def ver($mt): if .version != null then .version
+           else ([$rel[] | select(.t <= $mt)] | last | if . == null then "unknown" else .v + "~" end) end;
+
+  . as $rows
+  | ($rows | map(select(.finished | not)) | length) as $unfinished
+  | ($rows | map(select(.finished and (.hydrated or .usage_events == 0))) | length) as $nousage
+  | [ $rows[] | select(.finished and (.hydrated | not) and .usage_events > 0)
+      | . as $r | $r + {ver: ($r | ver($r.mt)), repo: ($r.repo // "unknown")} ] as $runs
+  | ($versions | split(",") | map(select(length > 0))) as $vf
+  | ($runs | map(.ver | select(. != "unknown")) | unique | sort_by(vkey)) as $vers
+  | (if $last == "" then $vers else ($vers | .[(length - ($last | tonumber) | if . < 0 then 0 else . end):]) end) as $keep
+  | [ $runs[] | select((.ver | IN($keep[])) or ($last == "" and .ver == "unknown"))
+      | select($vf == [] or ((.ver | sub("~$"; "")) | IN($vf[]))) ]
+  | group_by([.ver, .repo]) | sort_by(.[0].ver | vkey) as $groups
+  | "| Version | Repo | n | Cache-read/issue mean | median | investigate | build | review | remediate | close | Remediated | Merged | Per merged issue | Confidence |",
+    "|---|---|---|---|---|---|---|---|---|---|---|---|---|---|",
+    ( $groups[] | . as $g | length as $n
+      | ([.[] | select(.reason == "merged")] | length) as $m
+      | (map(.cr) | add) as $tot
+      | def pm($p): (map(.phase[$p] // 0) | add) / $n;
+        "| \($g[0].ver) | \($g[0].repo) | \($n) | \((map(.cr) | mean) | k) | \((map(.cr) | median) | k)"
+        + " | \(pm("investigate") | k) | \(pm("build") | k) | \(pm("review") | k) | \(pm("remediate") | k) | \(pm("close") | k)"
+        + " | \(([.[] | select(.remediated)] | length) / $n | pct) | \($m / $n | pct)"
+        + " | \(if $m == 0 then "n/a" else ($tot / $m | k) end)"
+        + " | \(if $n < $minn then "low-n (<\($minn))" else "ok" end) |" ),
+    "",
+    "Finished runs only; tokens are cache-read per issue. Excluded: \($unfinished) unfinished, \($nousage) without usage data (hydrated or empty). \"~\" = version estimated from log mtime; \"unknown\" = no version available."
+  '

package/scripts/cost-report.test.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# cost-report.test.sh — cases for scripts/cost-report.sh (forge#3824).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+S="$HERE/cost-report.sh"
+FIX="$HERE/fixtures/cost-report"
+PASS=0; FAILN=0
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+has() { # name text needle
+  case "$2" in *"$3"*) ok ;; *) bad "$1 (missing: $3)"; printf '%s\n' "$2" | sed 's/^/    /' ;; esac
+}
+hasnt() { # name text needle
+  case "$2" in *"$3"*) bad "$1 (unexpected: $3)" ;; *) ok ;; esac
+}
+
+RUNS="$TMP/runs"; mkdir -p "$RUNS"
+cp "$FIX"/*.jsonl "$RUNS"/
+# Old logs carry no version: their mtime (UTC) is mapped to the release active at that time.
+TZ=UTC touch -t 200201010000 "$RUNS/old-log-no-version.jsonl"
+printf '1.0.0 1000000000\n2.0.0 1100000000\n' > "$TMP/releases.txt"
+
+OUT=$(bash "$S" --runs-dir "$RUNS" --release-times "$TMP/releases.txt"); rc=$?
+[ "$rc" -eq 0 ] && ok || bad "exit 0 on a valid runs dir (rc=$rc)"
+
+# Repo split: o/a (3 finished runs) and o/b (1) are separate rows.
+ROW_A=$(printf '%s\n' "$OUT" | grep '^| 2\.0\.0 | o/a |')
+ROW_B=$(printf '%s\n' "$OUT" | grep '^| 2\.0\.0 | o/b |')
+[ -n "$ROW_A" ] && ok || bad "row for 2.0.0 o/a"
+[ -n "$ROW_B" ] && ok || bad "row for 2.0.0 o/b"
+
+# o/a: unfinished (no terminal, reopened) and hydrated runs are excluded, so n=3.
+has "o/a n=3 (unfinished and hydrated excluded)" "$ROW_A" "| 2.0.0 | o/a | 3 |"
+# totals 330k, 560k, 100k: mean 330k, median 330k
+has "o/a mean and median" "$ROW_A" "| 330k | 330k |"
+# per-phase means divide by n: investigate 30k/3, build 390k/3, review 500k/3, remediate 40k/3, close 30k/3
+has "o/a per-phase means" "$ROW_A" "| 10k | 130k | 167k | 13k | 10k |"
+# 1 of 3 remediated, 2 of 3 merged (needs-human is not merged)
+has "o/a remediated and merged rates" "$ROW_A" "| 33% | 67% |"
+# per merged issue: 990k total over 2 merged runs
+has "o/a tokens per merged issue" "$ROW_A" "| 495k |"
+has "o/a low-n flag" "$ROW_A" "low-n (<10)"
+has "o/b single run per-merged math" "$ROW_B" "| 2.0.0 | o/b | 1 | 1000k | 1000k |"
+has "o/b per merged" "$ROW_B" "| 100% | 1000k |"
+hasnt "unfinished usage never counted" "$OUT" "9999k"
+
+# o/c: new-style log (PHASE_ATTEMPT_USAGE). Per-phase attempts are summed once: investigate 10k + build 100k + 50k
+# = 160k; the cumulative PHASE_COMMIT (150k) and the PHASE_FAILED (100k) must not be added on top.
+ROW_C=$(printf '%s\n' "$OUT" | grep '^| 2\.0\.0 | o/c |')
+has "o/c attempt events not double counted" "$ROW_C" "| 2.0.0 | o/c | 1 | 160k | 160k |"
+
+# Old log: version estimated from mtime (marked ~), repo unknown.
+has "old-log fallback" "$OUT" "| 1.0.0~ | unknown | 1 | 70k |"
+has "excluded footer" "$OUT" "Excluded: 2 unfinished, 1 without usage data"
+
+# --min-n lowers the flag threshold.
+OUT2=$(bash "$S" --runs-dir "$RUNS" --release-times "$TMP/releases.txt" --min-n 3)
+has "min-n 3 marks o/a ok" "$(printf '%s\n' "$OUT2" | grep '^| 2\.0\.0 | o/a |')" "| ok |"
+
+# --last / --versions filtering.
+OUT3=$(bash "$S" --runs-dir "$RUNS" --release-times "$TMP/releases.txt" --last 1)
+hasnt "--last 1 drops the older estimated version" "$OUT3" "1.0.0~"
+has "--last 1 keeps the newest" "$OUT3" "| 2.0.0 | o/a |"
+OUT4=$(bash "$S" --runs-dir "$RUNS" --release-times "$TMP/releases.txt" --versions 1.0.0)
+has "--versions matches an estimated version" "$OUT4" "| 1.0.0~ |"
+hasnt "--versions excludes others" "$OUT4" "| 2.0.0 |"
+
+# Fail closed: missing runs dir exits 2; empty dir still reports (header only).
+bash "$S" --runs-dir "$TMP/nope" >/dev/null 2>&1; [ $? -eq 2 ] && ok || bad "missing runs dir exits 2"
+bash "$S" --bogus >/dev/null 2>&1; [ $? -eq 2 ] && ok || bad "unknown flag exits 2"
+mkdir "$TMP/empty"
+OUT5=$(bash "$S" --runs-dir "$TMP/empty" --release-times "$TMP/releases.txt"); rc=$?
+[ "$rc" -eq 0 ] && ok || bad "empty runs dir exits 0"
+has "empty dir footer" "$OUT5" "Excluded: 0 unfinished"
+
+echo "cost-report.test: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]

package/scripts/diff-size.sh

@@ -30,6 +30,9 @@
 # Exit: 0 measured (even when over); 2 usage or git failure with EMPTY stdout (fail closed: unknown is not zero).
 
 set -euo 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() { :; }
 
 REPO_PATH=""; BASE=""; THRESHOLD="1000"; EXTRA=()
 die() { echo "diff-size.sh: $*" >&2; exit 2; }
@@ -112,6 +115,8 @@ echo "new_lines=$NEWL"
 echo "test_lines=$TESTL"
 echo "cohesive_lines=$COHL"
 echo "cohesive=$COHESIVE"
+_res=OK; if [ "$COHESIVE" = true ]; then _res=COHESIVE; elif [ "$OVER" = true ]; then _res=OVER; fi
+forge_emit diff_size lines="$TOTAL" excluded="$EXCL" threshold="$THRESHOLD" result="$_res"
 if [ -n "$LIST" ]; then
   printf '%s' "$LIST" | sort -t' ' -k1,1nr | head -n 10 | sed 's/^/top=/' || true
 fi

package/scripts/doctor-pipeline-state.sh

@@ -49,6 +49,8 @@
 #       PRIOR_GIST annotations in recent issue comments)
 #   I9  Issues stuck in workflow:remediating beyond threshold (the state must
 #       never outlive its remediation run)
+#   I10 Issues in workflow:engine-error that also carry another in-flight
+#       workflow:* label, or that sit there beyond threshold
 #
 # /pipeline-health should consume this script's JSON output rather than
 # re-discovering state from scratch.
@@ -357,6 +359,47 @@ while IFS= read -r row; do
   fi
 done < <(echo "$REMEDIATING" | jq -c '.[]')
 
+# ---------------------------------------------------------------------------
+# I10: Issues stuck in workflow:engine-error
+# ---------------------------------------------------------------------------
+# engine-error is a terminal projection: it must not coexist with another
+# in-flight workflow:* label (stranded state) and must not sit unrecovered past
+# the threshold. Same fail-inconclusive pattern as I9.
+if ! ENGINE_ERRORS=$(gh issue list $GH_FLAG \
+  --state open --label "workflow:engine-error" \
+  --limit 100 \
+  --json number,title,updatedAt,labels 2>"$GH_STDERR_TMP"); then
+  echo "WARNING: gh issue list failed for workflow:engine-error — I10 check inconclusive, skipping (not treated as empty): $(cat "$GH_STDERR_TMP")" >&2
+  add_skip "I10" "all" "gh issue list failed: $(bounded_reason "$(cat "$GH_STDERR_TMP")")"
+  ENGINE_ERRORS="[]"
+fi
+
+while IFS= read -r row; do
+  num=$(echo "$row" | jq -r '.number')
+  labels=$(echo "$row" | jq -c '[.labels[].name]')
+  if has_terminal_label "$labels"; then
+    continue
+  fi
+  updated=$(echo "$row" | jq -r '.updatedAt')
+  hours=$(hours_since "$updated")
+  other=$(echo "$labels" | jq -r '[.[] | select(startswith("workflow:") and . != "workflow:engine-error")] | first // empty')
+  if [ -n "$other" ]; then
+    add_finding \
+      "stuck_engine_error" "warning" \
+      "$num" "workflow:engine-error" "$hours" \
+      "FORGE:STATE" \
+      "forgedock run-issue $num --retry" \
+      "Issue #$num carries workflow:engine-error together with $other (stranded state). Remove the stale label or recover with forgedock run-issue $num --retry"
+  elif [ "$hours" -ge "$STUCK_HOURS" ]; then
+    add_finding \
+      "stuck_engine_error" "warning" \
+      "$num" "workflow:engine-error" "$hours" \
+      "FORGE:STATE" \
+      "forgedock run-issue $num --retry" \
+      "Issue #$num stuck in workflow:engine-error for ${hours}h (threshold: ${STUCK_HOURS}h). Recover with forgedock run-issue $num --retry"
+  fi
+done < <(echo "$ENGINE_ERRORS" | jq -c '.[]')
+
 # ---------------------------------------------------------------------------
 # I4: Issues in workflow:building with no FORGE:BUILDER annotation
 # ---------------------------------------------------------------------------

package/scripts/file-deferred-followups.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# file-deferred-followups.sh — file ALL deferred out-of-scope items of one build as ONE follow-up issue.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# The builder decides fold-vs-defer (judgment, build.md B2.0); this script does the mechanics for the items
+# that stay deferred: trusted lookup of an open follow-up carrying <!-- FORGE:DEFERRED_FROM: #N -->, append the
+# missing items to it as checklist entries (exact path match), or create ONE issue with a checklist.
+#
+# Usage: file-deferred-followups.sh --parent N --repo OWNER/REPO [--items FILE|-] [--folded N]
+#   items TSV, one per line: <path> TAB <why> TAB <known-flaw flag: known-flaw|1|yes|true, else empty>
+# Env: DRY_RUN (non-empty: no create/edit, issue number 0), FORGE_TRAIL_TRUSTED_ASSOCIATIONS (default
+#      OWNER,MEMBER,COLLABORATOR), FORGE_TRAIL_TRUSTED_LOGINS (default empty), FORGE_DEFERRED_RETRY_SLEEP (secs).
+# Stdout: `path<TAB>issue` per item, then DEFERRED_TELEMETRY deferred_items=N folded=N batched_into=#M filed=N.
+# Exit: 0 ok | 2 usage | 3 lookup failed (DEFERRED_LOOKUP=FAILED) | 4 create/append failed (DEFERRED_FILE=FAILED).
+# A failed lookup is never "none found". bash 3.2 portable.
+
+set -uo pipefail
+
+PARENT=""; REPO=""; ITEMS="-"; FOLDED=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --parent|--repo|--items|--folded)
+      [ $# -ge 2 ] || { echo "file-deferred-followups: $1 requires a value" >&2; exit 2; }
+      case "$1" in --parent) PARENT="$2" ;; --repo) REPO="$2" ;; --items) ITEMS="$2" ;; --folded) FOLDED="$2" ;; esac
+      shift 2 ;;
+    *) echo "usage: file-deferred-followups.sh --parent N --repo OWNER/REPO [--items FILE|-] [--folded N]" >&2; exit 2 ;;
+  esac
+done
+case "$PARENT" in ''|*[!0-9]*) echo "file-deferred-followups: --parent must be a number" >&2; exit 2 ;; esac
+case "$FOLDED" in ''|*[!0-9]*) FOLDED=0 ;; esac
+[ -n "$REPO" ] || { echo "file-deferred-followups: --repo required" >&2; exit 2; }
+if [ "$ITEMS" != "-" ] && [ ! -f "$ITEMS" ]; then echo "file-deferred-followups: items file not found: $ITEMS" >&2; exit 2; fi
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/deferred-followups.XXXXXX") || exit 2
+trap 'rm -rf "$TMP"' EXIT
+if [ "$ITEMS" = "-" ]; then cat > "$TMP/items.raw"; else cat "$ITEMS" > "$TMP/items.raw"; fi
+
+# Normalise: drop blank lines and duplicate paths (first wins), strip backticks from the path.
+# Internal file uses a non-whitespace separator (US, \x1f): a tab IFS collapses an empty `why` and drops the known-flaw flag.
+SEP=$(printf '\037')
+: > "$TMP/items"
+while IFS= read -r line || [ -n "$line" ]; do
+  # Split on TAB by hand: `IFS=$'\t' read` would collapse an empty why field and shift the flag into it.
+  p="${line%%$'\t'*}"; rest=""; w=""; k=""
+  case "$line" in *$'\t'*) rest="${line#*$'\t'}"; w="${rest%%$'\t'*}"; case "$rest" in *$'\t'*) k="${rest#*$'\t'}" ;; esac ;; esac
+  p=$(printf '%s' "${p:-}" | tr -d '`' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+  [ -n "$p" ] || continue
+  if cut -d "$SEP" -f1 "$TMP/items" | grep -qxF -- "$p"; then continue; fi
+  case "${k:-}" in known-flaw|1|yes|true) k="known-flaw" ;; *) k="" ;; esac
+  w=$(printf '%s' "${w:-}" | tr '\r\n' '  ')
+  printf '%s%s%s%s%s\n' "$p" "$SEP" "$w" "$SEP" "$k" >> "$TMP/items"
+done < "$TMP/items.raw"
+TOTAL=$(wc -l < "$TMP/items" | tr -d ' ')
+
+MARKER="<!-- FORGE:DEFERRED_FROM: #${PARENT} -->"
+TRUSTED_ASSOC="${FORGE_TRAIL_TRUSTED_ASSOCIATIONS-OWNER,MEMBER,COLLABORATOR}"
+TRUSTED_LOGINS="${FORGE_TRAIL_TRUSTED_LOGINS-}"
+
+finish() { # $1 = batched_into number or empty, $2 = filed count
+  local into="none"; [ -n "$1" ] && into="#$1"
+  local line="DEFERRED_TELEMETRY deferred_items=${TOTAL} folded=${FOLDED} batched_into=${into} filed=$2"
+  echo "$line"
+  # #3834 emitter (scripts/lib/telemetry.sh): optional, never blocks, never changes stdout or the exit code.
+  local d; d=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+  if [ -f "$d/lib/telemetry.sh" ]; then
+    FORGE_ISSUE="${FORGE_ISSUE:-$PARENT}" FORGE_REPO="${FORGE_REPO:-$REPO}" \
+      bash "$d/lib/telemetry.sh" deferred_followups deferred_items="$TOTAL" folded="$FOLDED" \
+      batched_into="${1:-none}" filed="$2" >/dev/null 2>&1 </dev/null || true
+  fi
+}
+
+# --- Trusted lookup (author predicate applied before path match), one retry ---------------------------------
+do_lookup() {
+  gh api -X GET search/issues -f per_page=50 \
+    -f q="\"FORGE:DEFERRED_FROM: #${PARENT}\" in:body repo:${REPO} is:issue is:open" 2>/dev/null \
+  | jq -c --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$MARKER" '
+      ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
+      | ($logins | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $L
+      | [.items[]
+          | select(((.author_association // "") as $x | $A | index($x) != null)
+                   or ((.user.type // "") == "Bot")
+                   or ((.user.login // "") as $x | $L | index($x) != null))
+          | select((.body // "") | contains($m))
+          | {number, body: (.body // "")}]
+      | sort_by(.number)' 2>/dev/null
+}
+LOOKUP=""
+for attempt in 1 2; do
+  LOOKUP=$(do_lookup) && [ -n "$LOOKUP" ] && break
+  LOOKUP=""
+  [ "$attempt" = 1 ] && sleep "${FORGE_DEFERRED_RETRY_SLEEP:-2}"
+done
+if [ -z "$LOOKUP" ]; then
+  echo "DEFERRED_LOOKUP=FAILED"
+  exit 3
+fi
+
+# Checklist line for one item. Path always backticked so review-pr 6B.5 `contains` verification holds.
+entry() { # path why flag
+  local l="- [ ] \`$1\`"
+  [ -n "$3" ] && l="$l **known-flaw**"
+  [ -n "$2" ] && l="$l — $2"
+  printf '%s\n' "$l"
+}
+has_entry() { # body-file path : exact checklist-line match, not substring
+  grep -qE '^- \[[ xX]\] `' "$1" 2>/dev/null || return 1
+  grep -F -- "\`$2\`" "$1" | grep -qE "^- \[[ xX]\] \`$(printf '%s' "$2" | sed 's/[][\.*^$+?(){}|]/\\&/g')\`( |\$)"
+}
+
+NUM=$(printf '%s' "$LOOKUP" | jq -r 'first | .number // empty' 2>/dev/null)
+
+if [ -n "$NUM" ]; then
+  # Re-read the body immediately before editing (parallel builds of the same parent), then append what is missing.
+  if ! gh api "repos/${REPO}/issues/${NUM}" --jq '.body // ""' > "$TMP/body" 2>/dev/null; then
+    echo "DEFERRED_FILE=FAILED"; exit 4
+  fi
+  : > "$TMP/add"
+  while IFS="$SEP" read -r p w k; do
+    has_entry "$TMP/body" "$p" || entry "$p" "$w" "$k" >> "$TMP/add"
+  done < "$TMP/items"
+  if [ -s "$TMP/add" ]; then
+    { cat "$TMP/body"; printf '\n### Added by a later build of #%s\n\n' "$PARENT"; cat "$TMP/add"; } > "$TMP/newbody"
+    if [ -n "${DRY_RUN:-}" ]; then
+      echo "DRY_RUN: gh issue edit $NUM (append $(wc -l < "$TMP/add" | tr -d ' ') item(s))" >&2
+    elif ! gh issue edit "$NUM" -R "$REPO" --body-file "$TMP/newbody" >/dev/null 2>&1; then
+      echo "DEFERRED_FILE=FAILED"; exit 4
+    fi
+  fi
+  while IFS="$SEP" read -r p w k; do printf '%s\t%s\n' "$p" "$NUM"; done < "$TMP/items"
+  finish "$NUM" 0
+  exit 0
+fi
+
+[ "$TOTAL" -gt 0 ] || { finish "" 0; exit 0; }
+
+# --- Create ONE issue with a checklist for every item ---------------------------------------------------------
+{
+  printf '## Problem\n\n'
+  printf 'Deferred from #%s: the items below were declared out of scope in its contract and are tracked here, in one issue, instead of surfacing later as review findings.\n\n' "$PARENT"
+  printf '## Affected Files\n\n'
+  while IFS="$SEP" read -r p w k; do printf -- '- `%s`\n' "$p"; done < "$TMP/items"
+  printf '\n## Acceptance Criteria\n\n'
+  while IFS="$SEP" read -r p w k; do entry "$p" "$w" "$k"; done < "$TMP/items"
+  printf '\n%s\n' "$MARKER"
+} > "$TMP/newissue"
+
+if [ -n "${DRY_RUN:-}" ]; then
+  echo "DRY_RUN: gh issue create (follow-up: ${TOTAL} deferred item(s) from #${PARENT})" >&2
+  NUM=0
+else
+  URL=$(gh issue create -R "$REPO" --title "follow-up: ${TOTAL} deferred item(s) (deferred from #${PARENT})" \
+    --body-file "$TMP/newissue" 2>/dev/null) || URL=""
+  NUM=$(printf '%s' "$URL" | grep -oE '[0-9]+$' | tail -n 1)
+  [ -n "$NUM" ] || { echo "DEFERRED_FILE=FAILED"; exit 4; }
+fi
+while IFS="$SEP" read -r p w k; do printf '%s\t%s\n' "$p" "$NUM"; done < "$TMP/items"
+finish "$NUM" 1
+exit 0

package/scripts/file-deferred-followups.test.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# file-deferred-followups.test.sh — stubbed-gh tests for scripts/file-deferred-followups.sh
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+S="$HERE/file-deferred-followups.sh"
+T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
+mkdir "$T/bin"
+export FORGE_DEFERRED_RETRY_SLEEP=0
+export GH_LOG="$T/gh.log" SEARCH_JSON="$T/search.json" ISSUE_BODY="$T/issue.body"
+
+cat > "$T/bin/gh" <<'MOCK'
+#!/usr/bin/env bash
+echo "$*" >> "$GH_LOG"
+case "$1 $2" in
+  "api -X") [ -n "${LOOKUP_FAIL:-}" ] && exit 1; cat "$SEARCH_JSON"; exit 0 ;;
+  "issue create") [ -n "${CREATE_FAIL:-}" ] && exit 1; echo "https://github.com/o/r/issues/901"; exit 0 ;;
+  "issue edit")
+    [ -n "${EDIT_FAIL:-}" ] && exit 1
+    while [ $# -gt 0 ]; do [ "$1" = "--body-file" ] && cp "$2" "$ISSUE_BODY.edited"; shift; done; exit 0 ;;
+esac
+case "$1" in api) cat "$ISSUE_BODY"; exit 0 ;; esac
+exit 1
+MOCK
+chmod +x "$T/bin/gh"; export PATH="$T/bin:$PATH"
+
+PASS=0; FAIL=0
+ok() { PASS=$((PASS+1)); echo "PASS: $1"; }
+bad() { FAIL=$((FAIL+1)); echo "FAIL: $1"; }
+check() { if eval "$2"; then ok "$1"; else bad "$1"; fi; }
+reset() { : > "$GH_LOG"; rm -f "$ISSUE_BODY.edited"; unset LOOKUP_FAIL CREATE_FAIL EDIT_FAIL DRY_RUN; echo '{"items":[]}' > "$SEARCH_JSON"; }
+printf 'a/x.sh\twhy a\t\nb/y.sh\twhy b\tknown-flaw\nc/z.sh\twhy c\t\n' > "$T/items.tsv"
+
+# 1. N items -> exactly one create
+reset
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" --folded 2); RC=$?
+check "create: rc 0" "[ $RC -eq 0 ]"
+check "create: one issue create for 3 items" "[ \$(grep -c '^issue create' '$GH_LOG') -eq 1 ]"
+check "create: rows share issue" "[ \$(printf '%s\n' \"\$OUT\" | grep -c '901\$') -ge 3 ]"
+check "create: telemetry" "printf '%s' \"\$OUT\" | grep -q 'DEFERRED_TELEMETRY deferred_items=3 folded=2 batched_into=#901 filed=1'"
+
+# 2. append to existing trusted open issue; exact path match
+reset
+printf '## Affected Files\n- `a/x.sh`\n\n- [ ] `a/x.sh.bak` — other\n<!-- FORGE:DEFERRED_FROM: #10 -->\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
+check "append: rc 0, no create" "[ $RC -eq 0 ] && ! grep -q '^issue create' '$GH_LOG'"
+check "append: telemetry batched into 77 filed=0" "printf '%s' \"\$OUT\" | grep -q 'batched_into=#77 filed=0'"
+check "append: all three added (substring .bak does not dedup a/x.sh)" "[ \$(grep -c '^- \[ \] \`' '$ISSUE_BODY.edited') -eq 4 ]"
+check "append: known-flaw flagged" "grep -q 'b/y.sh. \*\*known-flaw\*\*' '$ISSUE_BODY.edited'"
+
+# 2b. empty why + known-flaw: the flag must survive (a whitespace IFS would collapse the empty field)
+reset
+printf 'd/w.sh\t\tknown-flaw\n' > "$T/emptywhy.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/emptywhy.tsv" >/dev/null; RC=$?
+rm -f "$ISSUE_BODY.edited"; printf 'x\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/emptywhy.tsv"); RC=$?
+check "empty-why: append keeps known-flaw flag" "[ $RC -eq 0 ] && grep -q 'd/w.sh. \*\*known-flaw\*\*' '$ISSUE_BODY.edited'"
+
+# 2c. missing option value -> usage exit 2
+bash "$S" --parent >/dev/null 2>&1; RC=$?
+check "missing option value: rc 2" "[ $RC -eq 2 ]"
+
+# 3. already-listed path is not duplicated; nothing to add -> no edit
+reset
+printf -- '- [ ] `a/x.sh` — w\n- [x] `b/y.sh`\n- [ ] `c/z.sh`\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"MEMBER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null; RC=$?
+check "idempotent: no edit, no create on resume" "[ $RC -eq 0 ] && ! grep -qE '^issue (edit|create)' '$GH_LOG'"
+
+# 4. untrusted match ignored -> new issue
+reset
+echo '{"items":[{"number":66,"author_association":"NONE","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv")
+check "untrusted: ignored, create filed" "grep -q '^issue create' '$GH_LOG' && printf '%s' \"\$OUT\" | grep -q 'filed=1'"
+
+# 5. lookup failure -> FAILED, nothing filed
+reset; export LOOKUP_FAIL=1
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
+check "lookup failure: rc 3, DEFERRED_LOOKUP=FAILED, no create" "[ $RC -eq 3 ] && printf '%s' \"\$OUT\" | grep -q DEFERRED_LOOKUP=FAILED && ! grep -q '^issue create' '$GH_LOG'"
+
+# 6. create / edit failure not counted as success
+reset; export CREATE_FAIL=1
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
+check "create failure: rc 4, no telemetry" "[ $RC -eq 4 ] && ! printf '%s' \"\$OUT\" | grep -q DEFERRED_TELEMETRY"
+reset; export EDIT_FAIL=1
+printf 'x\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
+check "edit failure: rc 4, no telemetry" "[ $RC -eq 4 ] && ! printf '%s' \"\$OUT\" | grep -q DEFERRED_TELEMETRY"
+
+# 7. DRY_RUN
+reset; export DRY_RUN=1
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" 2>/dev/null)
+check "dry-run: no create" "! grep -q '^issue create' '$GH_LOG' && printf '%s' \"\$OUT\" | grep -q 'filed=1'"
+
+# 8. empty items, usage errors
+reset
+OUT=$(printf '' | bash "$S" --parent 10 --repo o/r)
+check "empty: no create, deferred_items=0" "! grep -q '^issue create' '$GH_LOG' && printf '%s' \"\$OUT\" | grep -q 'deferred_items=0'"
+bash "$S" --repo o/r >/dev/null 2>&1; check "usage: missing parent rc 2" "[ $? -eq 2 ]"
+
+echo "passed=$PASS failed=$FAIL"
+[ "$FAIL" -eq 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}}