forgedock 1.24.4 → 1.25.0

package/docs/OUTCOME-CODES.md

@@ -43,12 +43,19 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `infra.disk_quota` | Disk full or quota exhausted (EDQUOT/ENOSPC, errno -28/-122); retryable infra failure, never `needs-human` | engine | Runner error text |
 | `infra.cli_spawn_transient` | CLI spawn failed transiently before the child ran (ETIMEDOUT, EAGAIN, ENOMEM, EMFILE); retried with backoff on a separate bounded counter that does not consume a phase attempt | engine | `err.code` `CLI_SPAWN_TRANSIENT` |
 | `cli.timeout` | CLI child ran and was killed at the wall-clock limit; a normal attempt (consumes one of `maxAttempts`), usage recorded when the CLI emitted any | engine | `err.code` `CLI_TIMEOUT` |
+| `cli.spawn_failed` | The CLI could not be started for a reason that repeats on every rerun (`E2BIG` argv too large, `ENOENT`/`EACCES`/`ENOEXEC` binary missing or not executable, `ENAMETOOLONG`). Core work-on ends `needs-human` with this code instead of `engine-error`, so `forgedock orchestrate` does not spend its relaunch on it | lean, engine | `err.code` `CLI_SPAWN_FAILED` (E2BIG) or `err.spawnDeterministic` (other errnos keep their `err.code`); `err.spawnErrno` holds the errno |
 | `lease.held` | Another live agent holds the issue lease | engine | Foreign live lease on acquire |
-| `dependency.open` | A trusted `**Depends on**: #N` dependency is still open, so the run was refused before any state write | engine | Trusted issue body `**Depends on**` line + the dependency issue's open state |
-| `dependency.unreadable` | The issue body or a declared dependency could not be read, so the run was refused (fail closed) | engine | Failed or unparsable `gh api` read |
+| `dependency.open` | A dependency is still open: a trusted `**Depends on**: #N` line refused the run before any state write, or the core builder reported `block.kind: "dependency"` naming an issue that is open. Carries `dependencies`; never `needs-human`. `forgedock orchestrate` adds the edge and requeues the issue behind it, without skipping dependents | engine, lean | Trusted `**Depends on**` line, or `result.json` `block.issues`, + the dependency issue's live open state |
+| `dependency.unreadable` | The issue body or a declared dependency could not be read, so the run was refused (fail closed) | engine, lean | Failed or unparsable `gh api` / `gh issue view` read |
+| `dependency.blocked` | Core work-on: the builder's dependency is open and itself labelled `needs-human`. Terminal reason `dependency-blocked` (blocked by #X); this issue is not labelled `needs-human` | lean | `result.json` `block.kind: "dependency"` + the dependency's `needs-human` label |
+| `lane.mismatch` | Core work-on: `--lane` differs from the lane worked out from the issue (milestone → `branches.feature_pattern`, else `branches.staging`); refused before any lease, comment or worktree. `--lane-override` forces it and is recorded in the trajectory. A resumed PR whose base is not the lane is refused the same way before merge | lean | Issue milestone + forge.yaml `branches`, or the open PR's `baseRefName` |
+| `lane.default_branch` | Core work-on: the requested or resolved lane is the default (production) branch (forge.yaml `branches.default` or the GitHub default branch); never a lane, refused at every entry point and before PR create and merge | lean, cli | forge.yaml `branches.default`, `gh repo view` `defaultBranchRef` |
+| `lane.branch_missing` | Core work-on: the lane branch (e.g. `milestone/<slug>`) does not exist on origin; fail closed | lean | `git ls-remote --heads origin` |
+| `lane.unresolved` | Core work-on: the lane could not be worked out (milestone or default branch unreadable, empty milestone slug, bad `feature_pattern`); fail closed | lean | Failed `gh` read or config |
 | `invalid` | Issue is invalid or in a divergent closed state | investigate, engine | `INVESTIGATION:INVALID` marker, or live snapshot |
