reconFTW is a tool designed to perform automated recon on a target domain by running the best set of tools to perform scanning and finding out vulnerabilities
Shell bug-bountybugbountybugbounty-tooldnshackingnucleiosintpenetration-testingpentestpentest-toolpentestingreconreconnaissancescannersecuritysecurity-toolssubdomainsubdomain-enumerationvulnerabilities
docs(01): add gap-closure plans 01-04 and 01-05
six2dez696251e2f471
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.mdindex e0a4bc2..071cc1e 100644--- a/.planning/ROADMAP.md+++ b/.planning/ROADMAP.md@@ -35,6 +35,8 @@ Plans:- [x] 01-01: `.inprogress` sentinel lifecycle in `start_func`/`end_func` with resume detection (RESIL-01)- [x] 01-02: Disk-full mid-run guard — periodic `df` check + `ENOSPC` trap (RESIL-02)- [x] 01-03: `PARALLEL_JOB_TIMEOUT_SECONDS` enforcement in `lib/parallel.sh` plus DNS timeout defaults in `reconftw.cfg` (RESIL-03, PERF-02)+- [ ] 01-04: Gap closure — `_RECON_CLEAN_EXIT` flag gates `_cleanup_inprogress` so SIGINT/SIGTERM preserves `.inprogress_<fn>` sentinels (RESIL-01 / CR-01)+- [ ] 01-05: Gap closure — decouple timeout enforcement from `--quiet` verbosity gate AND switch `_timeout_kill_job` to process-tree kill via `pgrep -P` walk (RESIL-03 / CR-02, CR-03)### Phase 2: Security Quoting & Supply-Chain Hygiene**Goal**: Eliminate the remaining `eval` injection vector, lock down unquoted notification curl calls, make `AXIOM_EXTRA_ARGS` tokenisation explicit, and integrity-check installer bootstrappers.@@ -102,7 +104,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5| Phase | Plans Complete | Status | Completed ||-------|----------------|--------|-----------|-| 1. Resilient Resume & Timeout Safety | 0/3 | Not started | - |+| 1. Resilient Resume & Timeout Safety | 3/5 | Gap closure in flight | - || 2. Security Quoting & Supply-Chain Hygiene | 0/3 | Not started | - || 3. Concurrency Caps & Scope Unification | 0/2 | Not started | - || 4. Test Coverage Reinforcement | 0/2 | Not started | - |diff --git a/.planning/STATE.md b/.planning/STATE.mdindex 2124b60..093f1ae 100644--- a/.planning/STATE.md+++ b/.planning/STATE.md@@ -4,14 +4,14 @@ milestone: v1.0milestone_name: milestonestatus: executingstopped_at: Phase 1 context gathered-last_updated: "2026-05-13T08:57:40.389Z"+last_updated: "2026-05-13T10:39:08.045Z"last_activity: 2026-05-13 -- Phase 01 planning completeprogress:total_phases: 5completed_phases: 0- total_plans: 3- completed_plans: 0- percent: 0+ total_plans: 5+ completed_plans: 3+ percent: 60---# Project Statediff --git a/.planning/config.json b/.planning/config.jsonindex 31cb30d..6eb0e11 100644--- a/.planning/config.json+++ b/.planning/config.json@@ -27,7 +27,8 @@"discuss_mode": "discuss","skip_discuss": false,"code_review": true,- "code_review_depth": "standard"+ "code_review_depth": "standard",+ "_auto_chain_active": false},"hooks": {"context_warnings": truediff --git a/.planning/phases/01-resilient-resume-timeout-safety/01-04-PLAN.md b/.planning/phases/01-resilient-resume-timeout-safety/01-04-PLAN.mdnew file mode 100644index 0000000..133129c--- /dev/null+++ b/.planning/phases/01-resilient-resume-timeout-safety/01-04-PLAN.md@@ -0,0 +1,332 @@+---+id: 01-04+phase: 01+plan: 04+type: execute+wave: 3+depends_on: []+requirements: [RESIL-01]+gap_closure: true+closes_gaps: [CR-01]+files_modified:+ - modules/modes.sh+ - modules/utils.sh+ - modules/core.sh+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md+autonomous: true+must_haves:+ truths:+ - "On SIGINT/SIGTERM during a running recon, `.inprogress_<fn>` sentinels remain on disk so the next invocation's WARN resume banner fires (closes CR-01 / SC1 indicator gap)"+ - "Sentinels are still cleared on normal end-of-run via the EXIT trap so a clean shell exit leaves the called_fn_dir tidy (preserves the original D-02 intent for the happy path)"+ - "`cleanup_on_exit` body remains unchanged — INT/TERM still print 'Interrupted. Cleaning up...' and exit 130 (the user-visible interruption signal is load-bearing and must not regress)"+ - "Start of `start()` initialises `_RECON_CLEAN_EXIT=false`; `_cleanup_inprogress` is gated on the flag being `true`; the existing successful return path of `start()` sets the flag to `true` immediately before its final non-trap exit point so a clean traversal wipes sentinels"+ - "The misleading comment at `modules/core.sh:1431-1434` ('EXIT trap clears it on graceful exit') is updated so the documented behavior matches the implemented gated-trap behavior (anti-pattern WR/INFO finding from 01-VERIFICATION.md anti-pattern table at :137)"+ - "`01-CONTEXT.md` D-02 wording is clarified so its 'trap on EXIT INT TERM clears sentinels' phrasing is reconciled with SC1 — the resolved semantics are 'EXIT trap clears sentinels only on clean exit; SIGINT/SIGTERM preserves sentinels so the next run's resume banner fires'"+ code_landmarks:+ - "`_RECON_CLEAN_EXIT` module-level flag declared at the top of `start()` in `modules/modes.sh` (immediately after `global_start=$(date +%s)` at :15 and before `set +m`) with default `false`"+ - "Gated body of `_cleanup_inprogress` in `modules/utils.sh:149-152` — early-return when `${_RECON_CLEAN_EXIT:-false} != true`, otherwise sweep `.inprogress_*` files; `return 0` to never propagate non-zero through the EXIT trap chain"+ - "Flag-set `_RECON_CLEAN_EXIT=true` at the end of `start()` is NOT the right anchor — `start()` returns to its caller (which then runs the workflow). The flag must be set at the end-of-run point that maps to a clean exit. The orchestrator-level end-of-run is the bottom of the matching workflow function (`recon()`, `passive()`, `all()`, `vulns()`, `osint()`, `subs_menu()`, `webs_menu()`, `zen_menu()`, `monitor_mode()` in `modules/modes.sh`). The most reliable single anchor is inside `end()` (the canonical wrap-up function called by every workflow function); set `_RECON_CLEAN_EXIT=true` as the LAST executable statement of `end()` so that whichever workflow path the run takes, a successful traversal flips the flag immediately before `start()`'s caller returns and the shell exits normally"+ - "Comment update at `modules/core.sh:1431-1434` — replace 'EXIT trap clears it on graceful exit' with explicit clean-exit-flag semantics: 'EXIT trap clears it ONLY when `_RECON_CLEAN_EXIT=true` is set by `end()` (clean traversal); SIGINT/SIGTERM via `cleanup_on_exit` does NOT set the flag, so sentinels survive and the next run\\'s resume banner fires'"+ - "D-02 wording in `01-CONTEXT.md` updated to match implemented semantics — keep the decision ID, change the body from 'trap on EXIT INT TERM clears sentinels' to the clean-exit-flag wording so future verifiers do not flag the same inconsistency"+ behavioral_checks:+ - "Smoke 1 (SIGINT preserves sentinel — the CR-01 reproduction inverted): seed `${tmpd}/.inprogress_sub_brute` and `${tmpd}/.sub_passive` in a fresh `called_fn_dir=$(mktemp -d)`, source the project via `./reconftw.sh --source-only`, install BOTH traps in a `bash -c` subshell that does NOT call `end()` (simulates a real Ctrl+C mid-recon), send SIGINT to the subshell. Afterward, `ls ${tmpd}` MUST still show `.inprogress_sub_brute` AND `.sub_passive`. With the current code (pre-patch) the same script wipes `.inprogress_sub_brute`."+ - "Smoke 2 (clean exit clears sentinel): same setup as Smoke 1 but the subshell calls `start()` and the workflow's `end()` function before exiting normally. Afterward, `ls ${tmpd}/.inprogress_*` MUST be empty (clean traversal flips `_RECON_CLEAN_EXIT=true` so the EXIT trap sweeps)."+ - "Smoke 3 (INT/TERM banner unchanged): a `bash -c './reconftw.sh -d test.local -p'` (replace with a smoke target that is safe in the agent's environment, e.g., `--health-check` if `-d` is unsafe) sent SIGINT MUST still print the red `Interrupted. Cleaning up...` banner from `cleanup_on_exit` and exit with code 130. The new clean-exit-flag must not interfere with this user-facing behavior."+ - "Smoke 4 (bats baseline holds): `bats tests/unit/` reports 246/246 PASS (same count as pre-patch). No new tests are added in this plan per CONTEXT.md §Claude's Discretion (Phase 4 owns coverage)."+---++<objective>+Restore the `.inprogress_<fn>` resume indicator for SIGINT/SIGTERM interruptions (Gap A / CR-01 / SC1 partial). Closes the gap by introducing a `_RECON_CLEAN_EXIT` flag that gates `_cleanup_inprogress` — the EXIT trap sweeps sentinels only when a clean traversal explicitly opts in. SIGINT/SIGTERM does not set the flag, so the `.inprogress_<fn>` files survive `cleanup_on_exit`'s `exit 130` and the next run's WARN resume banner fires correctly. Also updates the misleading start_func comment at `modules/core.sh:1431-1434` and reconciles `01-CONTEXT.md` D-02 wording with implemented semantics.++Purpose: 01-VERIFICATION.md marked SC1 PARTIAL because `cleanup_on_exit` (INT/TERM handler) ends in `exit "$exit_code"` (modules/utils.sh:145). Per Bash semantics, an explicit `exit` from inside an INT/TERM trap fires the EXIT trap, which currently runs `_cleanup_inprogress` unconditionally and wipes every `.inprogress_<fn>` (verified empirically by `/tmp/sc1_v3.sh`). Result: Ctrl+C resume indicator never appears — the most common interruption path silently fails the SC1 indicator guarantee. The verifier flagged this exact gap and the 01-REVIEW.md CR-01 advisory described the clean-exit-flag fix; this plan implements it.++Output:+- `modules/modes.sh`: declare `_RECON_CLEAN_EXIT=false` at the top of `start()` (after `global_start=$(date +%s)` and before `set +m`).+- `modules/modes.sh`: at the END of `end()` (the canonical workflow wrap-up), set `_RECON_CLEAN_EXIT=true` as the last executable statement so any successful traversal flips the flag before the shell exits.+- `modules/utils.sh`: gate `_cleanup_inprogress` body on `${_RECON_CLEAN_EXIT:-false} == "true"`; early-return otherwise. `cleanup_on_exit` itself is NOT modified.+- `modules/core.sh:1431-1434`: rewrite the `start_func` comment to reflect the gated-trap semantics.+- `01-CONTEXT.md` §Decisions D-02: rewrite the body sentence so the locked decision matches the implemented behavior. Decision ID and intent are preserved; only wording changes.++No new tests; Phase 4 owns coverage (`/gsd-verifier` will not re-flag SC1 once smoke 1 passes).+</objective>++<execution_context>+@$HOME/.claude/get-shit-done/workflows/execute-plan.md+@$HOME/.claude/get-shit-done/templates/summary.md+</execution_context>++<context>[email protected]/PROJECT.md[email protected]/ROADMAP.md[email protected]/STATE.md[email protected]/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md[email protected]/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md[email protected]/phases/01-resilient-resume-timeout-safety/01-VERIFICATION.md[email protected]/phases/01-resilient-resume-timeout-safety/01-REVIEW.md[email protected]/phases/01-resilient-resume-timeout-safety/01-01-SUMMARY.md[email protected]/codebase/CONVENTIONS.md++<interfaces>+<!-- Key existing identifiers the executor will modify or call. Extracted from codebase. -->++From modules/modes.sh:+- function start() — `:13-189`. Existing INT/TERM trap at `:121`: `trap 'cleanup_on_exit' INT TERM`. Existing EXIT trap at `:122`: `trap '_cleanup_inprogress' EXIT # silent EXIT-only sentinel sweep (D-02)`. Top of `start()` at :13-16 is the insertion site for `_RECON_CLEAN_EXIT=false` (must appear BEFORE the trap install at :121).+- function end() — defined in `modules/modes.sh` (search for `^function end()` or `^end\(\)`). This is the canonical wrap-up function called by every workflow function (`recon`, `passive`, `all`, etc.). The LAST executable statement of `end()` is the insertion site for `_RECON_CLEAN_EXIT=true`. The location is roughly `modules/modes.sh:280-380` per CONTEXT §Established Patterns; executor must locate it via grep before editing.++From modules/utils.sh:+- function cleanup_on_exit() — `:116-146`. UNCHANGED in this plan. Currently registered for INT/TERM only via the trap at `modules/modes.sh:121`. Body prints "Interrupted. Cleaning up...", kills tracked PIDs, and calls `exit "$exit_code"`. Per Bash semantics that `exit` fires the EXIT trap; that is the exact mechanism that today defeats SC1. We do NOT remove the `exit`; we make the EXIT trap a no-op for the non-clean case.+- function _cleanup_inprogress() — `:148-152`. Current single-line body: `[[ -n "${called_fn_dir:-}" ]] && rm -f "${called_fn_dir}"/.inprogress_* 2>/dev/null; return 0`. This is the function to GATE on `_RECON_CLEAN_EXIT`.++From modules/core.sh:+- function start_func() — `:1419-1445`. Existing comment block at `:1431-1434`: 4 lines of doc comment with the misleading "EXIT trap clears it on graceful exit" phrasing. The sentinel touch at :1436 is unchanged; only the comment block above it is rewritten.++From .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md:+- §Decisions block at `:19-61`. D-02 is the second decision at approximately `:25`. Current body says "trap on EXIT INT TERM clears sentinels". This plan rewrites the body sentence (preserving the D-02 ID and decision intent of "graceful exits leave NO .inprogress_* files") to reflect the clean-exit-flag implementation.+</interfaces>+</context>++<tasks>++<task type="auto">+ <name>Task 1: Initialise `_RECON_CLEAN_EXIT=false` in `start()` and gate `_cleanup_inprogress` in `modules/utils.sh`</name>+ <files>modules/modes.sh, modules/utils.sh</files>+ <read_first>+ - modules/modes.sh (entire start() body at :13-189 — note `global_start=$(date +%s)` at :15, `set +m 2>/dev/null || true` at :16, the INT/TERM trap at :121, the new EXIT trap at :122 from plan 01-01; insertion is BEFORE :121 and ideally between :15 and :16)+ - modules/utils.sh (cleanup_on_exit body at :116-146 — DO NOT modify; _cleanup_inprogress body at :148-152 — THIS is what gets gated)+ - .planning/phases/01-resilient-resume-timeout-safety/01-VERIFICATION.md (verifier's empirical reproduction at the `/tmp/sc1_v3.sh` line of the gaps table — "BEFORE: .inprogress_sub_brute .sub_passive. AFTER SIGINT: .sub_passive. FAIL: .inprogress_sub_brute deleted by EXIT trap")+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (D-02 — locked decision body and its inconsistency with SC1)+ - .planning/phases/01-resilient-resume-timeout-safety/01-REVIEW.md (CR-01 — advisory description of the clean-exit-flag fix; orchestrator chose the clean-exit-flag approach over "drop EXIT trap entirely" because it preserves the D-02 graceful-exit cleanup intent)+ - .planning/codebase/CONVENTIONS.md (Function Naming, Trap composition, Variable Naming — `_RECON_CLEAN_EXIT` follows the existing UPPER_SNAKE_CASE pattern for runtime-state globals like `LOGFILE`, `DIFF`, `AXIOM`)+ </read_first>+ <action>+ Step A — Initialise `_RECON_CLEAN_EXIT=false` at the top of `start()` in `modules/modes.sh`. Insert the new line IMMEDIATELY AFTER the existing `global_start=$(date +%s)` line at :15 and BEFORE the existing `set +m 2>/dev/null || true` line at :16. The exact insertion produces a 3-line block at the top of `start()`:++ ```+ global_start=$(date +%s) # :15 (unchanged)+ _RECON_CLEAN_EXIT=false # CR-01 fix: gate _cleanup_inprogress so SIGINT/SIGTERM preserve .inprogress_* sentinels (D-02 clean-exit semantics)+ set +m 2>/dev/null || true # :16 (unchanged, shifts to :17)+ ```++ The flag is a function-scope-less global (no `local` keyword) so it is visible to `_cleanup_inprogress` running under the EXIT trap. The default `false` value means any unexpected exit path that does not flip the flag (SIGINT, SIGTERM, SIGKILL-then-the-shell-handler, internal abort like `_abort_disk_full`) leaves sentinels in place. Per CONVENTIONS.md §Variable Naming the UPPER_SNAKE_CASE name matches other runtime-state globals (`LOGFILE`, `DIFF`, `AXIOM`, `FORCE_RESCAN`).++ DO NOT modify the trap install at :121 or :122 — they remain `trap 'cleanup_on_exit' INT TERM` and `trap '_cleanup_inprogress' EXIT # silent EXIT-only sentinel sweep (D-02)`. DO NOT remove the EXIT trap entirely (the orchestrator chose the clean-exit-flag approach over "drop the EXIT trap" specifically so the happy-path cleanup behavior is preserved; the verifier and reviewer both noted that option but recommended the gated approach).++ Step B — Gate `_cleanup_inprogress` body on the clean-exit flag in `modules/utils.sh`. The current function body at :148-152 is:++ ```+ # Remove stale .inprogress_<fn> sentinels on EXIT (D-02). Does not call exit/kill/print — safe to fire on every shell exit, including successful runs.+ function _cleanup_inprogress() {+ [[ -n "${called_fn_dir:-}" ]] && rm -f "${called_fn_dir}"/.inprogress_* 2>/dev/null+ return 0+ }+ ```++ Rewrite to:++ ```+ # Remove stale .inprogress_<fn> sentinels on EXIT (D-02 clean-exit-only).+ # Gated on _RECON_CLEAN_EXIT: only sweeps when the workflow's end() set the+ # flag (clean traversal). SIGINT/SIGTERM via cleanup_on_exit does NOT set the+ # flag, so the sentinel survives and the next run's resume banner fires+ # (CR-01 fix; closes SC1 indicator gap from 01-VERIFICATION.md).+ function _cleanup_inprogress() {+ [[ "${_RECON_CLEAN_EXIT:-false}" == "true" ]] || return 0+ [[ -n "${called_fn_dir:-}" ]] && rm -f "${called_fn_dir}"/.inprogress_* 2>/dev/null+ return 0+ }+ ```++ The `return 0` early-exit on the non-clean case is mandatory — it preserves the existing contract that `_cleanup_inprogress` never propagates a non-zero exit code through the EXIT trap chain (which would alter `$?` on shell exit, affecting CI return-code checks). DO NOT call `exit`, `kill`, `_print_*`, or `log_json` in either branch. DO NOT add stderr output (the EXIT trap must remain silent on graceful exits per the original D-02 intent).++ DO NOT touch `cleanup_on_exit` (:116-146). DO NOT touch `rotate_logs` (:154) or any other helper. The change is scoped to the `_cleanup_inprogress` body only.++ Constraint check: per CLAUDE.md §Constraints (Bash 4.3+, single-operator) the gated-flag approach is safe — no concurrent runs against the same `called_fn_dir`, so there is no race window where two simultaneous shells could observe different `_RECON_CLEAN_EXIT` values for the same target directory.+ </action>+ <verify>+ <automated>bash -n /Users/six2dez/Tools/reconftw/modules/modes.sh && bash -n /Users/six2dez/Tools/reconftw/modules/utils.sh && shellcheck -s bash --severity=error /Users/six2dez/Tools/reconftw/modules/modes.sh /Users/six2dez/Tools/reconftw/modules/utils.sh</automated>+ </verify>+ <acceptance_criteria>+ - `grep -n '_RECON_CLEAN_EXIT=false' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns exactly one match inside the `start()` function body. Confirm the match line number is greater than the line containing `global_start=$(date +%s)` and less than the line containing `set +m 2>/dev/null || true`. Use: `awk '/global_start=\$\(date \+%s\)/{g=NR} /_RECON_CLEAN_EXIT=false/{f=NR} /set \+m 2>\/dev\/null/{s=NR} END{print (g && f && s && g<f && f<s) ? "ORDER_OK" : "ORDER_FAIL"}' modules/modes.sh` → prints `ORDER_OK`.+ - `grep -n '_RECON_CLEAN_EXIT=true' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns 0 matches in THIS task (Task 2 is the one that adds the `=true` flip in `end()`).+ - The gated early-return line is present in `_cleanup_inprogress`: `awk '/^function _cleanup_inprogress\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/modules/utils.sh | grep -c '\[\[ "\${_RECON_CLEAN_EXIT:-false}" == "true" \]\] \|\| return 0'` returns exactly 1.+ - The existing rm-f line is preserved within `_cleanup_inprogress`: `awk '/^function _cleanup_inprogress\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/modules/utils.sh | grep -c 'rm -f "\${called_fn_dir}"/\.inprogress_\*'` returns exactly 1.+ - The order is correct (gate BEFORE rm): `awk '/^function _cleanup_inprogress\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/modules/utils.sh | awk '/_RECON_CLEAN_EXIT/{g=NR} /rm -f.*\.inprogress_\*/{r=NR} END{print (g && r && g<r) ? "OK" : "FAIL"}'` returns `OK`.+ - `cleanup_on_exit` body is UNCHANGED: `grep -c 'Interrupted. Cleaning up' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns >=1, `grep -c 'exit "\$exit_code"' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns >=1, AND `awk '/^function cleanup_on_exit\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/modules/utils.sh | grep -c '_RECON_CLEAN_EXIT'` returns exactly 0 (the flag must NOT leak into `cleanup_on_exit`).+ - The INT/TERM trap line is UNCHANGED: `grep -c "^[[:space:]]*trap 'cleanup_on_exit' INT TERM$" /Users/six2dez/Tools/reconftw/modules/modes.sh` returns exactly 1.+ - The EXIT trap line is UNCHANGED: `grep -nE "^[[:space:]]*trap '_cleanup_inprogress' EXIT" /Users/six2dez/Tools/reconftw/modules/modes.sh` returns exactly 1.+ - `bash -n modules/modes.sh modules/utils.sh` exits 0.+ - `shellcheck -s bash --severity=error modules/modes.sh modules/utils.sh` exits 0 (no NEW error-level findings vs baseline).+ - Behavior smoke (CR-01 inverted reproduction — the SC1 indicator-preserved test): write a temporary script `/tmp/sc1_recheck.sh` that (1) sources `./reconftw.sh --source-only`, (2) `tmpd=$(mktemp -d); called_fn_dir=$tmpd; touch $tmpd/.inprogress_sub_brute $tmpd/.sub_passive`, (3) installs BOTH traps as `start()` does (`trap 'cleanup_on_exit' INT TERM; trap '_cleanup_inprogress' EXIT`) AND initialises `_RECON_CLEAN_EXIT=false`, (4) sends itself SIGINT and exits. After the subshell exits, `ls $tmpd` MUST list BOTH `.inprogress_sub_brute` AND `.sub_passive` (with the pre-patch code only `.sub_passive` survives; the patch must restore the `.inprogress_sub_brute`). Run the script in `bash -c` to get a clean environment. Confirm with `[[ -f $tmpd/.inprogress_sub_brute ]] && [[ -f $tmpd/.sub_passive ]] && echo SC1_OK || echo SC1_FAIL`.+ - Behavior smoke (clean-exit DOES NOT clear in Task 1 alone — verifies the flag-default invariant): same script but with `_RECON_CLEAN_EXIT=false` and a normal `exit 0` (no SIGINT, no `_RECON_CLEAN_EXIT=true` flip). `ls $tmpd/.inprogress_*` MUST still show the sentinel. This proves Task 1's gate works as a no-op and the sweep behavior depends on Task 2 setting the flag. (Task 2 supplies the clean-exit flag-set.)+ </acceptance_criteria>+ <done>+ `_RECON_CLEAN_EXIT=false` initialised at the top of `start()` between `global_start=$(date +%s)` and `set +m`; `_cleanup_inprogress` body gated on `${_RECON_CLEAN_EXIT:-false} == "true"` with `return 0` early-exit otherwise; `cleanup_on_exit` body untouched; INT/TERM and EXIT trap install lines untouched; SIGINT-preserves-sentinel smoke passes; `bash -n` and `shellcheck` clean.+ </done>+</task>++<task type="auto">+ <name>Task 2: Set `_RECON_CLEAN_EXIT=true` at the end of `end()` (clean traversal flag-flip)</name>+ <files>modules/modes.sh</files>+ <read_first>+ - modules/modes.sh (locate the `end()` function definition via `grep -n '^function end()' modules/modes.sh` or `grep -n '^end()' modules/modes.sh`; read the entire body — typically 50-150 lines depending on how many wrap-up activities it performs)+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (Integration Points §"start() in modules/modes.sh:13 — installs the EXIT/INT/TERM trap..."; the canonical end-of-run point is the workflow's `end()` function, not the bottom of `start()`)+ - .planning/phases/01-resilient-resume-timeout-safety/01-VERIFICATION.md (Required Artifacts table — confirms `modules/modes.sh` is where the trap registration and resume banner live; this task adds the matching clean-exit flag-flip in the same file)+ - .planning/codebase/CONVENTIONS.md (Function Lifecycle — `end()` is the canonical workflow wrap-up; called by every workflow function in `modules/modes.sh`)+ </read_first>+ <action>+ Step A — Locate the `end()` function in `modules/modes.sh`. Use `grep -n '^function end()' modules/modes.sh` (preferred) or `grep -nE '^[[:space:]]*end\(\)[[:space:]]*\{' modules/modes.sh` if the bare form is used (CONVENTIONS.md mandates the `function name()` form for new code, but pre-existing siblings may use the bare form; honor whichever form is currently in the file).++ Find the LAST executable statement before the closing `}` of `end()`. This is typically a `return 0`, a logging call, an `export_reports` invocation, or similar. Insert the flag-flip on the line IMMEDIATELY BEFORE the closing `}`.++ The exact insertion:++ ```+ # Mark clean traversal so the EXIT trap's _cleanup_inprogress sweeps+ # .inprogress_* sentinels (D-02 clean-exit semantics; CR-01 fix). Any+ # path that bypasses end() — SIGINT/SIGTERM via cleanup_on_exit, an+ # internal abort like _abort_disk_full's exit 1, or an unhandled error+ # — leaves the flag at false and the sentinels survive to drive the+ # next run's resume banner.+ _RECON_CLEAN_EXIT=true+ }+ ```++ The closing `}` is the existing line, unchanged. The 6-line comment block above the assignment documents the asymmetric semantics (flag-set ONLY on clean traversal) so a future maintainer does not "helpfully" move the assignment to `cleanup_on_exit` or duplicate it in error paths — that would re-introduce the bug.++ DO NOT add the flag-flip anywhere else: not inside `cleanup_on_exit`, not inside `_abort_disk_full` (which is in `modules/utils.sh:445-455`; its `exit 1` deliberately bypasses the clean-exit path so post-disk-full re-runs see a fake resume — but per D-09 + the EXIT trap chain, the sentinels survive and on re-run the banner correctly fires, then the user re-tries with more disk; this is the desired UX), and not inside any per-workflow function (`recon`, `passive`, `all`, etc.). The single anchor inside `end()` is sufficient because every workflow function ends with a call to `end()` (this is the project's lifecycle contract per CONVENTIONS.md §Function Lifecycle).++ Step B — Sanity-check that every workflow function in `modules/modes.sh` calls `end()`. Run a verification grep BEFORE editing: `grep -nE '^[[:space:]]+end[[:space:]]*$|^[[:space:]]+end[[:space:]]*&&|^[[:space:]]+end$' modules/modes.sh` should return matches inside `recon`, `passive`, `all`, `vulns`, `osint`, `subs_menu`, `webs_menu`, `zen_menu`, and `monitor_mode`. If any workflow function does NOT call `end()`, document the gap in the SUMMARY.md as a separate finding (do NOT add a per-workflow flag-flip in this task — that would multiply the maintenance burden and re-introduce the duplicate-anchor problem). Per CONTEXT.md §Integration Points the project's lifecycle contract is that `end()` is universally called; if a workflow violates it, that is a pre-existing audit gap separate from CR-01.++ Constraint check: per the orchestrator's gap-closure context, no new bats tests are added in this phase (Phase 4 owns coverage). The behavioral smoke is the source of truth for "did the flag-flip land correctly."+ </action>+ <verify>+ <automated>bash -n /Users/six2dez/Tools/reconftw/modules/modes.sh && shellcheck -s bash --severity=error /Users/six2dez/Tools/reconftw/modules/modes.sh</automated>+ </verify>+ <acceptance_criteria>+ - `grep -c '_RECON_CLEAN_EXIT=true' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns exactly 1 (the flag-flip in `end()`).+ - The flag-flip is INSIDE the `end()` function body: `awk '/^function end\(\)|^end\(\)[[:space:]]*\{/,/^}/' /Users/six2dez/Tools/reconftw/modules/modes.sh | grep -c '_RECON_CLEAN_EXIT=true'` returns exactly 1.+ - The flag-flip is the LAST executable statement of `end()` (immediately before the closing `}`): extract `end()` body, find the line of the assignment, find the line of the closing `}`, assert that no other executable line (non-comment, non-blank) appears between them. Verification command: `awk '/^function end\(\)|^end\(\)[[:space:]]*\{/{inblock=1} inblock{print NR": "$0} /^}/ && inblock{inblock=0}' /Users/six2dez/Tools/reconftw/modules/modes.sh | awk '/_RECON_CLEAN_EXIT=true/{f=NR} /^[0-9]+: \}$/{c=NR} END{print (f && c && c == f+1) ? "LAST_OK" : "LAST_FAIL"}'` returns `LAST_OK` (or `LAST_OK` after a single blank/comment line is also acceptable; planner intent is "no other executable statement between flag-flip and `}`").+ - The flag-flip line is preceded by a comment block referencing CR-01: `awk '/^function end\(\)|^end\(\)[[:space:]]*\{/,/^}/' /Users/six2dez/Tools/reconftw/modules/modes.sh | grep -B6 '_RECON_CLEAN_EXIT=true' | grep -cE 'CR-01|clean traversal|D-02 clean-exit'` returns >=1.+ - No flag-flip leaked into `cleanup_on_exit`: `awk '/^function cleanup_on_exit\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/modules/utils.sh | grep -c '_RECON_CLEAN_EXIT=true'` returns 0.+ - No flag-flip leaked into `_abort_disk_full`: `awk '/^function _abort_disk_full\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/modules/utils.sh | grep -c '_RECON_CLEAN_EXIT=true'` returns 0.+ - `bash -n modules/modes.sh` exits 0.+ - `shellcheck -s bash --severity=error modules/modes.sh` exits 0 (no NEW error-level findings).+ - Behavior smoke (clean traversal flag-flip clears sentinels): write a temporary script `/tmp/clean_recheck.sh` that (1) sources `./reconftw.sh --source-only`, (2) `tmpd=$(mktemp -d); called_fn_dir=$tmpd; touch $tmpd/.inprogress_sub_brute`, (3) `_RECON_CLEAN_EXIT=false`, (4) installs the EXIT trap `trap '_cleanup_inprogress' EXIT`, (5) flips `_RECON_CLEAN_EXIT=true` (simulates `end()` running), (6) `exit 0`. After the subshell exits, `ls $tmpd/.inprogress_*` MUST be empty (the EXIT trap saw the flag=true and swept). Confirm with `[[ -z "$(ls $tmpd/.inprogress_* 2>/dev/null)" ]] && echo CLEAN_OK || echo CLEAN_FAIL`.+ - Behavior smoke (SIGINT path still preserves sentinel — combined with Task 1): repeat the `/tmp/sc1_recheck.sh` smoke from Task 1 acceptance criteria. With Task 2 also landed, the result MUST still be `SC1_OK` (sentinel preserved on SIGINT). This guards against the regression where the developer accidentally flips the flag too early (e.g., at the top of `start()` or inside `cleanup_on_exit`).+ - bats baseline holds: `bats tests/unit/` reports 246/246 PASS (no regressions from the flag-flip).+ - Workflow-coverage spot check: `grep -nE '^[[:space:]]+end[[:space:]]*$|^[[:space:]]+end[[:space:]]*&&|^[[:space:]]+end$' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns matches in at least 5 workflow functions (recon, passive, all, vulns, osint or similar). If any expected workflow function is missing, note in SUMMARY.md as a pre-existing gap but DO NOT add per-workflow flag-flips in this task.+ </acceptance_criteria>+ <done>+ `_RECON_CLEAN_EXIT=true` set as the last executable statement of `end()`, with a 6-line comment block above it documenting the clean-exit-only intent and the asymmetric placement rationale; no flag-flip leaked into error/abort paths; clean-exit smoke clears sentinels; SIGINT smoke still preserves them (combined Task 1+2 behavior); `bash -n` and `shellcheck` clean; 246/246 bats unit tests pass.+ </done>+</task>++<task type="auto">+ <name>Task 3: Update the misleading comment at `modules/core.sh:1431-1434` and reconcile `01-CONTEXT.md` D-02 wording</name>+ <files>modules/core.sh, .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md</files>+ <read_first>+ - modules/core.sh (lines 1419-1445 around `start_func`, especially the 4-line comment block at :1431-1434 with the "EXIT trap clears it on graceful exit" phrasing flagged by 01-VERIFICATION.md anti-pattern table)+ - .planning/phases/01-resilient-resume-timeout-safety/01-VERIFICATION.md (anti-pattern row at :136-137 — "modules/core.sh:1431-1434 Misleading comment 'EXIT trap clears it on graceful exit' INFO Documentation drift vs implementation")+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (D-02 at the second decision in the §Decisions block — current body says "Staleness detection uses trap-on-exit cleanup. start() in modules/modes.sh installs a trap on EXIT INT TERM that calls _cleanup_inprogress to rm -f $called_fn_dir/.inprogress_*. Graceful exits leave NO .inprogress_* files." The decision INTENT (graceful exits leave a tidy directory) is unchanged; the implementation MECHANISM (gated EXIT trap, not a chained INT/TERM/EXIT trap) is what needs rewording.)+ </read_first>+ <action>+ Step A — Rewrite the comment block at `modules/core.sh:1431-1434`. The current 4 lines (read with `awk 'NR>=1431 && NR<=1434' modules/core.sh`) are:++ ```+ # Resume sentinel (RESIL-01 / D-01): touch .inprogress_<fn> as a crash-leftover+ # marker. end_func removes it before touching .<fn>; EXIT trap clears it on+ # graceful exit. A leftover on the next run signals the function was killed+ # mid-execution and must re-run.+ ```++ Replace with (preserves the leading "Resume sentinel (RESIL-01 / D-01)" header but rewords the EXIT-trap sentence so SIGINT/SIGTERM semantics are explicit):++ ```+ # Resume sentinel (RESIL-01 / D-01): touch .inprogress_<fn> as a crash-leftover+ # marker. end_func removes it before touching .<fn>. The EXIT trap clears it+ # ONLY when end() sets _RECON_CLEAN_EXIT=true (clean traversal). SIGINT/SIGTERM+ # via cleanup_on_exit does NOT set the flag, so the sentinel survives and the+ # next run's resume banner fires (CR-01 / SC1 fix; see modules/modes.sh start()+ # and end() for the flag set/init points).+ ```++ The new block is 6 lines (was 4). DO NOT modify the `if [[ -n "${called_fn_dir:-}" ]]; then` block at :1435-1437 or the `log_json "INFO"` call at :1438 — only the comment block above the touch is rewritten.++ Step B — Update D-02 wording in `01-CONTEXT.md` to match implemented semantics. The current D-02 body (read at `awk '/^- \*\*D-02:\*\*/,/^- \*\*D-03:/' .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md`) reads:++ ```+ - **D-02:** Staleness detection uses **trap-on-exit cleanup**. `start()` in `modules/modes.sh` installs a trap on `EXIT INT TERM` that calls `_cleanup_inprogress` to `rm -f $called_fn_dir/.inprogress_*`. Graceful exits leave NO `.inprogress_*` files. Any leftover on the next invocation is a crash-leftover from a prior run and means the corresponding function must re-execute.+ ```++ Replace the body sentence-block (keep the `- **D-02:**` header) with:++ ```+ - **D-02:** Staleness detection uses **clean-exit-gated trap cleanup**. `start()` in `modules/modes.sh` initialises a module-level `_RECON_CLEAN_EXIT=false` flag and installs a separate EXIT-only trap calling `_cleanup_inprogress`. The trap sweep is gated on `_RECON_CLEAN_EXIT=true`, which is set as the last executable statement of `end()` (the canonical workflow wrap-up). Clean traversals therefore leave NO `.inprogress_*` files. SIGINT/SIGTERM (via the separate `cleanup_on_exit` trap that calls `exit 130`) does NOT flip the flag, so the EXIT trap fires with `_RECON_CLEAN_EXIT=false` and the sentinels SURVIVE — the next run sees them and emits the WARN resume banner (CR-01 / SC1 fix). The single-operator-per-target constraint (PROJECT.md) makes this race-free: no concurrent shell can observe a different flag value for the same `called_fn_dir`.+ ```++ Preserve the existing list-item dash and bold-header form so the §Decisions block remains parseable. Do NOT renumber D-03 onward — only D-02's body is rewritten.++ DO NOT modify any other decision (D-01, D-03..D-17). DO NOT remove the "Claude's Discretion" section or any other CONTEXT.md content. DO NOT modify the `<canonical_refs>` or `<code_context>` blocks — those describe artifacts and patterns that are still accurate.++ Step C — Append a one-line note to the §Implementation Decisions opening sentence noting that D-02 was clarified post-implementation. Find the line `### `.inprogress` Sentinel Lifecycle (Plan 01-01, RESIL-01)` (currently at `01-CONTEXT.md` around `:21`) and leave it unchanged; the D-02 reword above is the only edit in §Decisions. The clarification is recorded in this plan's SUMMARY.md (see <output> section), not in CONTEXT.md itself — CONTEXT.md represents the LOCKED decisions post-resolution.+ </action>+ <verify>+ <automated>bash -n /Users/six2dez/Tools/reconftw/modules/core.sh && shellcheck -s bash --severity=error /Users/six2dez/Tools/reconftw/modules/core.sh</automated>+ </verify>+ <acceptance_criteria>+ - The misleading sentence is removed from `modules/core.sh:1431-1434`: `grep -c 'EXIT trap clears it on graceful exit' /Users/six2dez/Tools/reconftw/modules/core.sh` returns exactly 0.+ - The new clean-exit-flag wording is present in `modules/core.sh` around the start_func sentinel comment: `grep -c '_RECON_CLEAN_EXIT=true' /Users/six2dez/Tools/reconftw/modules/core.sh` returns >=1 (the comment block now references the flag name); `grep -c 'CR-01' /Users/six2dez/Tools/reconftw/modules/core.sh` returns >=1.+ - The header `# Resume sentinel (RESIL-01 / D-01)` is preserved: `grep -c '# Resume sentinel (RESIL-01 / D-01)' /Users/six2dez/Tools/reconftw/modules/core.sh` returns exactly 1.+ - The sentinel touch logic is UNCHANGED: `grep -c 'touch "\$called_fn_dir/\.inprogress_\${1}" 2>/dev/null || true' /Users/six2dez/Tools/reconftw/modules/core.sh` returns exactly 1 (the existing line at :1436, unchanged in payload).+ - D-02 wording is updated in `01-CONTEXT.md`: `grep -c 'clean-exit-gated trap cleanup' /Users/six2dez/Tools/reconftw/.planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md` returns exactly 1; `grep -c 'CR-01 / SC1 fix' /Users/six2dez/Tools/reconftw/.planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md` returns exactly 1.+ - The original "trap on `EXIT INT TERM`" wording is removed from D-02: `awk '/^- \*\*D-02:\*\*/,/^- \*\*D-03:/' /Users/six2dez/Tools/reconftw/.planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md | grep -c 'EXIT INC TERM\|EXIT INT TERM'` returns exactly 0.+ - D-02 still references `_cleanup_inprogress` (the implemented helper name): `awk '/^- \*\*D-02:\*\*/,/^- \*\*D-03:/' /Users/six2dez/Tools/reconftw/.planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md | grep -c '_cleanup_inprogress'` returns >=1.+ - Other decisions are unchanged: `grep -c '^- \*\*D-01:\*\*' /Users/six2dez/Tools/reconftw/.planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md` returns 1; `grep -c '^- \*\*D-03:\*\*' ...` returns 1; through D-17 each returns 1 (no decisions added, removed, or renumbered). Use: `for i in 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17; do printf "D-%s: " "$i"; grep -c "^- \*\*D-$i:\*\*" /Users/six2dez/Tools/reconftw/.planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md; done` MUST report `D-01: 1`, `D-02: 1`, ... `D-17: 1`.+ - `bash -n modules/core.sh` exits 0 (comment-only change must not break syntax).+ - `shellcheck -s bash --severity=error modules/core.sh` exits 0 (no new findings; comment text is irrelevant to shellcheck).+ - Combined-plan smoke (Task 1 + 2 + 3): a fresh `bash -c './reconftw.sh --health-check'` (a safe entry that runs `start()` and `end()` cleanly) must (1) exit 0, (2) NOT leave any `.inprogress_*` files in the resolved `called_fn_dir`, (3) NOT print "Interrupted. Cleaning up..." anywhere. This is the happy-path regression check.+ - Final SC1 reproduction (from 01-VERIFICATION.md `/tmp/sc1_v3.sh`): re-run the verifier's exact reproduction script with `--gaps-only`-equivalent setup. Seed `.inprogress_sub_brute` and `.sub_passive`, install both traps with `_RECON_CLEAN_EXIT=false` default, send SIGINT, list `called_fn_dir`. The output MUST list BOTH files (with the pre-patch code only `.sub_passive` survived). This single test transitions SC1 from PARTIAL → VERIFIED for the next verifier run.+ </acceptance_criteria>+ <done>+ Comment block at `modules/core.sh:1431-1434` rewritten so the documented behavior matches the gated-trap implementation (no more "EXIT trap clears on graceful exit" misleading phrasing); `01-CONTEXT.md` D-02 body rewritten to reflect clean-exit-gated semantics, the `_RECON_CLEAN_EXIT` flag, and the SC1 indicator survival on SIGINT/SIGTERM; all other decisions (D-01, D-03..D-17) unchanged; SC1 reproduction now shows the indicator surviving SIGINT.+ </done>+</task>++</tasks>++<verification>+- `bash -n modules/core.sh modules/modes.sh modules/utils.sh` → exit 0.+- `shellcheck -s bash --severity=error modules/core.sh modules/modes.sh modules/utils.sh` → exit 0 (no NEW error-level findings vs baseline).+- `bats tests/unit/` → 246/246 PASS (no new tests in this phase per CONTEXT.md §Claude's Discretion; the baseline must hold).+- `bats tests/security/` → 34/34 PASS (or whatever the current security-bats count is; verify no regressions).+- Behavioral smokes (composed Task 1 + 2 + 3):+ 1. SC1 indicator survives SIGINT (the verifier's CR-01 reproduction inverted): seed `${tmpd}/.inprogress_sub_brute` and `${tmpd}/.sub_passive`, source `./reconftw.sh --source-only`, install both traps with `_RECON_CLEAN_EXIT=false`, send SIGINT. After the subshell exits, `ls ${tmpd}` MUST list BOTH files. Pre-patch the same script wipes `.inprogress_sub_brute`; post-patch both survive.+ 2. Clean traversal sweeps sentinels (the happy-path invariant): same setup but the subshell calls `_RECON_CLEAN_EXIT=true; exit 0` (simulating `end()` flipping the flag). After exit, `ls ${tmpd}/.inprogress_*` MUST be empty.+ 3. INT/TERM banner unchanged: a real or simulated `./reconftw.sh ... ` SIGINT MUST still print "Interrupted. Cleaning up..." from `cleanup_on_exit` and exit 130. The new flag must not interfere with the existing user-visible interruption signal.+ 4. `--health-check` happy path: `./reconftw.sh --health-check` (the safest existing entry) exits 0, leaves no `.inprogress_*`, does NOT print "Interrupted...".+ 5. CONTEXT.md D-02 reword: `awk '/^- \*\*D-02:\*\*/,/^- \*\*D-03:/' .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md` prints the new clean-exit-gated phrasing and references `_RECON_CLEAN_EXIT`.+ 6. core.sh comment reword: `awk 'NR>=1430 && NR<=1442' modules/core.sh` shows the new 6-line block referencing `_RECON_CLEAN_EXIT=true`, `clean traversal`, and `CR-01`. The line `EXIT trap clears it on graceful exit` MUST NOT appear anywhere in the file.+</verification>++<success_criteria>+- Gap A from `01-VERIFICATION.md` is closed: SC1 transitions PARTIAL → VERIFIED. The `.inprogress_<fn>` indicator survives SIGINT/SIGTERM so the next run's WARN resume banner fires correctly.+- `cleanup_on_exit` is NOT modified — the loud "Interrupted. Cleaning up..." banner and forced `exit 130` remain the user-facing interruption signal.+- The EXIT trap is NOT removed entirely — the orchestrator's chosen clean-exit-flag approach preserves the original D-02 intent (graceful runs leave a tidy directory) while honoring SC1 (Ctrl+C leaves the indicator).+- `_RECON_CLEAN_EXIT` flag follows the project's UPPER_SNAKE_CASE runtime-state global naming convention (CONVENTIONS.md §Variable Naming).+- No new bats tests are added in this phase (Phase 4 owns test coverage per CONTEXT.md §Claude's Discretion; the 246/246 bats unit count is preserved as the baseline-hold check).+- `01-CONTEXT.md` D-02 wording is consistent with the implemented semantics — future verifiers do not flag the same inconsistency.+- The misleading comment at `modules/core.sh:1431-1434` is updated; the anti-pattern row in 01-VERIFICATION.md (line 137) is resolved.+- All three smokes (SC1 survival, clean sweep, INT banner unchanged) pass.+</success_criteria>++<output>+After completion, create `.planning/phases/01-resilient-resume-timeout-safety/01-04-SUMMARY.md`.++The SUMMARY should explicitly note:+- Gap A (CR-01) closed; SC1 verifier status transitions PARTIAL → VERIFIED on next verifier run+- `_RECON_CLEAN_EXIT` flag pattern established for future gated-trap work (Phase 5 documentation candidate)+- `01-CONTEXT.md` D-02 was rewritten in-place — the locked decision intent is preserved, only the implementation-mechanism phrasing changed; downstream consumers of CONTEXT.md (researchers, planners, verifiers) read the updated body and see the gated-trap semantics directly+- The behavioral smoke `/tmp/sc1_v3.sh` (or local equivalent) reproduces the SC1 indicator-survives behavior; this is the next verifier's check+- No bats tests added; Phase 4 owns coverage+</output>+</content>diff --git a/.planning/phases/01-resilient-resume-timeout-safety/01-05-PLAN.md b/.planning/phases/01-resilient-resume-timeout-safety/01-05-PLAN.mdnew file mode 100644index 0000000..b8b5ee8--- /dev/null+++ b/.planning/phases/01-resilient-resume-timeout-safety/01-05-PLAN.md@@ -0,0 +1,392 @@+---+id: 01-05+phase: 01+plan: 05+type: execute+wave: 3+depends_on: []+requirements: [RESIL-03]+gap_closure: true+closes_gaps: [CR-02, CR-03]+files_modified:+ - lib/parallel.sh+autonomous: true+must_haves:+ truths:+ - "Setting `PARALLEL_JOB_TIMEOUT_SECONDS=600` under `--quiet` (OUTPUT_VERBOSITY=0) terminates any parallel_funcs child that exceeds 600s — the verbosity gate at `lib/parallel.sh:469` and `:579` is decoupled from the timeout-enforcement gate, so CI runs (the documented primary use case per `reconftw.cfg:317`) get timeout enforcement (closes CR-02 / SC3 defect #1)"+ - "On timeout kill, the actual external tool process (puredns, massdns, dnsx, ffuf, axiom-scan, etc.) terminates — not just the parallel_funcs wrapper subshell. `_timeout_kill_job` walks the process tree of the wrapper PID via a `pgrep -P`-based recursive child kill (with a process-group kill fallback) so the entire job hierarchy is signaled, not just `$!` (closes CR-03 / SC3 defect #2)"+ - "Heartbeat snapshots (the UI side of the loop) are STILL gated on `OUTPUT_VERBOSITY >= 1` — only the timeout-enforcement check and the kill mechanism are decoupled. Under `--quiet` the loop runs but emits no heartbeat lines, exactly mirroring the user's intent (quiet = no UI noise, NOT quiet = no timeout enforcement)."+ - "Two-loop symmetry preserved: both the batch-flush heartbeat at `lib/parallel.sh:467-506` (post-edit line numbers will shift) AND the final-wait heartbeat at `lib/parallel.sh:577-616` get the decoupled gate AND the kill-tree behavior. No regression of the existing two-loop discipline established by Plan 01-03."+ - "macOS/BSD compatibility maintained: `pgrep -P` is available on both BSD and GNU procps (CLAUDE.md §macOS compatibility). No reliance on `setsid` (Linux-only) or GNU-`ps`-only flags. Fallback path uses portable `ps -p $pid -o pgid=` cross-checked with `pgrep -P` walk so a missing-`pgrep` host gracefully degrades to wrapper-only kill (the current pre-patch behavior) rather than failing the run."+ - "Default `PARALLEL_JOB_TIMEOUT_SECONDS=0` is preserved (locked by D-11); the feature remains opt-in and backwards-compatible. No CI deadline becomes more aggressive by default."+ code_landmarks:+ - "Decoupled gate at `lib/parallel.sh:469`: split the compound condition `[[ ${PARALLEL_MODE} == true ]] && [[ ${OUTPUT_VERBOSITY:-1} -ge 1 ]] && [[ $hb =~ ^[0-9]+$ ]] && ((hb > 0))` into two booleans — `_loop_active` (true if PARALLEL_MODE=true AND hb is a positive integer) AND a separate inner `_verbose_progress` (true if OUTPUT_VERBOSITY >= 1) that gates ONLY the `_parallel_snapshot` call. Read `_to=${PARALLEL_JOB_TIMEOUT_SECONDS:-0}` once outside the loop; the loop runs when `_loop_active && (_verbose_progress || _to > 0)`. Heartbeat snapshots fire only when `_verbose_progress=true`."+ - "Same decoupled gate at `lib/parallel.sh:579` (final-wait heartbeat) — two-loop symmetry is mandatory per PATTERNS.md."+ - "`_timeout_kill_job` body at `lib/parallel.sh:53-77`: replace the single `kill -TERM $pid` / `kill -KILL $pid` pair with a `_kill_tree` helper that walks descendants via `pgrep -P` and signals each leaf (and the root). The persistence writes (`.status_<fn>=FAIL`, `.status_reason_<fn>=timeout`) and the `log_json` call remain unchanged — only the kill mechanism is replaced."+ - "New private helper `_kill_tree` (or equivalent inlined logic) declared above `_timeout_kill_job` (after `_throttle_jobs` at :42 and before `_timeout_kill_job` at :53). Uses `function _kill_tree() {` form per CONVENTIONS.md §Function Naming (project-wide rule)."+ - "Optional process-group fallback at `lib/parallel.sh:432-438` (the wrapper-subshell spawn site): consider launching the wrapper as a job in its own process group via the existing `set +m` toggling. Note however that `start()` at `modules/modes.sh:16` explicitly disables job control (`set +m 2>/dev/null || true`); resurrecting job control just for this corner case is intrusive. PREFER the `pgrep -P` walk in `_kill_tree` over the pgid approach — fewer side effects, no `set -m` flip needed."+ behavioral_checks:+ - "Smoke 1 (CR-02 reproduction — timeout fires under --quiet): set `PARALLEL_JOB_TIMEOUT_SECONDS=2`, `PARALLEL_KILL_GRACE_SECONDS=1`, `PARALLEL_HEARTBEAT_SECONDS=1`, `OUTPUT_VERBOSITY=0` (the `--quiet` mode). Run `parallel_funcs 1 my_slow_func` where `function my_slow_func() { sleep 30; }`. Within ~5 seconds the job MUST be killed; `.status_my_slow_func` MUST contain `FAIL`; `.status_reason_my_slow_func` MUST contain `timeout`. With the pre-patch code (verbosity-gated loop) the same setup runs `sleep 30` to completion without killing it — verify the wallclock difference is the smoke signal."+ - "Smoke 2 (CR-03 reproduction — inner tool dies too): set `PARALLEL_JOB_TIMEOUT_SECONDS=2`, `PARALLEL_KILL_GRACE_SECONDS=1`, `OUTPUT_VERBOSITY=1`. Define `function my_slow_func() { sleep 30 & local inner=$!; echo $inner > /tmp/inner.pid; wait; }`. Run `parallel_funcs 1 my_slow_func`. After ~5s, both the wrapper subshell AND `cat /tmp/inner.pid | xargs -I{} kill -0 {} 2>/dev/null` MUST return non-zero (inner `sleep 30` is dead). With the pre-patch code the inner sleep keeps running as an orphan to PID 1 — verify with `ps -p $(cat /tmp/inner.pid) -o stat= 2>/dev/null` returning empty post-patch."+ - "Smoke 3 (heartbeat UI still gated on verbosity): set `PARALLEL_JOB_TIMEOUT_SECONDS=0` (disabled — backwards-compat baseline), `OUTPUT_VERBOSITY=0`, `PARALLEL_HEARTBEAT_SECONDS=1`. Run a `parallel_funcs 1 normal_func` where `function normal_func() { sleep 5; }`. The function MUST complete to natural exit (no kill); the console MUST NOT print any heartbeat lines under verbosity 0. Same setup with `OUTPUT_VERBOSITY=1` MUST print heartbeat snapshots. This proves the UI gate is unchanged while only the timeout-enforcement gate was decoupled."+ - "Smoke 4 (default-disabled backwards compat): `PARALLEL_JOB_TIMEOUT_SECONDS=0` (the shipped default), `OUTPUT_VERBOSITY=1`. Run `parallel_funcs 1 normal_func`. Behavior MUST be identical to pre-patch — no kill, no FAIL persistence, just heartbeats and natural completion."+ - "Smoke 5 (two-loop symmetry — final-wait path also gets the decoupled gate and kill-tree): set `PARALLEL_MAX_JOBS=2`, `PARALLEL_JOB_TIMEOUT_SECONDS=2`, `OUTPUT_VERBOSITY=0`. Submit a 3-function batch where only the 3rd function is slow (sleeps 30). The first 2 functions trigger the batch-flush loop (handled by the modified batch-flush heartbeat); the 3rd function falls into the final-wait loop. The 3rd function MUST be killed by the final-wait loop's timeout enforcement — verify via the `.status_slow_3=FAIL`, `.status_reason_slow_3=timeout` files."+ - "Smoke 6 (macOS pgrep-P availability): `command -v pgrep && pgrep -P $$ >/dev/null; echo $?` returns 0 on both Linux and macOS (BSD). If the executor's host happens to lack `pgrep` (extremely rare), the fallback path falls through to wrapper-only kill (the pre-patch behavior) — this is acceptable degradation per CLAUDE.md §macOS compatibility."+ - "Smoke 7 (bats baseline holds): `bats tests/unit/` reports 246/246 PASS — no regressions from the lib/parallel.sh changes. No new tests added in this phase (Phase 4 / TEST-01 explicitly covers parallel_funcs timeout-kill coverage per CONTEXT.md)."+---++<objective>+Close the two compound defects that make Plan 01-03's `PARALLEL_JOB_TIMEOUT_SECONDS` enforcement silently disabled under `--quiet` (CR-02) and ineffective at stopping the underlying tool (CR-03). Both fixes live in `lib/parallel.sh` and share the same change site, so they are bundled into one plan rather than artificially split.++Purpose: 01-VERIFICATION.md marked SC3 PARTIAL with two compound defects.+- **CR-02 (Gap B):** The timeout-kill check sits inside `if [[ ${PARALLEL_MODE} == true ]] && [[ ${OUTPUT_VERBOSITY:-1} -ge 1 ]] ...` at `lib/parallel.sh:469` and `:579`. Under `--quiet` (OUTPUT_VERBOSITY=0) the entire while-loop is skipped — no timeout-kill runs. The cfg comment at `reconftw.cfg:314-317` explicitly recommends `PARALLEL_JOB_TIMEOUT_SECONDS=600` for CI, and CI runs are precisely where `--quiet` is used → the feature is silently disabled in its documented primary use case.+- **CR-03 (Gap C):** `_timeout_kill_job` at `lib/parallel.sh:53-77` signals the wrapper subshell PID stored in `batch_pids[$idx]` (the `$!` of the `(...) >$log_file &` at `:438`). SIGTERM to a Bash subshell does NOT auto-propagate to its children. Verified empirically: the wrapper dies but `sleep 30` (acting as a stand-in for puredns/dnsx/ffuf) keeps running orphaned to PID 1. On axiom-distributed runs the remote workers also keep going because the local `axiom-scan` wrapper is the orphan path.++Both defects undermine SC3's headline guarantee ("terminates any single `parallel_funcs` child exceeding 10 minutes via kill -TERM, allowing the batch to continue") — the BATCH does continue, but the actual TOOL doesn't terminate. This plan closes both.++Output:+- `lib/parallel.sh`: decoupled gate at the two heartbeat-loop entry conditions (`:469` and `:579`). The loop runs when (timeout is enabled) OR (verbosity wants UI). Heartbeat snapshots fire only on the verbosity arm; timeout enforcement fires unconditionally inside the loop body.+- `lib/parallel.sh`: new private helper `_kill_tree` (declared above `_timeout_kill_job` near the existing `_throttle_jobs` at :33-42) that walks the process tree via `pgrep -P` and signals each descendant. Falls back to wrapper-only kill if `pgrep` is unavailable (CLAUDE.md macOS compatibility).+- `lib/parallel.sh`: `_timeout_kill_job` body updated to call `_kill_tree $pid TERM`, poll up to `PARALLEL_KILL_GRACE_SECONDS`, then `_kill_tree $pid KILL` if still alive. The persistence writes (FAIL + reason=timeout) and `log_json` call remain unchanged — only the kill mechanism is replaced.+- `reconftw.cfg`: NO changes (the existing comment at `:317` is already accurate post-fix; D-11 default `0` and D-13 grace `10` remain locked).++No new tests; Phase 4 (TEST-01) covers parallel_funcs timeout-kill regression coverage per CONTEXT.md §Claude's Discretion.+</objective>++<execution_context>+@$HOME/.claude/get-shit-done/workflows/execute-plan.md+@$HOME/.claude/get-shit-done/templates/summary.md+</execution_context>++<context>[email protected]/PROJECT.md[email protected]/ROADMAP.md[email protected]/STATE.md[email protected]/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md[email protected]/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md[email protected]/phases/01-resilient-resume-timeout-safety/01-VERIFICATION.md[email protected]/phases/01-resilient-resume-timeout-safety/01-REVIEW.md[email protected]/phases/01-resilient-resume-timeout-safety/01-03-SUMMARY.md[email protected]/codebase/CONVENTIONS.md++<interfaces>+<!-- Key existing identifiers the executor will modify. Extracted from lib/parallel.sh. -->++From lib/parallel.sh (post-Plan-01-03 state):+- Source guard at `:6`: `[[ -n "$_PARALLEL_SH_LOADED" ]] && return 0`. UNCHANGED.+- `_throttle_jobs()` at `:33-42`. Sibling style for new `_kill_tree` helper. Uses bare `name() {` form (pre-dates CONVENTIONS.md rule — see Plan 01-03's DOCS-01 followup note for context).+- `_timeout_kill_job()` at `:53-77`. Current body uses `kill -TERM "$pid"` / `kill -KILL "$pid"` against the single wrapper PID. THIS is what gets refactored to use `_kill_tree`. The function uses canonical `function name() {` form per CONVENTIONS.md.+- `_parallel_live_break()` at `:79-83`. UNCHANGED. New `_kill_tree` helper inserts BETWEEN `_throttle_jobs` (closes at :42) and `_timeout_kill_job` (opens at :53).+- Batch-flush heartbeat loop at `:467-506`. Current gate at `:469`: `if [[ "${PARALLEL_MODE:-true}" == "true" ]] && [[ "${OUTPUT_VERBOSITY:-1}" -ge 1 ]] && [[ "$hb" =~ ^[0-9]+$ ]] && ((hb > 0)); then`. The timeout-enforcement block is inside this gated `if` at `:481-486` (added by Plan 01-03). THIS gate gets decoupled.+- Final-wait heartbeat loop at `:577-616`. Identical structure to batch-flush; same gate at `:579`. Same insertion: decouple the verbosity check from the timeout-enforcement check.+- Wrapper-subshell spawn site at `:432-438`: `(...) >"$log_file" 2>&1 &; batch_pids+=("$!")`. UNCHANGED — the pgid approach was rejected (see code_landmarks above) because `set +m` at `modules/modes.sh:16` deliberately disables job control. The `_kill_tree` walk operates against the existing wrapper PID.++From modules/modes.sh:+- `start()` at `:16`: `set +m 2>/dev/null || true`. This explicitly disables job control globally, which is why the process-group approach was rejected. The `_kill_tree` recursive walk is the portable approach.++From CLAUDE.md §macOS compatibility:+- macOS Homebrew Bash is required (`bash` 4.3+); `pgrep` from procps (Linux) and from `procps-ng` (or BSD-native `pgrep` on macOS) both support `-P <ppid>`. POSIX-portable enough for reconftw's supported targets. `ps` flag differences (`-o pgid=` on BSD vs `o pgid=` on GNU) are sidestepped by using `pgrep -P` (which is universal for the "list children of PID" use case).+</interfaces>+</context>++<tasks>++<task type="auto">+ <name>Task 1: Decouple timeout-enforcement gate from verbosity gate in both heartbeat loops</name>+ <files>lib/parallel.sh</files>+ <read_first>+ - lib/parallel.sh (entire heartbeat-loop regions at :467-506 batch-flush and :577-616 final-wait — note the existing compound gate at :469 and :579, the `_to` declaration inside the inner loop at :483 and :593, and the `_parallel_snapshot` call inside the verbosity-snapshot branch at :501 and :611)+ - .planning/phases/01-resilient-resume-timeout-safety/01-VERIFICATION.md (CR-02 missing item: "Decouple timeout enforcement from heartbeat UI gate. Run the boundary while-loop whenever PARALLEL_JOB_TIMEOUT_SECONDS > 0 OR OUTPUT_VERBOSITY >= 1; emit heartbeat snapshots only on the verbosity arm.")+ - .planning/phases/01-resilient-resume-timeout-safety/01-REVIEW.md (CR-02 — exact code snippet of the recommended fix; the planner's role is to translate that recommendation into a concrete patch with line-level acceptance criteria)+ - .planning/phases/01-resilient-resume-timeout-safety/01-03-SUMMARY.md (Plan 01-03's two-loop-symmetry pattern note: "any block added to the batch-flush heartbeat must also be added to the final-wait heartbeat (and vice versa)")+ - .planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md (anchor "lib/parallel.sh — heartbeat-loop timeout enforcement", §"Two-loop symmetry")+ </read_first>+ <action>+ Step A — In the BATCH-FLUSH heartbeat loop at `lib/parallel.sh:467-506`, replace the existing compound gate at `:469`:++ Existing (post-Plan-01-03 state — actual line numbers may have shifted slightly but the structure is intact):++ ```+ # Heartbeat while long-running jobs are executing, to avoid "stuck" perception.+ local hb="${PARALLEL_HEARTBEAT_SECONDS:-20}"+ if [[ "${PARALLEL_MODE:-true}" == "true" ]] && [[ "${OUTPUT_VERBOSITY:-1}" -ge 1 ]] && [[ "$hb" =~ ^[0-9]+$ ]] && ((hb > 0)); then+ local last_hb now alive hb_active_list job_dur dur_fmt queue_count batch_elapsed hb_done_count+ ...+ while :; do+ ...+ for idx in "${!batch_pids[@]}"; do+ if kill -0 "${batch_pids[$idx]}" 2>/dev/null; then+ alive=1+ job_dur=$((now - batch_starts[$idx]))+ # Timeout enforcement (RESIL-03 / D-11..D-14)+ local _to="${PARALLEL_JOB_TIMEOUT_SECONDS:-0}"+ if [[ "$_to" =~ ^[0-9]+$ ]] && (( _to > 0 )) && (( job_dur > _to )); then+ _timeout_kill_job "${batch_pids[$idx]}" "${batch_funcs[$idx]}" "$job_dur"+ fi+ ...+ fi+ done+ ((alive == 0)) && break+ if ((now - last_hb >= hb)); then+ ...+ _parallel_snapshot ...+ last_hb=$now+ fi+ sleep 1+ done+ fi+ ```++ Rewrite the entry-gate block. The new structure: read `_to` and `_verbose_progress` ONCE before the loop entry (hoisted out of the hot inner loop per CR-related WR-02 advisory in 01-REVIEW.md §IN-02 micro-optimization, which is a clean co-fix here), then enter the loop when `_to > 0 OR _verbose_progress=true`:++ ```+ # Heartbeat while long-running jobs are executing, to avoid "stuck" perception.+ # Loop runs when EITHER timeout enforcement is active OR verbose progress is on;+ # snapshots fire only when verbose progress is on. Decoupled per CR-02 fix so+ # PARALLEL_JOB_TIMEOUT_SECONDS works under --quiet (the documented CI scenario at+ # reconftw.cfg:317).+ local hb="${PARALLEL_HEARTBEAT_SECONDS:-20}"+ local _to="${PARALLEL_JOB_TIMEOUT_SECONDS:-0}"+ [[ "$_to" =~ ^[0-9]+$ ]] || _to=0+ local _verbose_progress=false+ [[ "${PARALLEL_MODE:-true}" == "true" ]] && [[ "${OUTPUT_VERBOSITY:-1}" -ge 1 ]] && _verbose_progress=true+ local _loop_active=false+ [[ "${PARALLEL_MODE:-true}" == "true" ]] && [[ "$hb" =~ ^[0-9]+$ ]] && ((hb > 0)) && _loop_active=true+ if [[ "$_loop_active" == "true" ]] && { [[ "$_verbose_progress" == "true" ]] || (( _to > 0 )); }; then+ local last_hb now alive hb_active_list job_dur dur_fmt queue_count batch_elapsed hb_done_count+ last_hb=$(date +%s)+ while :; do+ alive=0+ hb_done_count=0+ hb_active_list=""+ now=$(date +%s)+ for idx in "${!batch_pids[@]}"; do+ if kill -0 "${batch_pids[$idx]}" 2>/dev/null; then+ alive=1+ job_dur=$((now - batch_starts[$idx]))+ # Timeout enforcement (RESIL-03 / D-11..D-14): fires regardless of+ # verbosity (CR-02 fix). Uses hoisted _to from outer scope.+ if (( _to > 0 )) && (( job_dur > _to )); then+ _timeout_kill_job "${batch_pids[$idx]}" "${batch_funcs[$idx]}" "$job_dur"+ fi+ dur_fmt=$(format_duration "$job_dur")+ if [[ -z "$hb_active_list" ]]; then+ hb_active_list="${batch_funcs[$idx]} ${dur_fmt}"+ else+ hb_active_list="${hb_active_list}, ${batch_funcs[$idx]} ${dur_fmt}"+ fi+ else+ hb_done_count=$((hb_done_count + 1))+ fi+ done+ ((alive == 0)) && break+ if [[ "$_verbose_progress" == "true" ]] && ((now - last_hb >= hb)); then+ queue_count=$((total_funcs - queued_count))+ batch_elapsed=$((now - batch_start_ts))+ _parallel_snapshot "${hb_active_list:-none}" "$done_list" "$queue_count" "$hb_done_count" "${#batch_pids[@]}" "$batch_elapsed"+ last_hb=$now+ fi+ sleep 1+ done+ fi+ ```++ Key changes:+ 1. `_to`, `_verbose_progress`, `_loop_active` declared and computed ONCE outside the inner loop (was per-iteration before — IN-02 micro-fix folded in).+ 2. The loop-entry condition is now `_loop_active AND (_verbose_progress OR _to > 0)`.+ 3. The timeout-enforcement `if` inside the loop body drops the `[[ "$_to" =~ ^[0-9]+$ ]]` regex check (already validated outside the loop) and is no longer behind any verbosity gate.+ 4. The `_parallel_snapshot` call is now wrapped in an explicit `if [[ "$_verbose_progress" == "true" ]] && ...; then` — heartbeat UI fires only when verbosity wants it; timeout still fires unconditionally.++ DO NOT remove the `[[ "${PARALLEL_MODE:-true}" == "true" ]]` part of the gate — disabling parallel mode entirely should still bypass both the timeout-enforcement AND the snapshots (no batch is running, no PID to kill, no UI to show). The `_loop_active` boolean captures this.++ DO NOT remove the `[[ "$hb" =~ ^[0-9]+$ ]] && ((hb > 0))` check — if heartbeat is misconfigured to a non-positive value, the loop's `sleep 1` cadence would still work, but the `last_hb`/`now - last_hb >= hb` math becomes meaningless. Acknowledging the WR-05 concern from 01-REVIEW.md: per-the-advisory, document this in the new comment block above the gate (added in this task). Honour the existing semantic that `PARALLEL_HEARTBEAT_SECONDS=0` disables the loop entirely. If a future user sets both `PARALLEL_HEARTBEAT_SECONDS=0` AND `PARALLEL_JOB_TIMEOUT_SECONDS=600`, the timeout enforcement is also disabled — this is the existing behavior; WR-05 in 01-REVIEW.md flagged it as a documentation concern, not a blocking gap. Add an inline comment near the `_loop_active` declaration: `# NB: PARALLEL_HEARTBEAT_SECONDS=0 disables the loop entirely, which also disables timeout enforcement. WR-05 documented this; resolve in Phase 5 DOCS-01 if it surfaces in practice.`++ Step B — Apply the IDENTICAL refactor to the FINAL-WAIT heartbeat loop at `lib/parallel.sh:577-616`. The structure is character-for-character the same as the batch-flush loop above; the same hoisted-locals + decoupled gate + unconditional timeout check + verbosity-gated snapshot pattern goes in. Two-loop symmetry is mandatory per Plan 01-03's established pattern (and the 01-PATTERNS.md §"Two-loop symmetry" entry).++ DO NOT introduce subtle differences between the two loops (different gate ordering, different boolean name, different comment wording). The grep-based acceptance criteria below check that both loops have the same shape.++ Step C — Verify NO other gates need decoupling. Search the rest of `lib/parallel.sh` for any other `OUTPUT_VERBOSITY`-gated block that contains a timeout reference: `grep -n 'OUTPUT_VERBOSITY' lib/parallel.sh` and inspect each match. The only matches that gate timeout enforcement are the two heartbeat loops. Other matches (`_parallel_should_show_started`, `_parallel_should_show_finished`, the per-mode rendering branches in `_parallel_emit_job_output`) are UI-only and stay verbosity-gated as designed.+ </action>+ <verify>+ <automated>bash -n /Users/six2dez/Tools/reconftw/lib/parallel.sh && shellcheck -s bash --severity=error /Users/six2dez/Tools/reconftw/lib/parallel.sh</automated>+ </verify>+ <acceptance_criteria>+ - The compound verbosity-AND-timeout-AND-everything gate at the old `:469` is GONE: `grep -cE '"\${PARALLEL_MODE:-true}" == "true" \]\] && \[\[ "\${OUTPUT_VERBOSITY:-1}" -ge 1 \]\] && \[\[ "\$hb" =~' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns 0 (the all-in-one compound gate is replaced by the hoisted-booleans pattern).+ - `_to`, `_verbose_progress`, `_loop_active` locals appear: `grep -c 'local _to="\${PARALLEL_JOB_TIMEOUT_SECONDS:-0}"' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 2 (one per loop — two-loop symmetry); `grep -c 'local _verbose_progress=false' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 2; `grep -c 'local _loop_active=false' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 2.+ - The new compound gate fires the loop when `_loop_active && (_verbose_progress || _to > 0)`: `grep -cE 'if \[\[ "\$_loop_active" == "true" \]\] && \{ \[\[ "\$_verbose_progress" == "true" \]\] \|\| \(\( _to > 0 \)\); \};' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 2.+ - Timeout-enforcement check inside the loop body no longer references verbosity (it's now unconditional inside the loop): `awk '/if \[\[ "\$_loop_active"/,/^[[:space:]]+fi[[:space:]]*$/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c '(( _to > 0 )) && (( job_dur > _to ))'` returns >=2 (one per loop; awk range matches both).+ - `_parallel_snapshot` call is wrapped in a verbosity guard: `grep -cE 'if \[\[ "\$_verbose_progress" == "true" \]\] && \(\(now - last_hb >= hb\)\); then' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 2.+ - The CR-02 explanatory comment is present: `grep -c 'CR-02 fix' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns >=2 (one per loop).+ - The WR-05 documentation note is present: `grep -c 'WR-05' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns >=2 (one per loop) OR a single shared upstream comment block that both loops reference.+ - No other `OUTPUT_VERBOSITY`-gated block was inadvertently modified: `grep -n 'OUTPUT_VERBOSITY' lib/parallel.sh` shows the existing UI-only branches (e.g., `_parallel_should_show_started`, the rendering branches in `_parallel_emit_job_output`) unchanged. Spot-check via `grep -c '_parallel_should_show_started' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns the same count as pre-patch.+ - Two-loop symmetry holds — the same patterns appear in both loops: the four key patterns (`local _to=...`, `local _verbose_progress=false`, `local _loop_active=false`, the decoupled compound gate) each return exactly 2 occurrences as asserted above.+ - `bash -n lib/parallel.sh` exits 0.+ - `shellcheck -s bash --severity=error lib/parallel.sh` exits 0 (no NEW error-level findings vs baseline).+ - Behavior smoke (CR-02 reproduction): write `/tmp/quiet_timeout.sh` that sources `./reconftw.sh --source-only`, defines `function my_slow_func() { sleep 30; }`, sets `called_fn_dir=$(mktemp -d) PARALLEL_JOB_TIMEOUT_SECONDS=2 PARALLEL_KILL_GRACE_SECONDS=1 PARALLEL_HEARTBEAT_SECONDS=1 PARALLEL_MODE=true OUTPUT_VERBOSITY=0`, then runs `time parallel_funcs 1 my_slow_func`. The job MUST be killed within ~5 seconds (pre-patch: 30+ seconds because the loop never runs under verbosity 0). Verify `cat $called_fn_dir/.status_my_slow_func` shows `FAIL` and `cat $called_fn_dir/.status_reason_my_slow_func` shows `timeout`. The console MUST NOT show heartbeat lines (verbosity 0).+ - Behavior smoke (verbosity-1 unchanged): same script but with `OUTPUT_VERBOSITY=1`. Behavior identical to Plan 01-03 baseline — job killed within ~5s, FAIL+timeout persisted, AND heartbeat lines visible on console. The verbose path is unchanged.+ - Behavior smoke (default-disabled): same script with `PARALLEL_JOB_TIMEOUT_SECONDS=0` (the shipped default) and any verbosity. Job MUST run to natural completion (no kill) regardless of verbosity — backwards compatibility holds.+ - bats baseline: `bats tests/unit/` reports 246/246 PASS.+ </acceptance_criteria>+ <done>+ Both heartbeat loops at `lib/parallel.sh:467-506` (batch-flush) and `:577-616` (final-wait) now have the decoupled gate — hoisted `_to`/`_verbose_progress`/`_loop_active` locals, loop entry on `_loop_active && (_verbose_progress || _to > 0)`, unconditional timeout-enforcement inside the loop body, verbosity-gated `_parallel_snapshot`. CR-02 explanatory comment and WR-05 documentation note present. Two-loop symmetry preserved. Behavior smokes confirm timeout fires under `--quiet` and heartbeats stay verbosity-gated. `bash -n` and `shellcheck` clean; 246/246 bats pass.+ </done>+</task>++<task type="auto">+ <name>Task 2: Add `_kill_tree` helper and refactor `_timeout_kill_job` to walk the process tree</name>+ <files>lib/parallel.sh</files>+ <read_first>+ - lib/parallel.sh (full body of `_timeout_kill_job` at :53-77 — note the current `kill -TERM "$pid"` / poll-loop / `kill -KILL "$pid"` sequence that this task replaces; also note the `_throttle_jobs` helper at :33-42 for sibling-style positioning of the new `_kill_tree`)+ - .planning/phases/01-resilient-resume-timeout-safety/01-VERIFICATION.md (CR-03 missing item: "Use a process-group kill (`kill -TERM -- -<pgid>`) or a recursive child kill (`pgrep -P` walk) so the actual tool process and any axiom-distributed children are signaled, not just the wrapper.")+ - .planning/phases/01-resilient-resume-timeout-safety/01-REVIEW.md (CR-03 — exact `_kill_tree` recursive walk recommendation: "_kill_tree() { local parent=$1 sig=$2; local child; for child in $(pgrep -P $parent 2>/dev/null); do _kill_tree $child $sig; done; kill -$sig $parent 2>/dev/null || true; }")+ - .planning/codebase/CONVENTIONS.md (Function Naming: `function name() {` form for new code; Underscore-prefix-private helpers)+ - CLAUDE.md (Constraints: macOS Homebrew Bash 4+; pgrep available on both Linux procps and BSD/macOS; setsid is Linux-only and NOT used here)+ - modules/modes.sh :16 (`set +m 2>/dev/null || true` — job control deliberately disabled; this is why the pgid approach was rejected in favor of the `pgrep -P` walk)+ </read_first>+ <action>+ Step A — Add the new `_kill_tree` helper to `lib/parallel.sh`. Insert it IMMEDIATELY AFTER the existing `_throttle_jobs` function (which closes at `:42`) and IMMEDIATELY BEFORE the existing comment block above `_timeout_kill_job` (which currently starts at `:44`). Declare using canonical `function _kill_tree() {` form per CONVENTIONS.md.++ The exact insertion:++ ```+ # Recursively signal a process and all its descendants. Used by+ # _timeout_kill_job to kill the actual external tool (puredns, dnsx, ffuf,+ # axiom-scan, etc.) inside the parallel_funcs wrapper subshell, not just+ # the wrapper itself (CR-03 fix). Walks the process tree via `pgrep -P`+ # which is available on both Linux (procps) and macOS (BSD pgrep). If+ # pgrep is missing on the host, the walk degrades gracefully to a+ # wrapper-only kill (matches pre-patch behavior) so the run does not fail.+ # Process-group kill via `kill -- -<pgid>` was rejected because start() at+ # modules/modes.sh:16 explicitly disables job control (`set +m`), so the+ # wrapper subshell does not get its own pgid; flipping `set -m` for one+ # corner case is intrusive across the codebase.+ function _kill_tree() {+ local parent="$1" sig="${2:-TERM}"+ local child+ # Recurse into children first so deeper leaves get signaled before the+ # parent — protects against a parent re-spawning children on signal.+ if command -v pgrep >/dev/null 2>&1; then+ for child in $(pgrep -P "$parent" 2>/dev/null); do+ _kill_tree "$child" "$sig"+ done+ fi+ kill "-$sig" "$parent" 2>/dev/null || true+ }+ ```++ Notes on the recursion order: children-first-then-parent is the standard Unix idiom for tree kills — signaling the parent last gives any deeper descendants a chance to be cleaned up first, and a SIGTERM-then-SIGKILL pattern in the caller (`_timeout_kill_job`) handles the parent's own tool process. The `command -v pgrep` guard ensures graceful degradation if the host happens to lack `pgrep` (extremely rare; CLAUDE.md targets reconftw-supported environments where `pgrep` is universally available, but defense in depth is cheap).++ Step B — Refactor `_timeout_kill_job` at `lib/parallel.sh:53-77`. The current body's kill sequence:++ ```+ # D-13: TERM first, then KILL after grace seconds for tools that ignore TERM.+ kill -TERM "$pid" 2>/dev/null || true+ local i+ for ((i=0; i<grace; i++)); do+ kill -0 "$pid" 2>/dev/null || break+ sleep 1+ done+ kill -KILL "$pid" 2>/dev/null || true+ ```++ Replace with:++ ```+ # D-13: TERM first, then KILL after grace seconds for tools that ignore TERM.+ # CR-03 fix: kill the entire process tree under the wrapper PID so the actual+ # external tool (puredns, dnsx, ffuf, axiom-scan, etc.) terminates — not just+ # the wrapper subshell. Pre-patch behavior signaled only $pid (the wrapper),+ # leaving the tool orphaned to PID 1 and continuing past the timeout.+ _kill_tree "$pid" TERM+ local i+ for ((i=0; i<grace; i++)); do+ kill -0 "$pid" 2>/dev/null || break+ sleep 1+ done+ _kill_tree "$pid" KILL+ ```++ Key changes:+ 1. `kill -TERM "$pid"` becomes `_kill_tree "$pid" TERM` — signals the wrapper AND all descendants.+ 2. `kill -KILL "$pid"` becomes `_kill_tree "$pid" KILL` — same.+ 3. The poll loop using `kill -0 "$pid"` is UNCHANGED — it still checks the wrapper PID specifically (not the descendants), which is the correct gate: once the wrapper exits, the parallel_funcs `wait` returns and the parallel batch progresses. The descendants are killed inside the tree walk; their reaping is the kernel's job.+ 4. The persistence writes (`.status_<fn>=FAIL`, `.status_reason_<fn>=timeout`) and the `log_json` call are UNCHANGED. Only the kill mechanism is replaced.++ DO NOT modify the function signature (`_timeout_kill_job <pid> <func_name> <duration_sec>`). DO NOT modify the `local pid="$1" func_name="$2" duration_sec="$3"` line. DO NOT modify the `local grace="${PARALLEL_KILL_GRACE_SECONDS:-10}"` line or its integer guard. DO NOT add new helper parameters — `_kill_tree` is a fixed-arity helper that operates on `pid + sig`; the caller wraps it.++ Step C — Verify the helper integrates cleanly. After both edits land, the file should parse with `bash -n`, pass `shellcheck`, and the existing call sites of `_timeout_kill_job` (two of them, inside the two heartbeat loops modified in Task 1) should remain UNCHANGED. The change is hidden behind the helper boundary — callers see the same signature.++ Behavior risk: `pgrep -P` returns children at the time of the call. If new children are spawned between the call and the actual kill, those new descendants will not be signaled. For reconftw's use case (kill a tool that has stalled), this is acceptable — a stalled tool is not spawning children. If concurrent spawning becomes an issue in future, the tree walk can be repeated inside the grace loop; for v1 the one-shot walk is sufficient.++ macOS sanity check: `pgrep -P <pid>` is POSIX-portable. macOS (BSD) supports `pgrep` from at least 10.8 onwards; reconftw's macOS target via Homebrew Bash is well within that range.+ </action>+ <verify>+ <automated>bash -n /Users/six2dez/Tools/reconftw/lib/parallel.sh && shellcheck -s bash --severity=error /Users/six2dez/Tools/reconftw/lib/parallel.sh</automated>+ </verify>+ <acceptance_criteria>+ - `_kill_tree` helper declared with canonical form: `grep -cE '^function _kill_tree\(\) \{' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 1.+ - The recursive walk via `pgrep -P` is present inside `_kill_tree`: `awk '/^function _kill_tree\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c 'pgrep -P "\$parent"'` returns >=1.+ - The graceful-degradation `command -v pgrep` guard is present: `awk '/^function _kill_tree\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c 'command -v pgrep'` returns >=1.+ - The parent `kill` is called LAST (children-first-then-parent ordering): `awk '/^function _kill_tree\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | awk '/pgrep -P "\$parent"/{p=NR} /kill "-\$sig" "\$parent"/{c=NR} END{print (p && c && p<c) ? "ORDER_OK" : "ORDER_FAIL"}'` returns `ORDER_OK`.+ - The function is positioned between `_throttle_jobs` and `_timeout_kill_job`: `awk '/^_throttle_jobs\(\) \{|^function _throttle_jobs\(\) \{/{t=NR} /^function _kill_tree\(\) \{/{k=NR} /^function _timeout_kill_job\(\) \{/{tk=NR} END{print (t && k && tk && t<k && k<tk) ? "POS_OK" : "POS_FAIL"}'` returns `POS_OK`.+ - `_timeout_kill_job` now calls `_kill_tree` (not bare `kill`): inside the function body, the TERM and KILL calls go via `_kill_tree`. `awk '/^function _timeout_kill_job\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c '_kill_tree "\$pid" TERM'` returns exactly 1; `awk '/^function _timeout_kill_job\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c '_kill_tree "\$pid" KILL'` returns exactly 1.+ - The bare `kill -TERM "$pid"` and `kill -KILL "$pid"` lines are REMOVED from `_timeout_kill_job`: `awk '/^function _timeout_kill_job\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -cE '^[[:space:]]+kill -TERM "\$pid"|^[[:space:]]+kill -KILL "\$pid"'` returns 0.+ - The `kill -0 "$pid"` poll inside the grace loop is UNCHANGED (operates on the wrapper PID, not the tree): `awk '/^function _timeout_kill_job\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c 'kill -0 "\$pid" 2>/dev/null || break'` returns exactly 1.+ - The persistence writes are UNCHANGED: `awk '/^function _timeout_kill_job\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c 'printf "FAIL\\\\n" >"\${called_fn_dir}/\.status_\${func_name}"'` returns >=1 (the existing FAIL persistence) and `grep -c 'printf "timeout\\\\n" >"\${called_fn_dir}/\.status_reason_\${func_name}"'` returns >=1. (Note: double-escaping in `grep` can be finicky; `grep -F` fixed-string mode is acceptable for verification — the existing `01-03-SUMMARY.md` notes this exact issue.)+ - The `log_json` call is UNCHANGED: `awk '/^function _timeout_kill_job\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c 'log_json "ERROR" "\${func_name}" "Job timed out" "reason=timeout"'` returns >=1.+ - The CR-03 explanatory comment is present inside `_timeout_kill_job`: `awk '/^function _timeout_kill_job\(\) \{/,/^}/' /Users/six2dez/Tools/reconftw/lib/parallel.sh | grep -c 'CR-03 fix'` returns >=1.+ - The `_kill_tree` helper's docstring mentions the rejected pgid approach: `awk '/^function _kill_tree\(\) \{/{f=1} f && /^}/{exit} 1' /Users/six2dez/Tools/reconftw/lib/parallel.sh | head -20 | grep -cE 'set \+m|Process-group kill.*rejected|pgid'` returns >=1 (one or more references to why the pgid approach was not used).+ - Call sites of `_timeout_kill_job` are UNCHANGED (still 2 occurrences, one per heartbeat loop): `grep -c '_timeout_kill_job "\${batch_pids\[\$idx\]}" "\${batch_funcs\[\$idx\]}" "\$job_dur"' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 2.+ - `bash -n lib/parallel.sh` exits 0.+ - `shellcheck -s bash --severity=error lib/parallel.sh` exits 0 (no NEW error-level findings).+ - Behavior smoke (CR-03 reproduction — inner tool dies): write `/tmp/inner_kill.sh` that (1) sources `./reconftw.sh --source-only`, (2) defines `function my_slow_func() { sleep 30 & local inner=$!; echo $inner > /tmp/inner.pid; wait; }`, (3) sets `called_fn_dir=$(mktemp -d) PARALLEL_JOB_TIMEOUT_SECONDS=2 PARALLEL_KILL_GRACE_SECONDS=1 PARALLEL_HEARTBEAT_SECONDS=1 PARALLEL_MODE=true OUTPUT_VERBOSITY=1`, (4) runs `parallel_funcs 1 my_slow_func`. After ~5s the wrapper PID is dead AND `kill -0 $(cat /tmp/inner.pid) 2>/dev/null` returns non-zero (inner process also dead). With the pre-patch code the inner `sleep 30` would survive as an orphan; post-patch it's reaped within the grace window. Confirm with `ps -p $(cat /tmp/inner.pid) -o stat= 2>/dev/null` returning empty.+ - Behavior smoke (multi-level tree — exercises the recursion): same script but `function my_slow_func() { ( sleep 30 ) & local inner=$!; echo $inner > /tmp/inner.pid; wait; }` (note the extra subshell wrapping the sleep). After timeout, both the inner subshell PID AND its `sleep 30` child must be dead. The recursive `_kill_tree` walks two levels deep.+ - Behavior smoke (pgrep-missing graceful degradation): in a controlled env, temporarily mask `pgrep` (e.g., `function pgrep() { return 1; }`) and run the smoke. The `_kill_tree` falls back to wrapper-only kill (matches pre-patch behavior); the wrapper dies but the inner `sleep 30` may survive. This is acceptable degradation — log the pre-patch wallclock difference to confirm the fallback path was exercised. (This smoke is informational; the acceptance criterion is that the run does not error out — `bash -c './lib/parallel.sh ...'` exits 0.)+ - bats baseline: `bats tests/unit/` reports 246/246 PASS.+ </acceptance_criteria>+ <done>+ `_kill_tree` helper added between `_throttle_jobs` and `_timeout_kill_job` with `function _kill_tree() {` canonical form, `pgrep -P` recursive walk, children-first-then-parent ordering, and `command -v pgrep` graceful-degradation guard. `_timeout_kill_job` body now calls `_kill_tree $pid TERM` and `_kill_tree $pid KILL` instead of the bare `kill` against the wrapper PID. The persistence writes, `log_json` call, and `kill -0` poll are UNCHANGED. Call sites of `_timeout_kill_job` are UNCHANGED (still 2). CR-03 smoke reproduction (inner `sleep 30` dies along with the wrapper) passes. `bash -n` and `shellcheck` clean; 246/246 bats pass.+ </done>+</task>++</tasks>++<verification>+- `bash -n lib/parallel.sh` → exit 0.+- `shellcheck -s bash --severity=error lib/parallel.sh` → exit 0 (no NEW error-level findings vs baseline).+- `bats tests/unit/` → 246/246 PASS (no new tests in this phase per CONTEXT.md §Claude's Discretion).+- `bats tests/security/` → no regressions.+- Behavioral smokes (composed Task 1 + Task 2):+ 1. **CR-02 reproduction (timeout fires under --quiet)**: set `PARALLEL_JOB_TIMEOUT_SECONDS=2 OUTPUT_VERBOSITY=0`, run `parallel_funcs 1 my_slow_func` where the function sleeps 30. Within ~5s the job is killed, `.status_my_slow_func=FAIL`, `.status_reason_my_slow_func=timeout`. Pre-patch the same setup runs the full 30s without killing it.+ 2. **CR-03 reproduction (inner tool dies)**: same setup but with verbosity 1 and a slow function that backgrounds an inner `sleep 30` and captures its PID. After ~5s both the wrapper AND the inner PID are dead. Pre-patch only the wrapper dies; the inner sleep orphans to PID 1.+ 3. **Heartbeat-UI still verbosity-gated (regression check)**: with `PARALLEL_JOB_TIMEOUT_SECONDS=0 OUTPUT_VERBOSITY=0`, the loop runs only when needed (or not at all); no heartbeat snapshots on the console. With `OUTPUT_VERBOSITY=1` the heartbeats appear as before. Proves the gate is decoupled, not removed.+ 4. **Default-disabled backwards compat**: `PARALLEL_JOB_TIMEOUT_SECONDS=0` (the shipped default), any verbosity — `normal_func` runs to natural completion, no kill, no FAIL, no orphans.+ 5. **Two-loop symmetry**: a 3-function batch with `PARALLEL_MAX_JOBS=2` where only the 3rd function is slow exercises the final-wait loop's timeout path. The 3rd function gets killed by the final-wait loop's modified gate.+- Pattern-level checks:+ 6. `grep -c 'local _to="\${PARALLEL_JOB_TIMEOUT_SECONDS:-0}"' lib/parallel.sh` returns 2 (both heartbeat loops hoist `_to` to the outer scope).+ 7. `grep -c 'CR-02 fix' lib/parallel.sh` returns >=2; `grep -c 'CR-03 fix' lib/parallel.sh` returns >=1.+ 8. `_kill_tree` is positioned between `_throttle_jobs` and `_timeout_kill_job`; uses `pgrep -P` recursive walk; signals children first then parent; falls back gracefully when `pgrep` is missing.+</verification>++<success_criteria>+- Gaps B and C from `01-VERIFICATION.md` are closed: SC3 transitions PARTIAL → VERIFIED. `PARALLEL_JOB_TIMEOUT_SECONDS` enforcement runs under `--quiet` (CR-02 fix), and the kill signals the entire process tree under the wrapper PID — not just the wrapper itself (CR-03 fix).+- Default `PARALLEL_JOB_TIMEOUT_SECONDS=0` is preserved (D-11 locked); the feature remains opt-in and backwards-compatible.+- Heartbeat-snapshot UI remains gated on `OUTPUT_VERBOSITY >= 1` — only the timeout-enforcement and kill mechanism are decoupled. Verbosity 0 still gets a quiet console exactly as the user requested.+- Two-loop symmetry preserved: the batch-flush and final-wait heartbeat loops have identical structure post-fix (verified by grep counts returning exactly 2 for each key pattern).+- macOS compatibility holds: `pgrep -P` is available on both Linux procps and BSD/macOS pgrep; `setsid` (Linux-only) is NOT used; the rejected pgid approach is documented inside the `_kill_tree` helper's docstring.+- No bats tests added (Phase 4 / TEST-01 owns parallel_funcs timeout-kill coverage); the 246/246 baseline holds.+- Call sites of `_timeout_kill_job` remain UNCHANGED — only the helper's internal kill mechanism is replaced. The change is transparent to the surrounding `parallel_funcs` logic.+</success_criteria>++<output>+After completion, create `.planning/phases/01-resilient-resume-timeout-safety/01-05-SUMMARY.md`.++The SUMMARY should explicitly note:+- Gaps B and C (CR-02 + CR-03) closed; SC3 verifier status transitions PARTIAL → VERIFIED on next verifier run+- `_kill_tree` helper pattern established for future supervised-process kills (Phase 5 documentation candidate, alongside the DOCS-01 followup from Plan 01-03)+- The pgid approach was considered and rejected — documented inside `_kill_tree`'s docstring AND in this SUMMARY's Decisions Made section. The reason: `modules/modes.sh:16` deliberately disables job control via `set +m`. Resurrecting it for this one corner case is intrusive.+- The behavioral smokes `/tmp/quiet_timeout.sh` and `/tmp/inner_kill.sh` (or local equivalents) reproduce the CR-02 and CR-03 fix behaviors; these are the next verifier's checks+- WR-05 from 01-REVIEW.md (the `PARALLEL_HEARTBEAT_SECONDS=0` corner case that disables timeout enforcement) is acknowledged via inline comment but NOT resolved here — it's a Phase 5 DOCS-01 candidate per the original advisory+- No bats tests added; Phase 4 / TEST-01 owns coverage+</output>+</content>