-| `decomposed` | Issue was decomposed into sub-issues | investigate, decompose | `FORGE:DECOMPOSED` or the decomposition assessment |
-| `builder.blocked` | Core work-on: the builder reported it cannot proceed without a human decision (design, credentials, infra) | lean | `result.json` status `blocked` |
+| `decomposed` | Issue was decomposed into sub-issues. In core work-on, the builder reported `block.kind: "split-required"`; the engine files the sub-issues (`**Parent**` and `**Depends on**` lines) and returns them as `subissues` for `forgedock orchestrate` to run | investigate, decompose, lean | `FORGE:DECOMPOSED` or the decomposition assessment; `result.json` `block.subissues` |
+| `builder.blocked` | Core work-on: the builder reported an external action agents cannot take, or a product decision too critical for agents: `block.kind: "human"` with `why` one of `credentials`, `spend`, `promotion`, `customer`, `product-decision`. An upstream issue, a needed split, or prod data that monitoring access can read never count | lean | `result.json` status `blocked` + typed `block` |
+| `builder.block_untyped` | Core work-on: the builder stayed `blocked` without a valid typed reason (missing `block`, a non-human `why` such as prod data, or a dependency that is not open) after one corrective resume | lean | `result.json` status `blocked`, twice |
 | `builder.no_evidence` | Core work-on: the builder reported invalid/already-fixed without file:line evidence, so the issue was not closed | lean | `result.json` with empty `evidence` |
 | `builder.no_commit` | Core work-on: the builder made no commit for a fix | lean | No changed files after the builder session |
 | `review.failed` | Core work-on: the fix/regression review failed twice (or could not resume the builder) | lean | Reviewer verdict FAIL |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.24.4",
+  "version": "1.25.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/code-index.sh

@@ -154,6 +154,29 @@ fi
 echo "INFO: Building code index for HEAD ${HEAD_SHA:0:8}..."
 mkdir -p "$CACHE_DIR"
 
+# ---------------------------------------------------------------------------
+# Step 0: File list (forge#4126)
+# ---------------------------------------------------------------------------
+# Enumerate files ONCE, from the git index when available: a filesystem walk also descends into nested
+# worktrees (.forge/worktrees, .claude/worktrees), virtualenvs and build output inside the checkout —
+# ~30x the tracked tree on a real repo. Outside git, fall back to a find that prunes those directories.
+# Every step below reads this list (paths relative to REPO_PATH); none walks the tree itself.
+FILE_LIST="${CACHE_DIR}/.files"
+if command -v git >/dev/null 2>&1 && git -C "$REPO_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  git -C "$REPO_PATH" -c core.quotepath=off ls-files > "$FILE_LIST" 2>/dev/null || true
+else
+  (cd "$REPO_PATH" && find . \( -name .git -o -name node_modules -o -name __pycache__ -o -name .forge \
+    -o -name .claude -o -name .venv -o -name venv \) -prune -o -type f -print 2>/dev/null | sed 's|^\./||') \
+    > "$FILE_LIST" || true
+fi
+
+# src_files <ext>... — absolute paths of listed files with one of the given extensions.
+src_files() {
+  local re
+  re="\\.($(IFS='|'; echo "$*"))\$"
+  grep -E "$re" "$FILE_LIST" 2>/dev/null | awk -v p="$REPO_PATH" '{print p "/" $0}' || true
+}
+
 # ---------------------------------------------------------------------------
 # Step 1: Symbol extraction
 # ---------------------------------------------------------------------------
@@ -163,12 +186,13 @@ SYMBOLS_FILE="${CACHE_DIR}/symbols.tsv"
 echo "INFO: Extracting symbols..."
 
 if command -v ctags >/dev/null 2>&1; then
-  # Use ctags for precise symbol extraction
   # --fields=+ne adds line number and end-of-scope — portable across universal-ctags
-  ctags -R --output-format=json \
+  # Use ctags for precise symbol extraction over the listed files only (-L, never -R: forge#4126).
+  # Paths are relative to REPO_PATH, matching the grep fallback and the caller graph.
+  (cd "$REPO_PATH" && ctags --output-format=json \
     --fields='nkz' \
     --languages=Python,JavaScript,TypeScript,Go,Rust,Java,C,C++ \
-    -f - "$REPO_PATH" 2>/dev/null \
+    -L "$FILE_LIST" -f - 2>/dev/null) \
   | grep -v '^!' \
   | while IFS= read -r line; do
       # Parse JSON output from universal-ctags. Portable (non-PCRE) extraction —
@@ -205,8 +229,7 @@ if [[ ! -s "$SYMBOLS_FILE" ]] || ! command -v ctags >/dev/null 2>&1; then
   echo "INFO: Falling back to grep-based symbol extraction"
 
   # Python: functions and classes
-  find "$REPO_PATH" -name "*.py" -not -path "*/.git/*" -not -path "*/node_modules/*" \
-    -not -path "*/__pycache__/*" 2>/dev/null | while read -r f; do
+  src_files py | while read -r f; do
     grep -n "^def \|^    def \|^class " "$f" 2>/dev/null | while IFS=: read -r lnum content; do
       # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
       # grep build on Windows, so use a bash regex instead of a lookbehind.
@@ -222,8 +245,7 @@ if [[ ! -s "$SYMBOLS_FILE" ]] || ! command -v ctags >/dev/null 2>&1; then
   done >> "$SYMBOLS_FILE" 2>/dev/null || true
 
   # JavaScript/TypeScript: functions and classes
-  find "$REPO_PATH" \( -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" \) \
-    -not -path "*/.git/*" -not -path "*/node_modules/*" 2>/dev/null | while read -r f; do
+  src_files js ts tsx jsx | while read -r f; do
     grep -n "^export function \|^function \|^export class \|^class \|^const .* = \(function\|async function\|() =>\)" \
       "$f" 2>/dev/null | while IFS=: read -r lnum content; do
       # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
@@ -250,8 +272,7 @@ IMPORTS_FILE="${CACHE_DIR}/imports.tsv"
 echo "INFO: Building import graph..."
 
 # Python imports
-find "$REPO_PATH" -name "*.py" -not -path "*/.git/*" -not -path "*/__pycache__/*" \
-  2>/dev/null | while read -r f; do
+src_files py | while read -r f; do
   rel_path="${f#$REPO_PATH/}"
   grep -n "^import \|^from " "$f" 2>/dev/null | while IFS=: read -r lnum content; do
     # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
@@ -271,8 +292,7 @@ find "$REPO_PATH" -name "*.py" -not -path "*/.git/*" -not -path "*/__pycache__/*
 done >> "$IMPORTS_FILE" 2>/dev/null || true
 
 # JavaScript/TypeScript imports
-find "$REPO_PATH" \( -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" \) \
-  -not -path "*/.git/*" -not -path "*/node_modules/*" 2>/dev/null | while read -r f; do
+src_files js ts tsx jsx | while read -r f; do
   rel_path="${f#$REPO_PATH/}"
   grep -n "^import \|^} from \|require(" "$f" 2>/dev/null | while IFS=: read -r lnum content; do
     # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
@@ -289,7 +309,7 @@ find "$REPO_PATH" \( -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.j
 done >> "$IMPORTS_FILE" 2>/dev/null || true
 
 # Go imports
-find "$REPO_PATH" -name "*.go" -not -path "*/.git/*" 2>/dev/null | while read -r f; do
+src_files go | while read -r f; do
   rel_path="${f#$REPO_PATH/}"
   grep -n '"[^"]*"' "$f" 2>/dev/null | grep -v "//\|fmt.Print\|errors.New" | while IFS=: read -r lnum content; do
     # Portable (non-PCRE) extraction — grep -oP is not supported by Git Bash's
@@ -311,28 +331,32 @@ CALLERS_FILE="${CACHE_DIR}/callers.tsv"
 
 echo "INFO: Building caller graph..."
 
-# For each symbol, find files that call it (grep for usage)
+# One pass (forge#4126): collect every `name(` occurrence across the listed sources with a single grep, then
+# join it in awk against the first 500 symbols. The old loop ran one full find|grep tree walk per symbol.
+# One row per (symbol, caller file) at the first call line; files defining the symbol are skipped.
 if [[ -s "$SYMBOLS_FILE" ]]; then
-  # Process a sample of top symbols (cap at 500 to avoid timeout)
-  head -500 "$SYMBOLS_FILE" | while IFS=$'\t' read -r sym_name sym_file sym_line sym_kind; do
-    # Skip very short or generic names to avoid false positives
-    if [[ ${#sym_name} -lt 3 ]]; then continue; fi
-    # Search for callers (function calls, not definitions)
-    find "$REPO_PATH" -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \
-      -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) \
-      -not -path "*/.git/*" -not -path "*/node_modules/*" 2>/dev/null | \
-      xargs grep -l "\b${sym_name}(" 2>/dev/null | while read -r caller_file; do
-        rel_caller="${caller_file#$REPO_PATH/}"
-        # Skip the file where the symbol is defined
-        if [[ "$rel_caller" == "$sym_file" ]]; then continue; fi
-        caller_line=$(grep -n "\b${sym_name}(" "$caller_file" 2>/dev/null | head -1 | cut -d: -f1 || echo "0")
-        echo -e "${sym_name}\t${rel_caller}\t${caller_line}"
-      done || true
-      # ^ `xargs grep -l` returning 1 (zero callers found for this symbol) propagates
-      # through `pipefail` into this `while` compound statement, which is subject to
-      # `set -e` — guard it here so one symbol with no callers doesn't abort the
-      # remaining symbols in the outer loop.
-  done >> "$CALLERS_FILE" 2>/dev/null || true
+  CALLEE_FILE="${CACHE_DIR}/.callees"
+  head -500 "$SYMBOLS_FILE" > "$CALLEE_FILE"
+  (cd "$REPO_PATH" && grep -E '\.(py|js|ts|go|rs|java)$' "$FILE_LIST" | tr '\n' '\0' \
+    | xargs -0 grep -n -o -H -E '[A-Za-z_][A-Za-z0-9_]*\(' -- 2>/dev/null) \
+  | awk -v syms="$CALLEE_FILE" '
+      BEGIN {
+        while ((getline l < syms) > 0) {
+          split(l, s, "\t")
+          # Skip very short or generic names to avoid false positives
+          if (length(s[1]) >= 3) { want[s[1]] = 1; def[s[1] SUBSEP s[2]] = 1 }
+        }
+      }
+      {
+        # file:line:name(  — split from the right so a ":" in the file name survives.
+        n = split($0, a, ":"); id = a[n]; sub(/\($/, "", id); ln = a[n-1]
+        f = substr($0, 1, length($0) - length(a[n]) - length(ln) - 2)
+        k = id SUBSEP f
+        if (!(id in want) || (k in def) || (k in seen)) next
+        seen[k] = 1
+        print id "\t" f "\t" ln
+      }' >> "$CALLERS_FILE" 2>/dev/null || true
+  # ^ grep exits 1 when nothing matches; guard so `set -e`/`pipefail` never aborts the build here.
 fi
 
 # ---------------------------------------------------------------------------
@@ -375,9 +399,8 @@ if [[ -f "$FORGE_YAML" ]]; then
 fi
 
 # Map each file to its domain
-find "$REPO_PATH" -type f -not -path "*/.git/*" -not -path "*/node_modules/*" \
-  -not -path "*/__pycache__/*" -not -path "*/.forge/*" 2>/dev/null | while read -r f; do
-  rel_path="${f#$REPO_PATH/}"
+while IFS= read -r rel_path; do
+  case "$rel_path" in .forge/*|*/node_modules/*|node_modules/*|*/__pycache__/*) continue ;; esac
   domain="unclassified"
   for pattern in "${!DOMAIN_PATTERNS[@]}"; do
     if [[ "$rel_path" == $pattern* ]]; then
@@ -386,7 +409,7 @@ find "$REPO_PATH" -type f -not -path "*/.git/*" -not -path "*/node_modules/*" \
     fi
   done
   echo -e "${rel_path}\t${domain}"
-done >> "$DOMAIN_FILE" 2>/dev/null || true
+done < "$FILE_LIST" >> "$DOMAIN_FILE" 2>/dev/null || true
 
 # ---------------------------------------------------------------------------
 # Step 5: Write index manifest
@@ -401,9 +424,7 @@ FILE_COUNT=$(wc -l < "$DOMAIN_FILE" 2>/dev/null || echo 0)
 # found, but extraction came back empty, a loop was truncated somewhere above
 # (or a tool like grep -oP is unavailable/incompatible on this platform) — flag
 # it instead of letting "Index built successfully" silently paper over data loss.
-SRC_FILE_COUNT=$(find "$REPO_PATH" \( -name "*.py" -o -name "*.js" -o -name "*.ts" \
-  -o -name "*.tsx" -o -name "*.jsx" -o -name "*.go" \) -not -path "*/.git/*" \
-  -not -path "*/node_modules/*" -not -path "*/__pycache__/*" 2>/dev/null | wc -l | tr -d ' ')
+SRC_FILE_COUNT=$(src_files py js ts tsx jsx go | wc -l | tr -d ' ')
 INDEX_TRUNCATED=0
 if [[ "$SRC_FILE_COUNT" -gt 0 && "$SYMBOL_COUNT" -eq 0 ]]; then
   INDEX_TRUNCATED=1

package/scripts/code-index.test.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Tests for scripts/code-index.sh: the index covers the tracked tree only — nested worktrees (.forge/worktrees,
+# .claude/worktrees) and virtualenvs inside the checkout are never walked (forge#4126) — and the one-pass caller
+# graph still maps callees to their callers. Run: bash scripts/code-index.test.sh (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+ROOT=$(cd "$DIR/.." && pwd)
+SCRIPT="${CODE_INDEX_UNDER_TEST:-$ROOT/scripts/code-index.sh}"   # override to run the suite against another copy
+pass=0; fail=0
+ok() { pass=$((pass+1)); }
+bad() { fail=$((fail+1)); echo "FAIL: $1"; }
+WORK=$(mktemp -d "${TMPDIR:-/tmp}/code-index-test.XXXXXX")
+trap 'rm -rf "$WORK"' EXIT
+export GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@t GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@t
+
+# mksrc <dir> — a small Python + JS source tree; helper_fn is defined in app.py and called from use.py.
+mksrc() {
+  mkdir -p "$1/src" "$1/web"
+  printf 'def helper_fn():\n    return helper_fn()\n\nclass Widget:\n    pass\n' > "$1/src/app.py"
+  printf 'from src.app import helper_fn\n\n\ndef run_it():\n    return helper_fn()\n' > "$1/src/use.py"
+  printf "import x from './y'\nexport function renderPage() {}\n" > "$1/web/page.js"
+}
+
+# --- 1. git checkout with nested worktrees and a venv inside it ---
+REPO="$WORK/repo"; mksrc "$REPO"
+git -C "$REPO" init -q -b main
+git -C "$REPO" add -A; git -C "$REPO" commit -qm init
+git -C "$REPO" worktree add -q -b wt1 "$REPO/.claude/worktrees/one" 2>/dev/null
+git -C "$REPO" worktree add -q -b wt2 "$REPO/.forge/worktrees/two" 2>/dev/null
+printf 'def worktree_only_fn():\n    helper_fn()\n' > "$REPO/.claude/worktrees/one/src/wt_only.py"
+printf 'def forge_wt_only_fn():\n    helper_fn()\n' > "$REPO/.forge/worktrees/two/src/fwt_only.py"
+mkdir -p "$REPO/.venv/lib"; printf 'def venv_only_fn():\n    helper_fn()\n' > "$REPO/.venv/lib/site.py"
+
+OUT="$WORK/out"
+bash "$SCRIPT" --repo-path "$REPO" --output "$OUT" > "$WORK/log" 2>&1; rc=$?
+if [ "$rc" -eq 0 ]; then ok; else bad "build exit $rc: $(head -c 400 "$WORK/log")"; fi
+C=$(ls -d "$OUT"/*/ 2>/dev/null | head -n 1)
+for f in symbols imports callers file_domain; do
+  if [ -s "$C/$f.tsv" ]; then ok; else bad "$f.tsv is empty"; fi
+  if grep -qE '\.claude/|\.forge/|\.venv/|worktree_only_fn|forge_wt_only_fn|venv_only_fn' "$C/$f.tsv" 2>/dev/null; then
+    bad "$f.tsv indexed a nested worktree or venv: $(grep -E '\.claude/|\.forge/|\.venv/|_only_fn' "$C/$f.tsv" | head -n 3 | tr '\n' ' ')"
+  else ok; fi
+done
+if grep -q '^helper_fn	src/app.py	1	' "$C/symbols.tsv"; then ok; else bad "helper_fn symbol missing or path not relative: $(cat "$C/symbols.tsv")"; fi
+if grep -q '"files": 3' "$C/index.json"; then ok; else bad "file count should be the 3 tracked files: $(grep '"files":' "$C/index.json" | head -n 1)"; fi
+
+# --- 2. one-pass caller graph ---
+if grep -q '^helper_fn	src/use.py	5$' "$C/callers.tsv"; then ok; else bad "helper_fn caller src/use.py:5 missing: $(cat "$C/callers.tsv")"; fi
+if grep -q '^helper_fn	src/app.py	' "$C/callers.tsv"; then bad "the defining file must not be listed as a caller"; else ok; fi
+n=$(grep -c '^helper_fn	src/use.py	' "$C/callers.tsv")
+if [ "$n" -eq 1 ]; then ok; else bad "one caller row per (symbol, file), got $n"; fi
+
+# --- 3. cache hit on unchanged HEAD ---
+bash "$SCRIPT" --repo-path "$REPO" --output "$OUT" > "$WORK/log2" 2>&1
+if grep -q "Cache hit" "$WORK/log2"; then ok; else bad "second build should be a cache hit"; fi
+
+# --- 4. outside git: pruned find fallback ---
+PLAIN="$WORK/plain"; mksrc "$PLAIN"
+mkdir -p "$PLAIN/.venv/lib" "$PLAIN/.claude/worktrees/x/src"
+printf 'def venv_only_fn():\n    pass\n' > "$PLAIN/.venv/lib/site.py"
+printf 'def worktree_only_fn():\n    pass\n' > "$PLAIN/.claude/worktrees/x/src/w.py"
+bash "$SCRIPT" --repo-path "$PLAIN" --output "$WORK/out2" > "$WORK/log3" 2>&1; rc=$?
+if [ "$rc" -eq 0 ]; then ok; else bad "non-git build exit $rc"; fi
+C2=$(ls -d "$WORK"/out2/*/ 2>/dev/null | head -n 1)
+if grep -q '^helper_fn	src/app.py	' "$C2/symbols.tsv" 2>/dev/null; then ok; else bad "non-git build missed helper_fn"; fi
+if grep -qE 'venv_only_fn|worktree_only_fn' "$C2/symbols.tsv" 2>/dev/null; then bad "non-git build walked .venv/.claude"; else ok; fi
+
+echo "code-index tests: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/scripts/review-pr-staging-scope.test.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # review-pr-staging-scope.test.sh — cases for the review-pr-staging scoped-review gates (forge#3451):
 #   (1) the 7B out-of-scope rule may only demote MEDIUM/LOW/INFO, never HIGH/CRITICAL or unknown severity;
-#   (2) the 0B.1 "reviewed" test needs the full-length Reviewed-SHA line, not a 7-char substring.
+#   (2) the 0B.1 "reviewed" test needs the full-length Reviewed-SHA line, not a 7-char substring;
+#   (11) issue numbers cited in commit subjects never make 0B.1 fall open (forge#4127).
 # SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 # SPDX-License-Identifier: AGPL-3.0-or-later
 set -uo pipefail
@@ -264,6 +265,40 @@ vh10 blocking "PASS"
 case "$VH10_OUT" in *rc=0*) [ "$VH10_V" = "PASS" ] && ok || bad "a valid persisted PASS must stay PASS" ;; *) bad "a valid persisted PASS must not block" ;; esac
 vh10 blocking "SKIP"
 case "$VH10_OUT" in *rc=0*) [ "$VH10_V" = "SKIP" ] && ok || bad "a valid persisted SKIP must stay SKIP" ;; *) bad "a valid persisted SKIP must not block" ;; esac
+# (11) bundle PR set vs issue numbers (forge#4127): conventional subjects cite issues ("(#28668)"); an issue is skipped, never a reason to fall open.
+# Stub gh: PRs 5 (reviewed at head) and 6; 28668 is an issue; 77 fails every read.
+H11=0123456789abcdef0123456789abcdef01234567
+gh11() {
+  case "$*" in
+    "pr view 5 "*|"pr view 6 "*) jq -n --arg h "$H11" '{headRefOid:$h,mergeCommit:{oid:"m"},commits:[{oid:"c"}],state:"MERGED",baseRefName:"staging",labels:[]}' ;;
+    "pr view "*) return 1 ;;
+    "api repos/o/r/issues/5 "*|"api repos/o/r/issues/6 "*) echo pr ;;
+    "api repos/o/r/issues/28668 "*) echo issue ;;
+    "api --paginate repos/o/r/issues/5/comments") printf '%s\n' "$(cm9 "<!-- FORGE:REVIEW_ROUTE mode=full spec=review-pr.md sha=${H11:0:7} -->")" "$(cm9 "$(agent9 security "$H11")")" | jq -s . ;;
+    "api --paginate repos/o/r/issues/"*/comments) echo '[]' ;;
+    "pr diff "*) echo "f$3.txt" ;;
+    *) return 1 ;;
+  esac
+}
+[ "$(grep -c '^# BEGIN bundle-pr-kind$' "$SPEC")" -eq 2 ] && [ "$(awk '/^# BEGIN bundle-pr-kind$/{f=1;n++} f{print > ("'"$TMP"'/kind" n ".sh")} /^# END bundle-pr-kind$/{f=0}' "$SPEC"; cmp -s "$TMP/kind1.sh" "$TMP/kind2.sh" && echo same)" = same ] && ok || bad "0A and 0B.1 must carry identical bundle_pr_kind blocks"
+awk '/^# BEGIN bundle-pr-set$/{f=1;next} /^# END bundle-pr-set$/{f=0} f' "$SPEC" | sed 's/{GH_REPO}/o\/r/g' > "$TMP/prset.sh"
+[ -s "$TMP/prset.sh" ] && ok || bad "bundle-pr-set block not found in Phase 0A"
+OUT11=$( gh() { gh11 "$@"; }; BUNDLE_PRS="5 6 28668 77 90"; MERGE_PRS="90"; . "$TMP/prset.sh"; echo $ALL_PR_NUMBERS "|$SKIPPED_ISSUES" )
+[ "$OUT11" = "5 6 77 90 | 28668" ] && ok || bad "0A must drop the confirmed issue and keep PRs, merge PRs and unclassifiable numbers (got '$OUT11')"
+awk '/^# BEGIN bundle-scope-loop$/{f=1;next} /^# END bundle-scope-loop$/{f=0} f' "$SPEC" > "$TMP/loop.sh"
+[ -s "$TMP/loop.sh" ] && ok || bad "bundle-scope-loop block not found in 0B.1"
+scope11() { # $1 = ALL_PR_NUMBERS; prints "<SCOPE_MODE> <REVIEWED_PR_COUNT>" then the loop output
+  ( gh() { gh11 "$@"; }; bundle_delta_credit() { DELTA_COMMITS=""; DELTA_FULL=0; }; . "$TMP/kind1.sh"
+    SCOPE_MODE=full; REVIEWED_COMMITS=""; REVIEWED_MERGES=""; REVIEWED_PR_COUNT=0; _PF="$TMP/pf11"; : > "$_PF"
+    TRUSTED_SCRIPT="$TC" ALL_PR_NUMBERS="$1" PR_NUMBER=9 GH_REPO=o/r _SD="$TMP" REVIEW_DELTA_SCRIPT=""
+    LOG11=$(. "$TMP/loop.sh"; echo "@@$SCOPE_MODE $REVIEWED_PR_COUNT"); echo "${LOG11##*@@}"; echo "${LOG11%@@*}" )
+}
+OUT11=$(scope11 "28668 5 6")
+[ "$(printf '%s\n' "$OUT11" | head -1)" = "scoped 1" ] && ok || bad "an issue number in the bundle list must be skipped, not fall open (got '$OUT11')"
+case "$OUT11" in *"#28668 is an issue"*) ok ;; *) bad "0B.1 must announce the skipped issue (got '$OUT11')" ;; esac
+OUT11=$(scope11 "5 77")
+[ "$(printf '%s\n' "$OUT11" | head -1 | cut -d' ' -f1)" = "full" ] && ok || bad "a genuine read failure must still fall open (got '$OUT11')"
+case "$OUT11" in *"fell open at bundle PR #77"*"not a confirmed issue"*) ok ;; *) bad "a fall-open must print the PR and reason (got '$OUT11')" ;; esac
 else echo "review-pr-staging-scope.test.sh: git missing, delta section skipped"; fi
 echo "review-pr-staging-scope.test.sh: passed=$PASS failed=$FAILN"
 [ "$FAILN" -eq 0 ]

package/scripts/review-prepare.sh

@@ -23,7 +23,9 @@
 #   --no-delta      skip the FULL/DELTA/BASE_SYNC_ONLY resolver: the review mode is always FULL (a staging bundle review always reviews the
 #                   whole bundle), without widening the roster to the full union the way --thorough does
 # Env: FORGE_CONFIG (forge.yaml path; default: the main checkout's forge.yaml, then the git top-level one),
-#      REVIEW_PREPARE_SLEEP (seconds between mergeability retries, default 5).
+#      REVIEW_PREPARE_SLEEP (seconds between mergeability retries, default 5),
+#      REVIEW_PREPARE_INDEX_TIMEOUT (seconds the code-index build may take, default 120; on timeout or failure the slices say
+#      "Code index not available" and agents grep instead — forge#4126).
 # Exit: 0 context emitted (status OK) | 3 context emitted with status BLOCKED (the caller must stop, never skip) | 2 usage error
 #
 # Moved from the spec and still in the spec (the caller keeps running them): Phase 2 lint/typecheck/test/build EXECUTION (long-running,
@@ -463,10 +465,21 @@ if [ "$REVIEW_MODE" != "BASE_SYNC_ONLY" ]; then
         gh pr comment "$PR_NUMBER" -R "$REPO" --body "$_msg" >/dev/null 2>&1 || true # allowlist:check-command-side-effects
         [ -z "$MERGE_ISSUE" ] || gh issue edit "$MERGE_ISSUE" -R "$REPO" --add-label needs-human >/dev/null 2>&1 || true # allowlist:check-command-side-effects
     fi
-    if [ -n "$CODE_INDEX_SCRIPT" ]; then bash "$CODE_INDEX_SCRIPT" --repo-path "$REPO_PATH" >/dev/null 2>&1 || true; fi
+    # forge#4126: the index build is bounded and visible. A hung build used to block review prep silently (output was discarded).
+    INDEX_OK=0
+    if [ -n "$CODE_INDEX_SCRIPT" ]; then
+        _ito="${REVIEW_PREPARE_INDEX_TIMEOUT:-120}"; case "$_ito" in ''|*[!0-9]*|0) _ito=120 ;; esac
+        _tbin=$(command -v timeout || command -v gtimeout || true)
+        echo "review-prepare: building code index (limit ${_ito}s)" >&2
+        if [ -n "$_tbin" ]; then "$_tbin" "$_ito" bash "$CODE_INDEX_SCRIPT" --repo-path "$REPO_PATH" >/dev/null 2>&1; _irc=$?
+        else bash "$CODE_INDEX_SCRIPT" --repo-path "$REPO_PATH" >/dev/null 2>&1; _irc=$?; fi
+        if [ "$_irc" -eq 0 ]; then INDEX_OK=1
+        elif [ "$_irc" -eq 124 ]; then echo "review-prepare: code index timed out after ${_ito}s — skipping index slices (agents grep instead)" >&2
+        else echo "review-prepare: code index failed (exit $_irc) — skipping index slices (agents grep instead)" >&2; fi
+    fi
     build_index_slice() {
         local domain="${1}" files
-        if [ -n "$CODE_INDEX_SCRIPT" ]; then
+        if [ "$INDEX_OK" -eq 1 ]; then
             files=$(bash "$CODE_INDEX_SCRIPT" query --domain "$domain" --repo-path "$REPO_PATH" 2>/dev/null | awk -F'\t' '{print $1}' | head -30 | tr '\n' ' ')
             echo "Domain files (${domain}): ${files:-none}"
         else echo "Code index not available — agent will use grep exploration"; fi

package/scripts/review-prepare.test.sh

@@ -300,5 +300,21 @@ setup feat/x staging "README.md" "$DIFF_PLAIN"
 CTX=$(cd "$WORK/hostile" && FORGEDOCK_HOME="$ROOT" FORGE_CONFIG="$CFG" bash "$ROOT/scripts/review-prepare.sh" --pr 7 --repo o/r --out-dir "$WORK/out" 2>/dev/null)
 eq "a hostile cwd roster script is never used" '.roster.agents | index("evil") != null' false
 
+# --- code index build is bounded and visible (forge#4126) ---
+setup feat/x staging "services/api/auth.py" "$DIFF_AUTH_BILL"
+prep "$ROOT"
+eq "real index fills the auth slice" '.index_slices.auth | startswith("Domain files (auth):")' true
+if grep -q "review-prepare: building code index" "$WORK/stderr"; then ok; else bad "index build must print a progress line on stderr"; fi
+if command -v timeout >/dev/null 2>&1 || command -v gtimeout >/dev/null 2>&1; then
+    mkroot "$WORK/root-slowindex" "" "" templates
+    printf '#!/usr/bin/env bash\nsleep 30\n' > "$WORK/root-slowindex/scripts/code-index.sh"
+    t0=$(date +%s)
+    REVIEW_PREPARE_INDEX_TIMEOUT=1 prep "$WORK/root-slowindex"; t1=$(date +%s)
+    rc_is "hung index build" 0
+    if [ $((t1 - t0)) -lt 20 ]; then ok; else bad "hung index build was not bounded ($((t1 - t0))s)"; fi
+    eq "timed-out index falls back to grep slices" .index_slices.auth "Code index not available — agent will use grep exploration"
+    if grep -q "code index timed out after 1s" "$WORK/stderr"; then ok; else bad "index timeout must be reported on stderr"; fi
+fi
+
 echo "review-prepare tests: $pass passed, $fail failed"
 [ "$fail" -eq 0 ]