Skip to content

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

docs(01): create phase plan

six2dezed7e020ec37e
diff --git a/.planning/STATE.md b/.planning/STATE.md
index 4ddaa57..2124b60 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -2,14 +2,14 @@
gsd_state_version: 1.0
milestone: v1.0
milestone_name: milestone
-status: planning
+status: executing
stopped_at: Phase 1 context gathered
-last_updated: "2026-05-13T08:20:48.073Z"
-last_activity: 2026-05-13 — Roadmap created from CONCERNS.md audit findings
+last_updated: "2026-05-13T08:57:40.389Z"
+last_activity: 2026-05-13 -- Phase 01 planning complete
progress:
total_phases: 5
completed_phases: 0
- total_plans: 0
+ total_plans: 3
completed_plans: 0
percent: 0
---
@@ -27,8 +27,8 @@ See: .planning/PROJECT.md (updated 2026-05-13)
Phase: 1 of 5 (Resilient Resume & Timeout Safety)
Plan: 0 of 3 in current phase
-Status: Ready to plan
-Last activity: 2026-05-13 — Roadmap created from CONCERNS.md audit findings
+Status: Ready to execute
+Last activity: 2026-05-13 -- Phase 01 planning complete
Progress: [░░░░░░░░░░] 0%
diff --git a/.planning/phases/01-resilient-resume-timeout-safety/01-01-PLAN.md b/.planning/phases/01-resilient-resume-timeout-safety/01-01-PLAN.md
new file mode 100644
index 0000000..936fad8
--- /dev/null
+++ b/.planning/phases/01-resilient-resume-timeout-safety/01-01-PLAN.md
@@ -0,0 +1,222 @@
+---
+id: 01-01
+phase: 01
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+requirements: [RESIL-01]
+files_modified:
+ - modules/core.sh
+ - modules/modes.sh
+ - modules/utils.sh
+autonomous: true
+must_haves:
+ truths:
+ - "D-01: Sentinel file is a plain empty `${called_fn_dir}/.inprogress_<fn>` — when start_func runs for function FN, .inprogress_<FN> exists in called_fn_dir; no PID, no timestamp, no JSON metadata inside"
+ - "D-01: When end_func completes for FN, .inprogress_<FN> is removed BEFORE the existing .<FN> success checkpoint touch — preserves crash-safety ordering"
+ - "D-02: Staleness detection uses trap-on-exit cleanup — when the shell exits (normal, INT, TERM, EXIT), the registered traps clear all .inprogress_* files in called_fn_dir; graceful exits leave NO .inprogress_* files"
+ - "D-03: No PID liveness checks or staleness windows — the single-operator-per-target constraint (PROJECT.md) makes any leftover .inprogress_* a guaranteed crash-leftover from a prior run, so the trap-only design is sufficient"
+ - "D-04: When a prior run was killed and the next start() invocation sees one or more .inprogress_<FN> files, exactly ONE WARN summary line names the affected functions (`WARN resume: N functions re-running after interruption (fn_a, fn_b)`) and a JSONL event records reason=inprogress_leftover; no per-function RESUME badges"
+ - "D-05: When FORCE_RESCAN=true (PRESERVE=false), the orphan-cleanup loop removes any .inprogress_* alongside the existing .<FN> wipe so the resume banner does NOT fire"
+ - "D-06: Function re-execution on leftover is transparent — the existing checkpoint guard ([[ ! -f $called_fn_dir/.<FN> ]]) sees no .<FN> (end_func never reached on a crash) and re-enters; the .inprogress_* file does NOT drive control flow"
+ - "D-02: On graceful (non-signal) exit, the new EXIT-only trap clears .inprogress_* sentinels WITHOUT printing an interruption banner and WITHOUT forcing exit 130 — cleanup_on_exit is unchanged and stays bound to INT/TERM only"
+ artifacts:
+ - path: "modules/core.sh"
+ provides: "start_func touches .inprogress_<fn>; end_func removes .inprogress_<fn> before touching .<fn>"
+ - path: "modules/modes.sh"
+ provides: "separate EXIT-only trap calling _cleanup_inprogress + orphan-cleanup line in FORCE_RESCAN block + resume banner emission in start()"
+ - path: "modules/utils.sh"
+ provides: "_cleanup_inprogress standalone helper (NOT inside cleanup_on_exit); cleanup_on_exit untouched"
+ key_links:
+ - from: "modules/core.sh:start_func"
+ to: "$called_fn_dir/.inprogress_<fn>"
+ via: "touch with called_fn_dir guard"
+ pattern: "touch \"\\$called_fn_dir/\\.inprogress_"
+ - from: "modules/core.sh:end_func"
+ to: "$called_fn_dir/.inprogress_<fn>"
+ via: "rm -f BEFORE existing touch .<fn>"
+ pattern: "rm -f \"\\$called_fn_dir/\\.inprogress_"
+ - from: "modules/modes.sh:start()"
+ to: "_cleanup_inprogress (via separate EXIT-only trap)"
+ via: "trap '_cleanup_inprogress' EXIT installed immediately after the existing INT/TERM trap"
+ pattern: "trap '_cleanup_inprogress' EXIT"
+---
+
+<objective>
+Add `.inprogress_<fn>` sentinel lifecycle so interrupted runs surface a clear resume indicator and only re-execute the function that was killed mid-run. Closes RESIL-01.
+
+Purpose: Today, `end_func` writes `.<fn>` only on clean completion (`modules/core.sh:1465`). An interrupted function (Ctrl-C, OOM, crash) leaves NO marker, so a `PRESERVE=true` re-run cannot distinguish "function never ran" from "function crashed mid-run". This plan adds a touch-on-start / remove-on-end sentinel plus trap-based cleanup so leftover sentinels on the next invocation become the resume signal.
+
+Output: `start_func`/`end_func` write and clear `.inprogress_<fn>`; `start()` in `modules/modes.sh` installs a separate `EXIT`-only trap that calls a new lightweight `_cleanup_inprogress` helper (it clears stale sentinels on graceful exit without any banner, kill, or forced exit code). The existing `cleanup_on_exit` (modules/utils.sh:116-146) stays bound to `INT/TERM` only and is NOT modified. `FORCE_RESCAN=true` adds an explicit `.inprogress_*` orphan clear and start() emits a one-line resume WARN banner when leftover sentinels are detected from a prior crash.
+</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]/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md
[email protected]/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md
[email protected]/codebase/CONVENTIONS.md
[email protected]/codebase/ARCHITECTURE.md
+
+<interfaces>
+<!-- Key existing identifiers the executor will modify or call. Extracted from codebase. -->
+
+From modules/core.sh:
+- function start_func() — lifecycle entry, `:1419-1435`. Body: writes LOGFILE start line, sets `_start_time_<fn>` per-function timestamp, calls `log_json "INFO" "${1}" "Function started" "description=${2}"`.
+- function end_func() — lifecycle exit, `:1437-1531`. Body order today: case-normalize status (`:1442-1463`) → `touch "$called_fn_dir/.${fn}"` (`:1465`) → timing → badge mapping (`:1478-1502`) → `printf "%s\n" "$badge" >"${called_fn_dir}/.status_${fn}"` (`:1505-1509`) → `_print_status` (`:1512`) → `log_json "SUCCESS"` (`:1525`).
+- function log_json() — `:680`. Signature: `log_json "<LEVEL>" "<function_name>" "<human_message>" "key=value" "key2=value2"`. No-op when STRUCTURED_LOGGING != true.
+
+From modules/modes.sh:
+- function start() — `:13-163`. Existing INT/TERM trap at `:118`: `trap 'cleanup_on_exit' INT TERM`. Existing FORCE_RESCAN wipe at `:78-80`: `if [[ "${FORCE_RESCAN:-false}" == "true" ]]; then rm -f "$called_fn_dir"/.* 2>>"${LOGFILE:-/dev/null}" || true; fi`. Existing rescan banner at `:154-156`: `if [[ "${FORCE_RESCAN:-false}" == "true" ]]; then _print_msg WARN "Force rescan enabled: ignoring cached module markers"; fi`. Existing tools_installed call at `:160`.
+
+From modules/utils.sh:
+- function cleanup_on_exit() — `:116-146`. UNCHANGED in this plan. Currently registered for INT/TERM only. Body unconditionally prints "Interrupted. Cleaning up..." in red, kills tracked PIDs (`jobs -p`, `INTERACTSH_PID`), and calls `exit "$exit_code"` where exit_code defaults to 130. Firing it on EXIT would break every successful scan (red banner + forced exit 130). This plan therefore registers a SEPARATE EXIT-only trap pointing at a new lightweight `_cleanup_inprogress` helper, and DOES NOT modify cleanup_on_exit.
+
+From lib/common.sh:
+- _print_msg() — `:342`. Usage: `_print_msg WARN "message"`.
+- _print_error() — `:528`. Always-visible stderr error.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+ <name>Task 1: Sentinel touch in start_func + sentinel remove in end_func</name>
+ <files>modules/core.sh</files>
+ <read_first>
+ - modules/core.sh (current start_func body :1419-1435 and end_func body :1437-1531 — see the touch at :1465 and status persistence pattern at :1505-1509)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md (anchor "Existing `start_func` body (lines 1419-1435)" and "Existing `end_func` body (lines 1465-1510)")
+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (D-01: "plain empty `${called_fn_dir}/.inprogress_<fn>`. `start_func` `touch`es it; `end_func` removes it before `touch`ing the existing `.<fn>`. No JSON metadata, no PID, no timestamp inside.")
+ - .planning/codebase/CONVENTIONS.md (Function Lifecycle and File Checkpointing sections)
+ </read_first>
+ <action>
+ In modules/core.sh: extend start_func (line 1419) to touch `$called_fn_dir/.inprogress_${1}` immediately AFTER the `printf -v "_start_time_..."` line at :1425 and BEFORE the `log_json` call at :1428. Guard with `if [[ -n "${called_fn_dir:-}" ]]; then ... fi` mirroring the guard pattern at :1505. Use `touch "$called_fn_dir/.inprogress_${1}" 2>/dev/null || true` — the `2>/dev/null || true` pattern matches :1506/:1508 fire-and-forget idiom. Use raw `${1}` (function name) for the filename, NOT the sanitized `_fn_name` variant; the function name is already a valid bash identifier (FUNCNAME values are bash-token-safe). Per D-01 the file is plain empty — DO NOT write PID, timestamp, JSON, or any payload.
+
+ In end_func (line 1437): insert `if [[ -n "${called_fn_dir:-}" ]]; then rm -f "$called_fn_dir/.inprogress_${fn}" 2>/dev/null || true; fi` IMMEDIATELY BEFORE the existing `touch "$called_fn_dir/.${fn}"` at :1465. The ordering rationale (per D-06 / PATTERNS.md): a crash between the rm and the touch still leaves `.<fn>` absent, so the existing checkpoint guard re-runs the function on next invocation. The sentinel is purely a surface-level indicator; `.<fn>` is the source of truth.
+
+ DO NOT introduce a new badge or modify the status/reason files. DO NOT alter the `record_func_timing`, `_print_status`, or `log_json "SUCCESS"` calls. DO NOT add PID-in-sentinel or timestamp-in-sentinel (per D-03 simplicity decision is locked).
+
+ Preserve `function name() { ... }` declaration style (CONVENTIONS.md). Preserve all existing trailing logic (timing, badges, JSONL log).
+ </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>
+ - `grep -n 'touch "\$called_fn_dir/\.inprogress_' /Users/six2dez/Tools/reconftw/modules/core.sh` returns exactly one match inside start_func (line range 1419-1435 in the original file; line numbers will shift after edit, but the match must be within the start_func body — i.e., between `function start_func()` and the closing `}`).
+ - `grep -n 'rm -f "\$called_fn_dir/\.inprogress_' /Users/six2dez/Tools/reconftw/modules/core.sh` returns exactly one match inside end_func, on a line BEFORE the `touch "$called_fn_dir/.${fn}"` line.
+ - Existing `touch "$called_fn_dir/.${fn}"` line still present and unchanged in payload.
+ - Existing `printf -v "_start_time_${_fn_name//[^a-zA-Z0-9_]/_}"` line still present and unchanged.
+ - `bash -n modules/core.sh` exits 0.
+ - `shellcheck -s bash --severity=error modules/core.sh` exits 0 (no new error-level findings introduced; pre-existing warnings allowed).
+ - Behavior (manual smoke after task 2 lands): running `./reconftw.sh --source-only` does not error; sourcing the file and calling `called_fn_dir=$(mktemp -d); start_func test_fn "desc"; ls "$called_fn_dir/.inprogress_test_fn"` shows the sentinel exists; `end_func "done" test_fn; [[ ! -e "$called_fn_dir/.inprogress_test_fn" ]] && [[ -e "$called_fn_dir/.test_fn" ]]` confirms removal then checkpoint.
+ </acceptance_criteria>
+ <done>
+ start_func writes `.inprogress_<fn>` after timestamp setup; end_func removes it immediately before the existing `.<fn>` touch; no other behavior modified; shellcheck clean.
+ </done>
+</task>
+
+<task type="auto">
+ <name>Task 2: Separate EXIT-only trap + orphan cleanup + resume banner in start()</name>
+ <files>modules/modes.sh, modules/utils.sh</files>
+ <read_first>
+ - modules/modes.sh (current start() body :13-163 — note INT/TERM trap at :118, FORCE_RESCAN wipe at :78-80, ERR trap at :140, FORCE_RESCAN banner at :154-156, tools_installed call at :160)
+ - modules/utils.sh (current cleanup_on_exit at :116-146 — DO NOT modify; note that it unconditionally prints an interruption banner and exits with code 130. New _cleanup_inprogress is a sibling helper, placed adjacent but kept independent.)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md (anchor "modules/modes.sh — start() orchestration entry" — D-02/D-04/D-05 insertion notes)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (D-02 trap-on-exit cleanup; D-04 single WARN banner; D-05 FORCE_RESCAN orphan clear)
+ - lib/common.sh (review _print_msg signature at :342 and _print_error at :528)
+ </read_first>
+ <action>
+ Step A — Add `_cleanup_inprogress` standalone helper to modules/utils.sh as a sibling to `cleanup_on_exit` (insert immediately AFTER cleanup_on_exit closes at :146, before `rotate_logs` at :148). It MUST NOT be invoked from inside cleanup_on_exit and MUST NOT call exit, kill, or print any banner — its only job is to remove the `.inprogress_*` sentinel files. Define:
+ - `function _cleanup_inprogress() { [[ -n "${called_fn_dir:-}" ]] && rm -f "${called_fn_dir}"/.inprogress_* 2>/dev/null; return 0; }` on its own line range.
+ - Place a single-line doc comment above it: `# 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.`
+ - Behavioral contract: the helper is idempotent, side-effect-only on `${called_fn_dir}` sentinel files, and explicitly `return 0` so it never propagates a non-zero exit through the EXIT trap chain.
+
+ Step B — Register a separate EXIT-only trap in modules/modes.sh start(). DO NOT modify the existing `trap 'cleanup_on_exit' INT TERM` line at :118 (cleanup_on_exit remains bound to INT/TERM only — firing it on EXIT would print "Interrupted. Cleaning up..." and force exit 130 on every successful scan, breaking CI, `--health-check`, axiom-orchestrator, `make test`, etc.). Instead, add the EXIT trap on the line IMMEDIATELY AFTER :118:
+ - Existing line at :118: `trap 'cleanup_on_exit' INT TERM` (unchanged).
+ - New line inserted right after :118: `trap '_cleanup_inprogress' EXIT`
+ - Result: INT/TERM still trigger the loud, exit-130 cleanup_on_exit (correct for actual interruptions). EXIT triggers the lightweight, silent _cleanup_inprogress on every shell termination including normal success (no banner, no kill, no forced exit code — natural `$?` is preserved).
+ - DO NOT edit cleanup_on_exit (modules/utils.sh:116-146). DO NOT chain `_cleanup_inprogress` into cleanup_on_exit; the two helpers are intentionally separate so that INT/TERM paths emit the existing user-visible interruption banner exactly once while EXIT paths stay silent.
+
+ Step C — Add FORCE_RESCAN orphan-clear line in modules/modes.sh. The new line goes inside the existing FORCE_RESCAN block at modes.sh:78-80, immediately after the existing `rm -f "$called_fn_dir"/.*` line (the existing line at :79). Insertion produces:
+ ```
+ if [[ "${FORCE_RESCAN:-false}" == "true" ]]; then # :78 (unchanged)
+ rm -f "$called_fn_dir"/.* 2>>"${LOGFILE:-/dev/null}" || true # :79 (unchanged)
+ rm -f "$called_fn_dir"/.inprogress_* 2>>"${LOGFILE:-/dev/null}" || true # NEW
+ fi # :80 (unchanged)
+ ```
+ The block already executes before the trap installs at :118 in natural top-down flow — no reordering needed. Per D-05 / PATTERNS.md: although the existing `rm -f "$called_fn_dir"/.*` SHOULD match `.inprogress_*` via dotglob, we add an explicit second `rm -f` line for defensive clarity so a `--force` run never inherits a fake resume condition regardless of shell glob settings.
+
+ Step D — Emit resume banner in modules/modes.sh. Insert a new block AFTER the existing FORCE_RESCAN warning at :154-156 (`if [[ "${FORCE_RESCAN:-false}" == "true" ]]; then _print_msg WARN "Force rescan enabled..."; fi`) and BEFORE the `if [[ "${MONITOR_MODE:-false}" == "true" ]]` block at :157. Defensive guards are mandatory: the block MUST be wrapped so it does NOT enumerate sentinels when `called_fn_dir` is empty (which would scan filesystem root) and MUST be skipped under FORCE_RESCAN (Step C already wiped any orphans). The block must:
+ 1. Outer guard: wrap the entire detection in `if [[ -n "${called_fn_dir:-}" ]] && [[ "${FORCE_RESCAN:-false}" != "true" ]]; then ... fi`. The `[[ -n "${called_fn_dir:-}" ]]` check is mandatory — without it, an unset called_fn_dir would cause `ls -1 /.inprogress_*` to scan filesystem root.
+ 2. Inside the guard: `local -a _leftover; mapfile -t _leftover < <(ls -1 "${called_fn_dir}"/.inprogress_* 2>/dev/null)`. The `2>/dev/null` suppresses the no-match-glob error from `ls`.
+ 3. Test for non-empty results: `if (( ${#_leftover[@]} > 0 )); then ... fi`.
+ 4. Build a comma-separated function-name list by stripping the `${called_fn_dir}/.inprogress_` prefix from each path.
+ 5. Emit exactly ONE banner line via `_print_msg WARN "resume: ${#_leftover[@]} functions re-running after interruption (${joined})"` — matches the FORCE_RESCAN banner idiom at :155 and the locked D-04 phrasing ("WARN resume: N functions re-running after interruption (fn_a, fn_b)"). DO NOT add per-function badges, DO NOT call `notification`.
+ 6. Emit one JSONL event via `log_json "WARN" "resume" "Inprogress sentinels found" "reason=inprogress_leftover" "funcs=${joined}"` — matches the `log_json` shape from start_func at :1428.
+
+ DO NOT touch the ERR trap at :140 (composition with EXIT/INT/TERM only). DO NOT introduce a CLI flag for the resume banner (always-on at OUTPUT_VERBOSITY>=1 via WARN level). DO NOT modify cleanup_on_exit in modules/utils.sh (its INT/TERM behavior is intentional and load-bearing — the loud banner + exit 130 is the desired user-facing interruption signal).
+ </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 -nE '^function _cleanup_inprogress\(\) \{' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns exactly one match (standalone declaration in the canonical `function name() {` form).
+ - `grep -n 'rm -f "\${called_fn_dir}"/\.inprogress_\*' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns at least one match inside the _cleanup_inprogress body.
+ - `_cleanup_inprogress` is NOT called from inside `cleanup_on_exit`: `awk '/^function cleanup_on_exit/,/^}/' /Users/six2dez/Tools/reconftw/modules/utils.sh | grep -c '_cleanup_inprogress'` returns exactly 0.
+ - `cleanup_on_exit` is UNCHANGED apart from the surrounding file: the body still contains the interruption banner (`grep -c 'Interrupted. Cleaning up' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns >=1) and the `exit "$exit_code"` line (`grep -c 'exit "\$exit_code"' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns >=1).
+ - `grep -n "^[[:space:]]*trap 'cleanup_on_exit' INT TERM" /Users/six2dez/Tools/reconftw/modules/modes.sh` returns exactly 1 (existing trap UNCHANGED — EXIT must NOT appear on this line).
+ - `grep -n "^[[:space:]]*trap '_cleanup_inprogress' EXIT" /Users/six2dez/Tools/reconftw/modules/modes.sh` returns exactly 1 (NEW separate EXIT-only trap).
+ - The EXIT trap line sits immediately after the INT/TERM trap line: `awk '/^[[:space:]]*trap '\''cleanup_on_exit'\'' INT TERM/{getline nxt; print nxt; exit}' /Users/six2dez/Tools/reconftw/modules/modes.sh | grep -c "trap '_cleanup_inprogress' EXIT"` returns 1.
+ - FORCE_RESCAN orphan-clear line is between `rm -f "$called_fn_dir"/.*` and the closing `fi`: `awk '/if \[\[ "\${FORCE_RESCAN:-false}" == "true" \]\]; then/,/^[[:space:]]*fi/' /Users/six2dez/Tools/reconftw/modules/modes.sh | head -10 | grep -nE 'rm -f "\$called_fn_dir"/\.\*|rm -f "\$called_fn_dir"/\.inprogress_\*|^[[:space:]]*fi'` shows the two `rm -f` lines in order followed by `fi`.
+ - The new FORCE_RESCAN `rm -f .inprogress_*` line precedes the trap install at :118: `awk '/rm -f "\$called_fn_dir"\/\.inprogress_\*/{print NR; exit}' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns a line number < the line containing `trap '_cleanup_inprogress' EXIT`.
+ - Banner detection block is guarded against unset called_fn_dir: `grep -nE '\[\[ -n "\$\{called_fn_dir:-\}" \]\]' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns >=1 (specifically wrapping the leftover-detection mapfile/glob).
+ - Banner detection block is skipped under FORCE_RESCAN: the same guard line also tests `[[ "${FORCE_RESCAN:-false}" != "true" ]]`. `grep -nE '\[\[ "\$\{FORCE_RESCAN:-false\}" != "true" \]\]' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns >=1.
+ - `grep -n '_print_msg WARN "resume: ' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns exactly one match.
+ - `grep -n 'reason=inprogress_leftover' /Users/six2dez/Tools/reconftw/modules/modes.sh` returns exactly one match (the log_json call).
+ - `bash -n modules/modes.sh` and `bash -n modules/utils.sh` both exit 0.
+ - `shellcheck -s bash --severity=error modules/modes.sh modules/utils.sh` exits 0 (no new error-level findings).
+ - Behavior smoke (graceful-exit safety — protects against the BLOCKER regression): inside a `--source-only`-loaded shell, run `called_fn_dir=$(mktemp -d); start_func test_fn "desc"; end_func "done" test_fn; exit 0` (a clean round-trip + clean exit). The shell exit MUST NOT print "Interrupted. Cleaning up..." anywhere, and `$?` after the subshell MUST be 0 (the natural exit code) — NOT 130. The `${called_fn_dir}/.inprogress_*` directory listing MUST be empty.
+ - Behavior smoke (resume banner): simulating a crash via `mkdir -p /tmp/rftw-test/.called_fn && touch /tmp/rftw-test/.called_fn/.inprogress_sub_brute`, then a `--source-only` sourced `start` invocation pointing `called_fn_dir` there, must print exactly one banner line containing `resume: 1 functions re-running after interruption (sub_brute)`. The same setup with `FORCE_RESCAN=true` exported must print the rescan banner only and leave NO `.inprogress_*` files.
+ - Behavior smoke (INT/TERM unchanged): sending SIGINT to a real `./reconftw.sh -d test.local -p` invocation MUST still print the red "Interrupted. Cleaning up..." banner from cleanup_on_exit and exit with code 130 (unchanged user-facing behavior).
+ </acceptance_criteria>
+ <done>
+ Separate EXIT-only trap registered via `trap '_cleanup_inprogress' EXIT` adjacent to the existing untouched INT/TERM trap; `_cleanup_inprogress` standalone helper added to modules/utils.sh (sibling to but independent from cleanup_on_exit); cleanup_on_exit body NOT modified; FORCE_RESCAN explicitly clears `.inprogress_*` orphans inside the existing block at :78-80; resume banner emits one WARN line and one JSONL event when leftover sentinels are detected (and only when called_fn_dir is set and FORCE_RESCAN is false); no per-function badges added; graceful exits no longer print an interruption banner; shellcheck clean.
+ </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).
+- Manual smoke (no test files in this phase per CONTEXT Deferred):
+ 1. Source the project: `./reconftw.sh --source-only`.
+ 2. Graceful-exit safety: `( source ./reconftw.sh --source-only; called_fn_dir=$(mktemp -d); start_func test_fn "desc"; end_func "done" test_fn; exit 0 )` — outer `$?` is 0, no "Interrupted. Cleaning up..." banner printed, `.inprogress_*` cleared.
+ 3. Simulate crash: `mkdir -p /tmp/rftw-test/.called_fn && touch /tmp/rftw-test/.called_fn/.inprogress_sub_brute /tmp/rftw-test/.called_fn/.sub_other`.
+ 4. Invoke `start` with `called_fn_dir=/tmp/rftw-test/.called_fn dir=/tmp/rftw-test domain=test.local PRESERVE=true FORCE_RESCAN=false`.
+ 5. Expect: console shows `WARN resume: 1 functions re-running after interruption (sub_brute)` line once; `.sub_other` still present (success checkpoint preserved); `.inprogress_sub_brute` cleared by the EXIT trap when start returns.
+ 6. Repeat with `FORCE_RESCAN=true`: expect rescan banner, no resume banner, both `.inprogress_*` and `.sub_other` files absent.
+ 7. Actual SIGINT smoke: kill -INT a running `./reconftw.sh` — cleanup_on_exit fires with its existing red banner and exit code 130 (UNCHANGED user-facing behavior).
+</verification>
+
+<success_criteria>
+- Plan 01-01 success criterion (ROADMAP §"Phase 1" SC#1): Interrupting recon mid-`sub_brute` and re-running with `PRESERVE=true` produces a clear `.inprogress_sub_brute` indicator and re-executes only that function — completed functions retain `.<func>` checkpoints and are skipped.
+- All `must_haves.truths` verifiable per the acceptance criteria above.
+- No new badge values introduced; existing OK/WARN/FAIL/SKIP/CACHE/INFO/RUN vocabulary preserved.
+- No PID, timestamp, or JSON metadata inside `.inprogress_<fn>` files (D-01 simplicity locked).
+- Single WARN banner line for resume detection; no per-function decoration (D-04 locked).
+- cleanup_on_exit (modules/utils.sh:116-146) is NOT modified; its INT/TERM-only registration is preserved so successful exits never print an interruption banner or force exit 130.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-resilient-resume-timeout-safety/01-01-SUMMARY.md`.
+</output>
+</content>
+</invoke>
\ No newline at end of file
diff --git a/.planning/phases/01-resilient-resume-timeout-safety/01-02-PLAN.md b/.planning/phases/01-resilient-resume-timeout-safety/01-02-PLAN.md
new file mode 100644
index 0000000..69ddf9a
--- /dev/null
+++ b/.planning/phases/01-resilient-resume-timeout-safety/01-02-PLAN.md
@@ -0,0 +1,202 @@
+---
+id: 01-02
+phase: 01
+plan: 02
+type: execute
+wave: 2
+depends_on: [01-01]
+requirements: [RESIL-02]
+files_modified:
+ - modules/utils.sh
+ - modules/core.sh
+autonomous: true
+must_haves:
+ truths:
+ - "D-09: When _check_disk_mid_run reports available_gb < MIN_DISK_SPACE_GB at any function boundary, the run aborts (hard abort, exit 1) with a clear error naming available and required GB and the target directory; soft-abort and pause-and-wait were rejected"
+ - "D-08: The same MIN_DISK_SPACE_GB threshold used by the pre-flight check at modules/modes.sh:23 governs the mid-run check — single source of truth, no separate mid-run knob"
+ - "D-07: Check cadence is at every start_func / end_func boundary — _check_disk_mid_run is invoked at the TOP of start_func (before any state is written) and at the TAIL of end_func (after the .<fn> checkpoint and .status_<fn> are durably written); ~1ms × ~100 boundaries per scan = negligible overhead; no background watcher"
+ - "D-10: ENOSPC detection mechanism is boundary df only — no run_command stderr scanning for `No space left on device`, no per-redirect failure traps; mid-function truncation in a single tool is an accepted trade-off, boundary check catches it before further damage"
+ - "D-09: On hard abort, the existing EXIT trap (registered in Plan 01-01 per D-02) clears all .inprogress_* sentinels so a subsequent run does NOT surface a fake resume condition"
+ - "D-07: When `_check_disk_mid_run` aborts at start_func entry, no `.inprogress_<fn>` is written for the aborting function — the Plan 01-01 sentinel touch has not yet executed; the EXIT trap therefore has no orphan to clear for this specific function. Completed prior functions retain their `.<fn>` checkpoints"
+ - "D-08: No new mid-run disk knob is introduced; reconftw.cfg:39 and modules/modes.sh:23 are NOT modified in this phase (DOCS-02 reconciliation is Phase 5)"
+ artifacts:
+ - path: "modules/utils.sh"
+ provides: "_check_disk_mid_run thin wrapper around check_disk_space; _abort_disk_full emits structured error and exits 1"
+ - path: "modules/core.sh"
+ provides: "start_func and end_func call _check_disk_mid_run at the documented boundaries"
+ key_links:
+ - from: "modules/core.sh:start_func"
+ to: "modules/utils.sh:_check_disk_mid_run"
+ via: "guard pattern: _check_disk_mid_run || _abort_disk_full"
+ pattern: "_check_disk_mid_run.*\\|\\|.*_abort_disk_full"
+ - from: "modules/utils.sh:_abort_disk_full"
+ to: "exit 1"
+ via: "after _print_error + log_json, exit 1 triggers EXIT trap from 01-01"
+ pattern: "exit 1"
+ - from: "modules/utils.sh:_check_disk_mid_run"
+ to: "check_disk_space \"${MIN_DISK_SPACE_GB:-5}\" \"${dir:-.}\""
+ via: "reuses existing helper for df parsing; populates DISK_SPACE_INFO"
+ pattern: "check_disk_space.*MIN_DISK_SPACE_GB"
+---
+
+<objective>
+Add boundary-only mid-run disk-full guard so a recon run aborts cleanly with `ENOSPC`-style error rather than producing zero-byte or truncated outputs when the working filesystem fills mid-scan. Closes RESIL-02.
+
+Purpose: Today, `check_disk_space()` (modules/utils.sh:421) is only called once at the start of each recon mode (modules/modes.sh:23). If disk fills mid-run (e.g., during a 2GB gotator permutation write or a long DNS resolve), tools fail silently and downstream pipeline stages see corrupt partial outputs. This plan installs the same `df`-based check at every `start_func`/`end_func` boundary so the next function entry aborts the run before any further damage.
+
+Output: New private helpers `_check_disk_mid_run` and `_abort_disk_full` in `modules/utils.sh`. `start_func` and `end_func` in `modules/core.sh` call them at the documented anchors (top-of-start, tail-of-end) so the check runs at boundary cadence with negligible overhead (~1ms per call × ~100 boundaries per scan).
+</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]/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md
[email protected]/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md
[email protected]/codebase/CONVENTIONS.md
[email protected]/phases/01-resilient-resume-timeout-safety/01-01-PLAN.md
+
+<interfaces>
+<!-- Key existing identifiers the executor will modify or call. Extracted from codebase. -->
+
+From modules/utils.sh:
+- function check_disk_space() — `:421-436`. Signature: `check_disk_space <required_gb> <path>`. Behavior: parses `df -Pk <path>` to GB, returns 0 if `available_gb >= required_gb` else 1; populates global `DISK_SPACE_INFO` with either "Disk space LOW: required ${required_gb}GB, available ${available_gb}GB at ${check_path}" or "Disk space OK: ${available_gb}GB available at ${check_path}".
+- function cleanup_on_exit() — `:116-146`. NOT modified by Plan 01-01 (cleanup_on_exit remains bound to INT/TERM only). The new EXIT trap installed by Plan 01-01 invokes `_cleanup_inprogress` (a standalone helper), which fires on `exit 1` from `_abort_disk_full` and clears `.inprogress_*` sentinels without printing any banner.
+
+From modules/modes.sh:
+- start() pre-flight at `:23-27`: `local required_space_gb="${MIN_DISK_SPACE_GB:-5}"; if ! check_disk_space "$required_space_gb" "."; then _print_status WARN "Low disk space detected" "Continuing anyway..."; fi`. This is the SAME threshold the mid-run check must use (D-08 single source of truth).
+
+From modules/core.sh:
+- function start_func() — `:1419-1435`. AFTER Plan 01-01 lands, the body order is: `current_date=...` → `echo "[$current_date] Start function..."` → `local _fn_name="${1}"` → `printf -v "_start_time_..."` → `start=$(date +%s)` → [Plan 01-01 inserts touch .inprogress here] → `log_json "INFO" ...` → ui_log_jsonl → `if OUTPUT_VERBOSITY>=2: _print_msg INFO`.
+- function end_func() — `:1437-1531`. AFTER Plan 01-01 lands, the body order is: status case-normalization → [Plan 01-01 inserts rm -f .inprogress here] → `touch "$called_fn_dir/.${fn}"` → timing → badge mapping → `printf "%s\n" "$badge" >"${called_fn_dir}/.status_${fn}"` → `_print_status` → `log_json "SUCCESS"` → (end of function).
+- function log_json() — `:680`.
+
+From lib/common.sh:
+- _print_error() — `:528`. Always-visible stderr error.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+ <name>Task 1: Define _check_disk_mid_run and _abort_disk_full in modules/utils.sh</name>
+ <files>modules/utils.sh</files>
+ <read_first>
+ - modules/utils.sh (current check_disk_space at :421-436 — the analog whose df parsing is reused)
+ - modules/utils.sh (current cleanup_on_exit at :116-146 — sibling style for new private helpers)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md (anchor "modules/utils.sh — check_disk_space sibling helpers" — placement and helper signatures)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (D-07 cadence, D-08 single threshold, D-09 hard abort, D-10 boundary-only)
+ - .planning/codebase/CONVENTIONS.md (Function Naming: underscore-prefix for private; Error Handling: _print_error always visible)
+ </read_first>
+ <action>
+ Insert two new private helpers in modules/utils.sh IMMEDIATELY AFTER the existing `check_disk_space` closing brace at :436 and BEFORE the `progress_bar` block at :440. Both use `function name() { ... }` declaration style (CONVENTIONS.md §Function Naming).
+
+ Helper 1 — `_check_disk_mid_run`:
+ - Single-line doc comment above: `# Mid-run disk-full check: thin wrapper around check_disk_space using MIN_DISK_SPACE_GB (D-07/D-08).`
+ - Body: call `check_disk_space "${MIN_DISK_SPACE_GB:-5}" "${dir:-.}"` and `return $?`. The `:-5` fallback mirrors modes.sh:23 default (D-08 single source of truth). The `${dir:-.}` fallback handles invocations where `dir` is unset (e.g., test harness sourcing) by checking CWD.
+ - Returns 0 if disk OK, 1 if low. Populates `DISK_SPACE_INFO` as a side effect of check_disk_space.
+
+ Helper 2 — `_abort_disk_full`:
+ - Single-line doc comment above: `# Hard-abort the run on disk-full mid-run detection (D-09). EXIT trap (Plan 01-01) clears .inprogress_* on the way out.`
+ - Body:
+ 1. `_print_error "disk_full: aborting (${DISK_SPACE_INFO:-disk space exhausted})"` — uses the always-visible stderr helper from lib/common.sh:528. Includes the DISK_SPACE_INFO string already populated by _check_disk_mid_run for available/required context.
+ 2. `log_json "ERROR" "${FUNCNAME[1]:-main}" "Disk space exhausted" "reason=disk_full" "info=${DISK_SPACE_INFO:-unknown}"` — uses `FUNCNAME[1]` to log the CALLER's name (start_func or end_func), not _abort_disk_full itself. Reuses the log_json shape from modules/core.sh:1428/1525.
+ 3. `exit 1` — hard-aborts the entire process. The EXIT trap installed in Plan 01-01 (`trap '_cleanup_inprogress' EXIT`) fires automatically and clears all `.inprogress_*` files so a subsequent invocation does not see a fake resume condition (D-09 closing rationale). Returns nothing else after exit.
+
+ Do NOT introduce a new global. Do NOT add a separate "mid-run threshold" knob (D-08 single source of truth). Do NOT add `run_command` stderr scanning or per-redirect ENOSPC traps (D-10 boundary-only is locked). Do NOT call `exit 1` from `_check_disk_mid_run` — caller is responsible for chaining `_check_disk_mid_run || _abort_disk_full`.
+
+ Both helpers MUST be defined BEFORE the call sites in modules/core.sh are added (Task 2). The sourcing order in reconftw.sh loads `modules/utils.sh` before `modules/core.sh` (per CONVENTIONS.md §Import / Sourcing Order), so this ordering is naturally satisfied.
+ </action>
+ <verify>
+ <automated>bash -n /Users/six2dez/Tools/reconftw/modules/utils.sh && shellcheck -s bash --severity=error /Users/six2dez/Tools/reconftw/modules/utils.sh</automated>
+ </verify>
+ <acceptance_criteria>
+ - `grep -n '^function _check_disk_mid_run' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns exactly one match.
+ - `grep -n '^function _abort_disk_full' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns exactly one match.
+ - `grep -n 'check_disk_space "\${MIN_DISK_SPACE_GB:-5}"' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns at least one match (inside _check_disk_mid_run body).
+ - `grep -n 'reason=disk_full' /Users/six2dez/Tools/reconftw/modules/utils.sh` returns at least one match (inside _abort_disk_full log_json call).
+ - `grep -n '^[[:space:]]*exit 1' /Users/six2dez/Tools/reconftw/modules/utils.sh` shows at least one new occurrence inside `_abort_disk_full` (file may have other unrelated `exit 1` sites; the one inside _abort_disk_full must be present).
+ - Both new helpers placed AFTER `check_disk_space` closing brace and BEFORE `progress_bar` (visual ordering): `grep -n 'check_disk_space\|_check_disk_mid_run\|_abort_disk_full\|progress_bar' modules/utils.sh | head` shows the order check_disk_space → _check_disk_mid_run → _abort_disk_full → progress_bar.
+ - `bash -n modules/utils.sh` exits 0.
+ - `shellcheck -s bash --severity=error modules/utils.sh` exits 0 (no new error-level findings).
+ - Behavior smoke: source `--source-only`, set `MIN_DISK_SPACE_GB=99999999`, set `dir=/tmp`, call `_check_disk_mid_run; echo $?` — expect `1`. Set `MIN_DISK_SPACE_GB=0`, call `_check_disk_mid_run; echo $?` — expect `0`. `_abort_disk_full` cannot be tested without exiting the test shell; verify visually that body contains exit 1.
+ </acceptance_criteria>
+ <done>
+ Two private helpers added with correct placement, sibling-style declaration, single-threshold reuse of MIN_DISK_SPACE_GB, structured log emission via log_json, and hard-exit semantics in _abort_disk_full; shellcheck clean.
+ </done>
+</task>
+
+<task type="auto">
+ <name>Task 2: Call _check_disk_mid_run at start_func top + end_func tail</name>
+ <files>modules/core.sh</files>
+ <read_first>
+ - modules/core.sh (current start_func :1419-1435 — AFTER Plan 01-01 lands, the .inprogress touch sits between :1425 and :1428)
+ - modules/core.sh (current end_func :1437-1531 — AFTER Plan 01-01 lands, the .inprogress rm sits immediately BEFORE the .<fn> touch at :1465)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md (anchor "Insertion anchor (D-01 sentinel + D-07 disk check)" — exact placement)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (D-07: "start_func calls it BEFORE the existing body; end_func calls it AFTER touching the checkpoint")
+ </read_first>
+ <action>
+ In modules/core.sh start_func (at :1419, after Plan 01-01 lands): insert `_check_disk_mid_run || _abort_disk_full` as the VERY FIRST executable statement INSIDE the function body — that is, immediately AFTER the opening `{` and BEFORE the `local current_date` line at :1420. This placement ensures the disk-full abort fires before any LOGFILE write, any timestamp setup, any sentinel touch (the .inprogress touch added by 01-01 will run AFTER this guard).
+
+ In modules/core.sh end_func (at :1437, after Plan 01-01 lands): insert `_check_disk_mid_run || _abort_disk_full` as the VERY LAST executable statement of the function body — immediately AFTER the existing `log_json "SUCCESS" ...` call at :1525 (and after the `ui_log_jsonl` block at :1526-1528) and BEFORE the trailing `:` no-op at :1530 and the closing `}` at :1531. Per D-07 / PATTERNS.md "post-checkpoint disk check", this placement ensures the `.<fn>` checkpoint and `.status_<fn>` / `.status_reason_<fn>` files are durably written for the just-finished function BEFORE the abort can fire. A disk-full abort detected at end_func therefore still leaves a complete success record for the function that just finished.
+
+ Both call sites use the exact pattern `_check_disk_mid_run || _abort_disk_full` — short-circuit OR so _abort_disk_full only runs on non-zero return. No `if/then/fi` wrapper, no other transformations. No additional logging at the call sites (the helpers emit their own messages).
+
+ Do NOT call `_check_disk_mid_run` anywhere ELSE in this phase — boundary-only cadence is locked (D-10). Do NOT add `set -e` or any new shell options. Do NOT modify the order of the existing Plan 01-01 sentinel ops at start_func or end_func.
+
+ Note on context with Plan 01-01: after both plans land, start_func body order is (1) `_check_disk_mid_run || _abort_disk_full`, (2) all the existing pre-Plan-01-01 setup (`current_date`, LOGFILE write, _fn_name, printf -v start time, `start=`), (3) Plan 01-01 inserted `touch .inprogress`, (4) existing log_json INFO + ui_log_jsonl + verbose INFO print. end_func order is mostly unchanged with two insertions: (1) Plan 01-01 inserted `rm -f .inprogress` before the existing `touch .<fn>`, (2) Plan 01-02 inserted `_check_disk_mid_run || _abort_disk_full` after the existing `log_json SUCCESS` block. The two plans MUST land in order (01-01 first, 01-02 second) — captured in this plan's frontmatter via `depends_on: [01-01]` and `wave: 2`.
+
+ Sentinel-state contract on abort at start_func entry: because the Plan 01-02 disk check is the FIRST executable statement in start_func and the Plan 01-01 `touch .inprogress_<fn>` runs LATER in the same function, a disk-full abort at start_func entry happens BEFORE the sentinel touch for that function. Result: no `.inprogress_<fn>` is written for the aborting function. The EXIT trap from Plan 01-01 still fires and clears any sentinels that earlier functions might have left behind (there should be none if those earlier functions completed cleanly via end_func, which also clears them). A disk-full abort at end_func tail happens AFTER the `.<fn>` and `.status_<fn>` writes and AFTER the Plan 01-01 `rm -f .inprogress_<fn>`, so again the completing function leaves no sentinel orphan. Net effect: on disk-full abort, completed prior functions retain their `.<fn>` success checkpoints; the aborting function leaves no sentinel; the next run sees no resume banner for the aborting function (which is correct — disk-full is not a crash-recovery scenario).
+ </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>
+ - `grep -nc '_check_disk_mid_run || _abort_disk_full' /Users/six2dez/Tools/reconftw/modules/core.sh` returns 2 (one in start_func, one in end_func).
+ - In start_func: the `_check_disk_mid_run || _abort_disk_full` line appears BEFORE the `local current_date` line and BEFORE the Plan 01-01 `touch "$called_fn_dir/.inprogress_` line. Verifiable via: `awk '/^function start_func/,/^}/' modules/core.sh | grep -n '_check_disk_mid_run\|local current_date\|touch "\$called_fn_dir/\.inprogress_' | head` — first match must be `_check_disk_mid_run`.
+ - In end_func: the `_check_disk_mid_run || _abort_disk_full` line appears AFTER the `log_json "SUCCESS"` line and BEFORE the closing `}`. Verifiable via: `awk '/^function end_func/,/^}/' modules/core.sh | grep -n 'log_json "SUCCESS"\|_check_disk_mid_run\|^}'` — the order must be `log_json "SUCCESS"` → `_check_disk_mid_run` → `}`.
+ - The Plan 01-01 lines (`touch "$called_fn_dir/.inprogress_${1}"` in start_func and `rm -f "$called_fn_dir/.inprogress_${fn}"` in end_func) are still present and unchanged.
+ - The existing `touch "$called_fn_dir/.${fn}"` at :1465 is still present.
+ - `bash -n modules/core.sh` exits 0.
+ - `shellcheck -s bash --severity=error modules/core.sh` exits 0 (no new error-level findings).
+ - Behavior smoke: with `MIN_DISK_SPACE_GB=99999999` exported, invoking a real recon command (`./reconftw.sh -d test.local -p --dry-run` or any source-only test that calls start_func) MUST cause the process to exit non-zero with stderr containing `disk_full: aborting` and the JSONL log file (if STRUCTURED_LOGGING=true) MUST contain `reason=disk_full`. With `MIN_DISK_SPACE_GB=0` the run proceeds normally.
+ - Sentinel-state smoke on disk-full at start_func: `mkdir -p /tmp/rftw-test/.called_fn && export dir=/tmp/rftw-test called_fn_dir=/tmp/rftw-test/.called_fn LOGFILE=/tmp/rftw-test/log.txt MIN_DISK_SPACE_GB=99999999`, then call `start_func test_fn "desc"` — process exits 1; check `ls "$called_fn_dir"/.inprogress_*` shows NO file for test_fn (sentinel never touched). Pre-seeded `.other_fn` checkpoint files remain present.
+ </acceptance_criteria>
+ <done>
+ Both call sites added in canonical short-circuit form at the documented anchors; existing Plan 01-01 sentinel ops untouched; existing `.<fn>` touch unchanged; shellcheck clean.
+ </done>
+</task>
+
+</tasks>
+
+<verification>
+- `bash -n modules/utils.sh modules/core.sh` → exit 0.
+- `shellcheck -s bash --severity=error modules/utils.sh modules/core.sh` → exit 0 (no NEW error-level findings vs baseline).
+- Manual smoke (no test files in this phase per CONTEXT Deferred):
+ 1. Source the project: `./reconftw.sh --source-only`.
+ 2. Force disk-full: `export MIN_DISK_SPACE_GB=99999999`.
+ 3. Set up minimal state: `mkdir -p /tmp/rftw-test/.called_fn && export dir=/tmp/rftw-test called_fn_dir=/tmp/rftw-test/.called_fn LOGFILE=/tmp/rftw-test/log.txt STRUCTURED_LOGGING=true STRUCTURED_LOG_FILE=/tmp/rftw-test/events.jsonl`.
+ 4. Call `start_func test_fn "desc"` directly — expect immediate exit 1, stderr contains `disk_full: aborting`, and `/tmp/rftw-test/events.jsonl` contains a line with `"reason":"disk_full"` (or equivalent JSONL shape). Verify NO `.inprogress_test_fn` was created (the disk check ran before the sentinel touch).
+ 5. Verify EXIT trap composition with Plan 01-01: with `MIN_DISK_SPACE_GB=99999999` and a pre-seeded `.inprogress_sub_brute` in `called_fn_dir`, a `start` invocation that aborts via _abort_disk_full must STILL clear the `.inprogress_*` files via the EXIT trap chain (no fake resume condition for the next run).
+</verification>
+
+<success_criteria>
+- Plan 01-02 success criterion (ROADMAP §"Phase 1" SC#2): A scan that exhausts disk space mid-run aborts with a clear `ENOSPC` error message rather than producing zero-byte or truncated output files.
+- All `must_haves.truths` verifiable per the acceptance criteria above.
+- MIN_DISK_SPACE_GB threshold used by mid-run check is the same as pre-flight (single source of truth; no new knob).
+- No `run_command` stderr scanning, no per-redirect ENOSPC traps (D-10 boundary-only locked).
+- No modification to `reconftw.cfg:39` or `modules/modes.sh:23` (DOCS-02 reconciliation is Phase 5).
+- _abort_disk_full exits 1 and lets the Plan 01-01 EXIT trap clear `.inprogress_*` automatically — no double-cleanup logic.
+- Disk-full abort at start_func entry leaves no `.inprogress_<fn>` for the aborting function (the disk check precedes the sentinel touch); completed prior functions retain their `.<fn>` checkpoints.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-resilient-resume-timeout-safety/01-02-SUMMARY.md`.
+</output>
+</content>
+</invoke>
\ No newline at end of file
diff --git a/.planning/phases/01-resilient-resume-timeout-safety/01-03-PLAN.md b/.planning/phases/01-resilient-resume-timeout-safety/01-03-PLAN.md
new file mode 100644
index 0000000..4e71cb0
--- /dev/null
+++ b/.planning/phases/01-resilient-resume-timeout-safety/01-03-PLAN.md
@@ -0,0 +1,264 @@
+---
+id: 01-03
+phase: 01
+plan: 03
+type: execute
+wave: 1
+depends_on: []
+requirements: [RESIL-03, PERF-02]
+files_modified:
+ - lib/parallel.sh
+ - reconftw.cfg
+autonomous: true
+must_haves:
+ truths:
+ - "D-11: Default PARALLEL_JOB_TIMEOUT_SECONDS=0 (disabled, opt-in) — parallel_funcs behavior is identical to today, no jobs killed by the timeout path; zero risk of an in-flight scan getting killed by an aggressive default"
+ - "D-13: When PARALLEL_JOB_TIMEOUT_SECONDS>0 and a single parallel_funcs child exceeds the threshold, _timeout_kill_job sends SIGTERM, polls kill -0 once per second up to PARALLEL_KILL_GRACE_SECONDS, then SIGKILL if still alive — aligns with Unix shutdown semantics and protects against tools that ignore TERM"
+ - "D-14: On timeout kill, the persisted status (.status_<fn>=FAIL) and reason (.status_reason_<fn>=timeout) are written so _parallel_emit_job_output renders FAIL badge with `(timeout)` on the console; failed++ → RECON_PARTIAL_RUN=true via existing aggregator"
+ - "D-12: Timeout kill logic is inserted INSIDE the existing batch-flush heartbeat loop at lib/parallel.sh:432-465 AND the final-wait heartbeat at :537-569 — extends the existing `kill -0 ${batch_pids[$idx]}` poll with `now - batch_starts[$idx] > PARALLEL_JOB_TIMEOUT_SECONDS` check; two-loop symmetry preserved"
+ - "D-14: _parallel_emit_job_output's reason-render conditional is widened to also print `reason: timeout` (or inline parenthetical) for FAIL badges, alongside the existing SKIP/CACHE rendering"
+ - "D-15: Timeout applies uniformly to BOTH local and axiom-distributed jobs — parallel batch wrapper is the same code path for both; no special-casing for axiom"
+ - "D-16: reconftw.cfg:387-388 ships DNS_BRUTE_TIMEOUT=6h and DNS_RESOLVE_TIMEOUT=4h (was 0); _run_dns_with_heartbeat is NOT modified (already respects 0=disabled and accepts h-suffix durations honored by timeout/gtimeout)"
+ - "D-17: When the DNS hard timeout trips, the existing _run_dns_with_heartbeat already returns non-zero and emits a clear log line; existing WARN badge from end_func is sufficient surfacing; JSONL log carries reason=dns_hard_timeout so downstream tools (Phase 4 tests, AI report) can distinguish"
+ - "D-11: reconftw.cfg ships PARALLEL_JOB_TIMEOUT_SECONDS=0 (disabled by default) with doc comment listing 3600/600 examples, and PARALLEL_KILL_GRACE_SECONDS=10"
+ artifacts:
+ - path: "lib/parallel.sh"
+ provides: "_timeout_kill_job helper + timeout kill check inside both heartbeat loops + reason rendering for FAIL badges"
+ - path: "reconftw.cfg"
+ provides: "Four config lines — DNS_BRUTE_TIMEOUT/DNS_RESOLVE_TIMEOUT default value changes plus PARALLEL_JOB_TIMEOUT_SECONDS/PARALLEL_KILL_GRACE_SECONDS new knobs"
+ key_links:
+ - from: "lib/parallel.sh heartbeat loop (line ~445 batch-flush, ~549 final-wait)"
+ to: "_timeout_kill_job"
+ via: "if PARALLEL_JOB_TIMEOUT_SECONDS > 0 and job_dur > threshold"
+ pattern: "PARALLEL_JOB_TIMEOUT_SECONDS.*_timeout_kill_job"
+ - from: "_timeout_kill_job"
+ to: "$called_fn_dir/.status_<fn> + .status_reason_<fn>"
+ via: "printf FAIL + printf timeout (reuses end_func persistence pattern)"
+ pattern: "printf \"FAIL\\\\n\".*status_.*printf \"timeout"
+ - from: "_parallel_emit_job_output reason render"
+ to: "console badge"
+ via: "widened conditional to include FAIL alongside SKIP/CACHE"
+ pattern: "badge == \"FAIL\".*reason"
+---
+
+<objective>
+Add `PARALLEL_JOB_TIMEOUT_SECONDS` enforcement so stuck tools no longer stall a parallel batch, and set non-zero DNS timeout defaults so a hung resolver does not block a run indefinitely. Closes RESIL-03 and PERF-02.
+
+Purpose: Today, the heartbeat loop at `lib/parallel.sh:432-465` polls alive PIDs every `PARALLEL_HEARTBEAT_SECONDS` but provides no kill mechanism for stuck jobs. A single hung tool stalls the entire batch barrier-sync. Separately, `DNS_BRUTE_TIMEOUT=0` and `DNS_RESOLVE_TIMEOUT=0` at `reconftw.cfg:387-388` ship as disabled; `_run_dns_with_heartbeat` (modules/utils.sh:1434) already supports non-zero durations but the defaults never trigger.
+
+Output: New private helper `_timeout_kill_job` in `lib/parallel.sh`; timeout-check inserted in both heartbeat loops (batch-flush at :432-465 and final-wait at :537-569); reason rendering for FAIL badges widened in `_parallel_emit_job_output`; four config lines in `reconftw.cfg` (two value changes for DNS, two new parallel knobs). No CLI flag added (env-var/cfg override is sufficient for v1 per CONTEXT §Established Patterns).
+</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]/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md
[email protected]/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md
[email protected]/codebase/CONVENTIONS.md
+
+<interfaces>
+<!-- Key existing identifiers the executor will modify or call. Extracted from codebase. -->
+
+From lib/parallel.sh:
+- Source guard at `:6`: `[[ -n "$_PARALLEL_SH_LOADED" ]] && return 0`. Preserved as-is.
+- PARALLEL_HEARTBEAT_SECONDS init at `:15`: `PARALLEL_HEARTBEAT_SECONDS="${PARALLEL_HEARTBEAT_SECONDS:-20}"`. Pattern for new knob init.
+- _throttle_jobs() at `:33-42`. Sibling style for new `_timeout_kill_job` helper. NOTE: sibling helpers in this file (`_throttle_jobs`, `_parallel_live_break`, `_parallel_emit_job_output`) currently use the bare `name() {` declaration form, which contradicts CONVENTIONS.md §Function Naming (`function name() {`). Those pre-date the rule; new code in this plan follows the project-wide rule.
+- _parallel_emit_job_output() at `:172-300`. Reads `.status_<fn>` (`:204`) and `.status_reason_<fn>` (`:224`). Currently renders reason for SKIP/CACHE only — three locations to widen (summary mode at :261-263, tail mode at :279-281, full mode similar).
+- Batch-flush heartbeat loop at `:432-465`. Iterates alive PIDs, computes `job_dur=$((now - batch_starts[$idx]))` (`:445`). Insertion site for timeout check inside the `if kill -0` branch (`:443`).
+- Final-wait heartbeat loop at `:537-569`. Structurally identical to batch-flush; second insertion site at the same relative position.
+
+From modules/core.sh:
+- Status persistence pattern at `:1505-1509`: `printf "%s\n" "$badge" >"${called_fn_dir}/.status_${fn}" 2>/dev/null || true; printf "%s\n" "$reason_code" >"${called_fn_dir}/.status_reason_${fn}" 2>/dev/null || true`. _timeout_kill_job reuses this exact write pattern with FAIL + timeout values.
+
+From modules/utils.sh:
+- _run_dns_with_heartbeat() at `:1434-1452`. Already supports `0=disabled` via `_dns_timeout_enabled`. Already passes h-suffix durations through to `timeout`/`gtimeout` via the existing `"$TIMEOUT_CMD" -k 10s "$timeout_value" "$@"` call at `:1444`. NO CODE CHANGE here for PERF-02 — only the cfg defaults flip from 0 to 6h/4h.
+
+From reconftw.cfg:
+- DNS timeout block at `:386-389` — three lines around PERMUTATIONS_LIMIT and DNS_HEARTBEAT_INTERVAL_SECONDS. The two value-change lines (:387, :388) are the modification sites.
+- Parallelization block at `:302-312` — group `PARALLEL_MODE` through `PARALLEL_TRACE_SLOW_SECONDS`. Insertion site for the two new knobs is immediately after :312.
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+ <name>Task 1: _timeout_kill_job helper + timeout enforcement in both heartbeat loops</name>
+ <files>lib/parallel.sh</files>
+ <read_first>
+ - lib/parallel.sh (entire file overview, paying attention to :1-50 source guard + knob inits, :33-42 _throttle_jobs analog, :172-300 _parallel_emit_job_output reason render, :432-465 batch-flush heartbeat, :537-569 final-wait heartbeat)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md (anchor "lib/parallel.sh — heartbeat-loop timeout enforcement" — exact insertion site, helper signature, two-loop symmetry rule, FAIL-reason-render widening)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (D-11 default 0, D-12 enforcement point inside heartbeat, D-13 TERM-then-KILL grace, D-14 FAIL reason=timeout reuse, D-15 axiom uniformity)
+ - .planning/codebase/CONVENTIONS.md (Function Naming: `function name() {` form is the project-wide rule; only lib/ui.sh and lib/common.sh are listed exceptions; lib/parallel.sh is NOT exempt)
+ - modules/core.sh :1505-1509 (status persistence pattern reused verbatim by _timeout_kill_job)
+ </read_first>
+ <action>
+ Step A — Define `_timeout_kill_job` helper in lib/parallel.sh. Place it BETWEEN the existing `_throttle_jobs` function (closes at :42) and the existing `_parallel_live_break` function (`:44`). Declare using the canonical `function _timeout_kill_job() { ... }` form per CONVENTIONS.md §Function Naming (the project-wide rule; only lib/ui.sh and lib/common.sh are exempt). Add a single-line note immediately above the declaration: `# Uses 'function' keyword per CONVENTIONS.md §Function Naming; sibling helpers in this file that omit it predate the rule and are a Phase 5 DOCS-01 followup, not a precedent for new code.`
+
+ Helper signature: `_timeout_kill_job <pid> <func_name> <duration_sec>`.
+ Body steps:
+ 1. `local pid="$1" func_name="$2" duration_sec="$3"` — local-declare all positional args (CONVENTIONS.md §Variable Naming).
+ 2. `local grace="${PARALLEL_KILL_GRACE_SECONDS:-10}"; [[ "$grace" =~ ^[0-9]+$ ]] || grace=10` — defensive integer coercion mirroring the existing pattern at `:434` (`[[ "$hb" =~ ^[0-9]+$ ]] || hb=20`-style).
+ 3. `kill -TERM "$pid" 2>/dev/null || true` — D-13 first signal. The `2>/dev/null || true` is mandatory (PID may exit between check and kill) — pattern at `:443`.
+ 4. Poll loop: `local i; for ((i=0; i<grace; i++)); do kill -0 "$pid" 2>/dev/null || break; sleep 1; done`. Exits early if the process honored TERM.
+ 5. `kill -KILL "$pid" 2>/dev/null || true` — D-13 fallback for tools that ignore TERM. Idempotent — no-op if process already exited.
+ 6. Persist FAIL status reusing modules/core.sh:1505-1509 pattern verbatim: `if [[ -n "${called_fn_dir:-}" ]]; then printf "FAIL\n" >"${called_fn_dir}/.status_${func_name}" 2>/dev/null || true; printf "timeout\n" >"${called_fn_dir}/.status_reason_${func_name}" 2>/dev/null || true; fi`. The downstream `_parallel_emit_job_output` reads these files at :203-209/:223-224 and renders the badge accordingly.
+ 7. Emit structured log via `log_json "ERROR" "${func_name}" "Job timed out" "reason=timeout" "duration_sec=${duration_sec}"`. The `log_json` function is defined in modules/core.sh:680 and is no-op when STRUCTURED_LOGGING != true. The `lib/parallel.sh` is sourced before modules/core.sh per CONVENTIONS.md §Import / Sourcing Order, but at RUNTIME (when this helper is invoked by parallel_funcs called from inside a module function), log_json is already defined globally — safe to call.
+
+ Step B — Insert the timeout check inside the BATCH-FLUSH heartbeat loop (lib/parallel.sh:432-465). Locate the existing `if kill -0 "${batch_pids[$idx]}" 2>/dev/null; then` branch at :443 and the `job_dur=$((now - batch_starts[$idx]))` line at :445. IMMEDIATELY AFTER the `job_dur` computation and BEFORE the `dur_fmt=$(format_duration "$job_dur")` line at :446, insert:
+
+ ```
+ # Timeout enforcement (RESIL-03 / D-11..D-14): if PARALLEL_JOB_TIMEOUT_SECONDS > 0
+ # and the live job has exceeded it, TERM-then-KILL and persist FAIL + reason=timeout.
+ 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
+ ```
+
+ The post-loop `wait "${batch_pids[$idx]}"` at :470 collects the killed process's non-zero rc, and `_parallel_emit_job_output` at :483 reads the FAIL + timeout from the status files. NO change to the wait or emit code paths is required.
+
+ Step C — Insert the IDENTICAL block in the FINAL-WAIT heartbeat loop (lib/parallel.sh:537-569). Locate the same `if kill -0 "${batch_pids[$idx]}" 2>/dev/null; then` branch (around :547) and the `job_dur=$((now - batch_starts[$idx]))` line (around :549). Insert the same `# Timeout enforcement` block at the same relative position. Two-loop symmetry is mandatory per PATTERNS.md (the two heartbeat loops are structurally identical and the audit history treats them as one logical pattern).
+
+ Step D — Widen the reason-render conditional in `_parallel_emit_job_output`. In the `summary` mode branch at :261-263 the existing condition is:
+
+ ```
+ if [[ -n "$reason_code" ]] && { [[ "$badge" == "SKIP" ]] || { [[ "$badge" == "CACHE" ]] && [[ "${SHOW_CACHE:-false}" == "true" ]]; }; }; then
+ printf " reason: %s\n" "$reason_code"
+ fi
+ ```
+
+ Widen the condition to also fire when `badge == "FAIL"` so D-14 timeout reasons are surfaced. The updated condition:
+
+ ```
+ if [[ -n "$reason_code" ]] && { [[ "$badge" == "SKIP" ]] || [[ "$badge" == "FAIL" ]] || { [[ "$badge" == "CACHE" ]] && [[ "${SHOW_CACHE:-false}" == "true" ]]; }; }; then
+ printf " reason: %s\n" "$reason_code"
+ fi
+ ```
+
+ Apply the SAME widening to the `tail` mode branch (similar conditional at :279-281). Inspect the `full` mode branch (after :283) for the same conditional — if present, widen identically. The line-pattern stays the same; only the gate widens (no rewrite of the printf).
+
+ DO NOT introduce a new badge value (FAIL exists). DO NOT modify the post-loop `wait` semantics or the badge-aggregation case statement at :484-491 (it already counts FAIL into `failed++`, which sets `RECON_PARTIAL_RUN=true` via the existing aggregator — D-14 reuses this pipeline). DO NOT special-case axiom-distributed jobs (D-15: timeout kill targets the local subshell PID which itself dispatches axiom-scan; killing the subshell signals axiom-scan which signals remote nodes).
+ </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>
+ - `grep -nE '^function _timeout_kill_job\(\) \{' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 1 (project-wide `function name() {` form per CONVENTIONS.md).
+ - The bare `^_timeout_kill_job\(\)` form MUST NOT be present: `grep -cE '^_timeout_kill_job\(\)' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns 0.
+ - `grep -n 'kill -TERM "\$pid"' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns at least one match inside _timeout_kill_job body.
+ - `grep -n 'kill -KILL "\$pid"' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns at least one match inside _timeout_kill_job body.
+ - `grep -nc 'PARALLEL_KILL_GRACE_SECONDS' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns >=1 (at least once inside _timeout_kill_job).
+ - `grep -c 'printf "FAIL\\\\n" >"\${called_fn_dir}/\.status_' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns >=1 (the persistence write inside _timeout_kill_job).
+ - `grep -c 'printf "timeout\\\\n" >"\${called_fn_dir}/\.status_reason_' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns >=1.
+ - `grep -c '_timeout_kill_job "\${batch_pids\[\$idx\]}" "\${batch_funcs\[\$idx\]}"' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns exactly 2 (one in batch-flush loop, one in final-wait loop — two-loop symmetry).
+ - `grep -c 'PARALLEL_JOB_TIMEOUT_SECONDS' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns >=2 (at least the two call-site occurrences inside the heartbeat loops; helper itself may not reference it).
+ - Reason-render widening verified: `grep -c '"\$badge" == "FAIL"' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns >=2 (summary and tail branches, plus optionally full branch). All inside the same conditional-disjunction pattern alongside `"$badge" == "SKIP"`.
+ - The DOCS-01 followup note appears above the helper: `grep -c 'DOCS-01 followup' /Users/six2dez/Tools/reconftw/lib/parallel.sh` returns >=1.
+ - `bash -n lib/parallel.sh` exits 0.
+ - `shellcheck -s bash --severity=error lib/parallel.sh` exits 0 (no new error-level findings).
+ - Behavior smoke (no test files in this phase per Deferred): manually invoke a synthetic batch via `--source-only`-loaded shell, e.g. `source ./reconftw.sh && called_fn_dir=$(mktemp -d) && PARALLEL_JOB_TIMEOUT_SECONDS=2 PARALLEL_KILL_GRACE_SECONDS=1 PARALLEL_HEARTBEAT_SECONDS=1 parallel_funcs 1 my_slow_func` where my_slow_func is a test stub `function my_slow_func() { sleep 30; }`. After ~3 seconds the job is killed; `.status_my_slow_func` file contains `FAIL` and `.status_reason_my_slow_func` contains `timeout`; console shows `FAIL my_slow_func Xs` followed by `reason: timeout` line.
+ </acceptance_criteria>
+ <done>
+ _timeout_kill_job helper defined with `function name() {` form per CONVENTIONS.md (with DOCS-01 followup note about pre-existing siblings), TERM-then-KILL grace logic, timeout check inserted in BOTH heartbeat loops at the documented anchor; reason rendering widened to also print on FAIL badges; no new badge introduced; no axiom special-casing; shellcheck clean.
+ </done>
+</task>
+
+<task type="auto">
+ <name>Task 2: Update reconftw.cfg — DNS timeout defaults + two new parallel knobs</name>
+ <files>reconftw.cfg</files>
+ <read_first>
+ - reconftw.cfg (current DNS timeout block at :386-389 — value-change site; current Parallelization block at :302-312 — new-knob insertion site)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md (anchor "reconftw.cfg — DNS timeouts and new parallel knobs" — exact line targets and inline-comment style)
+ - .planning/phases/01-resilient-resume-timeout-safety/01-CONTEXT.md (D-11 default 0 ships disabled; D-13 default grace 10; D-16 DNS_BRUTE_TIMEOUT=6h, DNS_RESOLVE_TIMEOUT=4h)
+ </read_first>
+ <action>
+ Step A — Modify the DNS timeout lines at `reconftw.cfg:387-388`. Per D-16:
+ - Change `:387` from `DNS_BRUTE_TIMEOUT=0` to `DNS_BRUTE_TIMEOUT=6h`. Update the inline comment to reflect non-zero default. The comment in the existing file mentions `e.g. 4h` for DNS_BRUTE_TIMEOUT; per D-16 the BRUTE value is 6h (D-16 in CONTEXT.md is authoritative — the existing inline-comment example is inverted, fix it). New line: `DNS_BRUTE_TIMEOUT=6h # timeout/gtimeout duration for DNS bruteforce (0 disables hard-timeout). Default protects against hung resolvers.`
+ - Change `:388` from `DNS_RESOLVE_TIMEOUT=0` to `DNS_RESOLVE_TIMEOUT=4h`. New line: `DNS_RESOLVE_TIMEOUT=4h # timeout/gtimeout duration for DNS resolve (0 disables hard-timeout). Default protects against hung resolvers.`
+ - DO NOT modify `:389` (`DNS_HEARTBEAT_INTERVAL_SECONDS=20`) or `:386` (`PERMUTATIONS_LIMIT`).
+ - Preserve the alignment style of surrounding lines (end-of-line `#` comment, leading column-aligned value).
+
+ Step B — Add two new knobs at the end of the Parallelization block. Insert IMMEDIATELY AFTER the existing `PARALLEL_TRACE_SLOW_SECONDS=30 # ...` line at `:312` and BEFORE the comment line `# Parallel batch sizing per module group ...` at `:314`. Insert:
+
+ ```
+ # Per-job timeout (RESIL-03 / D-11..D-14). Default 0 = disabled (opt-in); suggested values:
+ # 3600 (1h) for long unattended scans, 600 (10min) for CI smoke runs.
+ # When > 0, parallel_funcs heartbeat sends SIGTERM after the threshold and SIGKILL after
+ # PARALLEL_KILL_GRACE_SECONDS if the job ignores TERM. Applies to both local and axiom jobs.
+ # Actual kill latency is the threshold + ~1s (heartbeat poll cadence) + PARALLEL_KILL_GRACE_SECONDS before SIGKILL.
+ PARALLEL_JOB_TIMEOUT_SECONDS=0 # 0 disables; e.g. 3600 for long scans, 600 for CI
+ PARALLEL_KILL_GRACE_SECONDS=10 # Seconds between TERM and KILL when enforcing PARALLEL_JOB_TIMEOUT_SECONDS
+ ```
+
+ The default value of 0 is deliberate per D-11 (locked) — DO NOT propose a non-zero default. The doc comment listing 3600 and 600 examples is mandatory per D-11 / CONTEXT §Specifics. The added "Actual kill latency is the threshold + ~1s (heartbeat poll cadence) + PARALLEL_KILL_GRACE_SECONDS before SIGKILL." line is documentation only (no code change); it makes the effective kill latency explicit for users tuning the knob for CI deadlines.
+
+ DO NOT add a CLI flag for either knob (per CONTEXT §Established Patterns: "any new config knob added in this phase does NOT need a CLI flag for v1"). DO NOT modify `lib/parallel.sh:15` PARALLEL_HEARTBEAT_SECONDS init (that's a DOCS-01/Phase-5 concern). DO NOT touch `reconftw.cfg:39` MIN_DISK_SPACE_GB (that's DOCS-02/Phase-5).
+
+ Step C — Verify no unrelated lines are touched. The diff should affect exactly:
+ - 2 modified lines at :387-388 (DNS_BRUTE_TIMEOUT, DNS_RESOLVE_TIMEOUT values + comments)
+ - 7 new lines inserted between :312 and :314 (5 comment lines including the kill-latency note + 2 knob assignments)
+
+ Total: 2 lines modified, 7 lines added. No deletions.
+ </action>
+ <verify>
+ <automated>bash -n /Users/six2dez/Tools/reconftw/reconftw.cfg && shellcheck -s bash --severity=error /Users/six2dez/Tools/reconftw/reconftw.cfg</automated>
+ </verify>
+ <acceptance_criteria>
+ - `grep -c '^DNS_BRUTE_TIMEOUT=6h' /Users/six2dez/Tools/reconftw/reconftw.cfg` returns exactly 1.
+ - `grep -c '^DNS_RESOLVE_TIMEOUT=4h' /Users/six2dez/Tools/reconftw/reconftw.cfg` returns exactly 1.
+ - `grep -c '^DNS_BRUTE_TIMEOUT=0\b' /Users/six2dez/Tools/reconftw/reconftw.cfg` returns exactly 0 (old value removed).
+ - `grep -c '^DNS_RESOLVE_TIMEOUT=0\b' /Users/six2dez/Tools/reconftw/reconftw.cfg` returns exactly 0 (old value removed).
+ - `grep -c '^PARALLEL_JOB_TIMEOUT_SECONDS=0' /Users/six2dez/Tools/reconftw/reconftw.cfg` returns exactly 1 (new knob shipped disabled).
+ - `grep -c '^PARALLEL_KILL_GRACE_SECONDS=10' /Users/six2dez/Tools/reconftw/reconftw.cfg` returns exactly 1.
+ - Doc comment with `3600` and `600` examples present: `grep -c '3600' /Users/six2dez/Tools/reconftw/reconftw.cfg` and `grep -c '600' /Users/six2dez/Tools/reconftw/reconftw.cfg` each return >=1 in the new comment block (filter to the new section: `awk '/^# Per-job timeout/,/^PARALLEL_KILL_GRACE_SECONDS/' reconftw.cfg | grep -c '3600\|600'` returns >=2).
+ - Kill-latency note present in the new doc block: `awk '/^# Per-job timeout/,/^PARALLEL_KILL_GRACE_SECONDS/' /Users/six2dez/Tools/reconftw/reconftw.cfg | grep -c 'Actual kill latency is the threshold'` returns exactly 1.
+ - The kill-latency note mentions the heartbeat poll cadence and PARALLEL_KILL_GRACE_SECONDS: `awk '/^# Per-job timeout/,/^PARALLEL_KILL_GRACE_SECONDS/' /Users/six2dez/Tools/reconftw/reconftw.cfg | grep -cE 'heartbeat poll cadence.*PARALLEL_KILL_GRACE_SECONDS|PARALLEL_KILL_GRACE_SECONDS.*heartbeat poll cadence'` returns >=1.
+ - Ordering preserved: `awk '/^PARALLEL_TRACE_SLOW_SECONDS/{p=1; next} p && /^PARALLEL_JOB_TIMEOUT_SECONDS/{print "ok"; exit}' reconftw.cfg` prints `ok` (i.e., the new knob is placed AFTER PARALLEL_TRACE_SLOW_SECONDS and BEFORE the batch-sizing block).
+ - `bash -n reconftw.cfg` exits 0 (cfg is sourced as bash — must parse cleanly).
+ - `shellcheck -s bash --severity=error reconftw.cfg` exits 0 (no NEW error-level findings; pre-existing warnings allowed).
+ - Behavior smoke after sourcing cfg: `source reconftw.cfg && echo "$DNS_BRUTE_TIMEOUT $DNS_RESOLVE_TIMEOUT $PARALLEL_JOB_TIMEOUT_SECONDS $PARALLEL_KILL_GRACE_SECONDS"` prints `6h 4h 0 10`.
+ - Behavior smoke for DNS: a manual run with hung resolver simulation (`timeout 0.1s` wrapper) shows DNS functions complete with WARN badge and the JSONL log contains the existing `_run_dns_with_heartbeat` non-zero return path; no code change to the helper is required (D-17 verification).
+ </acceptance_criteria>
+ <done>
+ Four cfg lines changed: two DNS timeout defaults flipped to non-zero (6h/4h), two new parallel knobs added at the documented section anchor with mandatory doc comment listing 3600/600 examples AND a kill-latency note explaining the threshold + ~1s heartbeat + grace before SIGKILL; no CLI flag added; no unrelated lines touched; cfg parses cleanly via bash -n.
+ </done>
+</task>
+
+</tasks>
+
+<verification>
+- `bash -n lib/parallel.sh reconftw.cfg` → exit 0.
+- `shellcheck -s bash --severity=error lib/parallel.sh reconftw.cfg` → exit 0 (no NEW error-level findings vs baseline).
+- Manual smoke (no test files in this phase per CONTEXT Deferred):
+ 1. Source the project with new cfg: `./reconftw.sh --source-only`.
+ 2. Verify defaults: `echo "$DNS_BRUTE_TIMEOUT $DNS_RESOLVE_TIMEOUT $PARALLEL_JOB_TIMEOUT_SECONDS $PARALLEL_KILL_GRACE_SECONDS"` prints `6h 4h 0 10`.
+ 3. Timeout kill smoke: define a stub `function _slow_test() { start_func "${FUNCNAME[0]}" "test"; sleep 60; end_func "done" "${FUNCNAME[0]}"; }` in the sourced shell. Set `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`, then run `parallel_funcs 1 _slow_test`. Within ~5 seconds the job is killed; console shows `FAIL _slow_test Xs` + `reason: timeout`; `cat "$called_fn_dir/.status__slow_test"` shows `FAIL`; `cat "$called_fn_dir/.status_reason__slow_test"` shows `timeout`.
+ 4. Backwards-compat smoke: with `PARALLEL_JOB_TIMEOUT_SECONDS=0` (default), the same `_slow_test` runs to completion (or until the test shell is killed); no kill, no FAIL persistence.
+ 5. DNS timeout smoke: with `DNS_BRUTE_TIMEOUT=6h` exported, `_run_dns_with_heartbeat` invocations should pass `-k 10s 6h` to the timeout command. Verifiable by inspecting the wrapped command in a `set -x` trace; no behavioral change for healthy resolvers.
+</verification>
+
+<success_criteria>
+- Plan 01-03 success criteria (ROADMAP §"Phase 1" SC#3 + SC#4):
+ - Setting `PARALLEL_JOB_TIMEOUT_SECONDS=600` in reconftw.cfg terminates any single parallel_funcs child exceeding 10 minutes via kill -TERM, allowing the batch to continue.
+ - Fresh installs of reconftw.cfg ship with non-zero `DNS_BRUTE_TIMEOUT=6h` and `DNS_RESOLVE_TIMEOUT=4h` defaults, and a stuck DNS run aborts with a logged timeout rather than blocking indefinitely.
+- All `must_haves.truths` verifiable per the acceptance criteria above.
+- Default value `PARALLEL_JOB_TIMEOUT_SECONDS=0` (disabled) preserved per D-11 — backwards compatibility intact.
+- No CLI flag added — env-var/cfg override is the v1 contract.
+- Two-loop symmetry maintained: timeout check inserted in BOTH heartbeat loops (batch-flush and final-wait).
+- No code change to `_run_dns_with_heartbeat` in modules/utils.sh — only cfg defaults flip.
+- No new badge introduced; FAIL + reason=timeout reuses the existing status-persistence pipeline.
+- `_timeout_kill_job` declared with the project-wide `function name() {` form per CONVENTIONS.md §Function Naming; pre-existing sibling helpers using the bare form are flagged in-plan as a DOCS-01 / Phase 5 followup rather than a new-code precedent.
+- reconftw.cfg doc comment for PARALLEL_JOB_TIMEOUT_SECONDS explicitly states the effective kill latency (threshold + ~1s heartbeat poll cadence + PARALLEL_KILL_GRACE_SECONDS before SIGKILL) so CI users tuning the knob set realistic deadlines.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-resilient-resume-timeout-safety/01-03-SUMMARY.md`.
+</output>
+</content>
+</invoke>
\ No newline at end of file
diff --git a/.planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md b/.planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md
new file mode 100644
index 0000000..b29ce03
--- /dev/null
+++ b/.planning/phases/01-resilient-resume-timeout-safety/01-PATTERNS.md
@@ -0,0 +1,451 @@
+# Phase 1: Resilient Resume & Timeout Safety - Pattern Map
+
+**Mapped:** 2026-05-13
+**Files analyzed:** 5 (all existing, modified — no new files)
+**Analogs found:** 5 / 5
+
+## File Classification
+
+All Phase 1 files sit on the **function-lifecycle pipeline** (start_func → body → end_func) and the **parallel-batch pipeline** (`parallel_funcs` → background subshell → heartbeat → emit). No new files; every change extends an existing function or adds a sibling helper next to an existing analog.
+
+| Modified File | Role | Data Flow | Lifecycle Stage Touched | Match Quality |
+|---------------|------|-----------|-------------------------|---------------|
+| `modules/core.sh` | lifecycle wrapper | event-driven (per-function boundary) | `start_func` / `end_func` body, checkpoint touch, status persistence | exact (self-analog) |
+| `modules/modes.sh` | mode orchestration | request-response (workflow entry) | `start()` body, trap registration, banner emission, cleanup loop | exact (self-analog) |
+| `modules/utils.sh` | shared utility | request-response (single-call helper) | sibling to `check_disk_space()`; no change to `_run_dns_with_heartbeat` | exact (self-analog) |
+| `lib/parallel.sh` | parallel execution machinery | event-driven (poll loop) | batch-flush heartbeat loop body + final-wait heartbeat loop body + `_parallel_emit_job_output` reason path | exact (self-analog) |
+| `reconftw.cfg` | config (defaults) | static declaration | timeouts block (`:387-388`) and parallel block (near `PARALLEL_HEARTBEAT_SECONDS` at `:312`) | exact (self-analog) |
+
+**Note on classification:** Phase 1 is a brownfield extension — every new helper has a direct sibling in the same file with the same role and data flow. The "analog" for each is therefore the existing function it sits beside, and the patterns to copy are the surrounding idioms (badge vocabulary, `log_json` shape, `2>/dev/null || true` error suppression, subshell-not-pushd, `function name()` declaration style).
+
+---
+
+## Pattern Assignments
+
+### `modules/core.sh` — `start_func` / `end_func` lifecycle (Plan 01-01 / RESIL-01 sentinel; Plan 01-02 / RESIL-02 disk hook)
+
+**Role:** Lifecycle wrapper. **Data flow:** Event-driven (called at every function boundary; both before tool invocations and after checkpoint write).
+**Analog:** Itself — `start_func` at `:1419-1435` and `end_func` at `:1437-1529` are the canonical patterns the new sentinel ops must mirror.
+
+#### Existing `start_func` body (lines 1419-1435) — analog for sentinel-create + mid-run disk check
+
+```bash
+function start_func() {
+ local current_date
+ current_date=$(date +'%Y-%m-%d %H:%M:%S')
+ echo "[$current_date] Start function: ${1} " >>"${LOGFILE}"
+ # Use per-function start time to avoid race conditions in parallel mode
+ local _fn_name="${1}"
+ printf -v "_start_time_${_fn_name//[^a-zA-Z0-9_]/_}" '%s' "$(date +%s)"
+ # Keep global $start for backward compat (serial mode)
+ start=$(date +%s)
+ log_json "INFO" "${1}" "Function started" "description=${2}"
+ if declare -F ui_log_jsonl >/dev/null 2>&1; then
+ ui_log_jsonl "INFO" "${1}" "Function started" "description=${2}"
+ fi
+ if [[ "${OUTPUT_VERBOSITY:-1}" -ge 2 ]]; then
+ _print_msg "INFO" "Running ${1}..."
+ fi
+}
+```
+
+**Insertion anchor (D-01 sentinel + D-07 disk check):**
+- D-01 `.inprogress_<fn>` `touch` lands **after** the `printf -v "_start_time_..."` line (1425) and **before** the first `log_json` call (1428). The variable is already sanitized via `${_fn_name//[^a-zA-Z0-9_]/_}` — reuse the same `${1}` (raw function name) for the file name (per D-01: "plain empty `${called_fn_dir}/.inprogress_<fn>`"). Guard with `[[ -n "${called_fn_dir:-}" ]]` (same pattern as line 1505).
+- D-07 `_check_disk_mid_run` call lands at the **very top** of the function body, before the `current_date` line, so the abort fires before any state is written. Pattern: `_check_disk_mid_run || _abort_disk_full`.
+
+#### Existing `end_func` body (lines 1465-1510) — analog for sentinel-remove + checkpoint touch + status persistence
+
+```bash
+ touch "$called_fn_dir/.${fn}"
+ local end
+ end=$(date +%s)
+ # ... (timing computation) ...
+
+ # Persist per-function final status for parallel aggregator.
+ if [[ -n "${called_fn_dir:-}" ]]; then
+ printf "%s\n" "$badge" >"${called_fn_dir}/.status_${fn}" 2>/dev/null || true
+ if [[ -n "$reason_code" ]]; then
+ printf "%s\n" "$reason_code" >"${called_fn_dir}/.status_reason_${fn}" 2>/dev/null || true
+ fi
+ fi
+```
+
+**Insertion anchor (D-01 sentinel-remove + D-07 post-checkpoint disk check):**
+- D-01 `rm -f "$called_fn_dir/.inprogress_${fn}"` lands **immediately before** the existing `touch "$called_fn_dir/.${fn}"` at line 1465. Use the same `2>/dev/null || true` suppression idiom seen at lines 1506/1508. Sentinel removal **before** the checkpoint touch means a crash between these two ops still re-runs the function on next invocation (the `.<fn>` is the source of truth; the `.inprogress_<fn>` is purely a surface-level indicator).
+- D-07 `_check_disk_mid_run` call lands **after** the existing `printf` blocks at lines 1505-1509 and after the `_print_status` block at 1512-1524 — i.e. only after the checkpoint and status are durably written. This way, a disk-full abort detected at end_func still leaves a complete `.<fn>` + `.status_<fn>` pair on disk for the just-finished function.
+
+#### Status persistence pattern (lines 1505-1509) — analog for D-14 (timeout reason)
+
+The `.status_<fn>` / `.status_reason_<fn>` pair is **reused as-is** for D-14 timeout reporting (no schema extension). The parallel-batch path (`lib/parallel.sh`) writes these files when it kills a stuck job, and `_parallel_emit_job_output` reads them via the same `head -n 1 "$status_marker"` path already at `lib/parallel.sh:203-209` and `:224`.
+
+#### Conventions to preserve in `modules/core.sh`
+
+- **`function name()` declaration style** — new helpers (`_check_disk_mid_run`, `_abort_disk_full`) defined alongside `start_func`/`end_func` use `function _name() { ... }` form (consistent with `:1419`, `:1437`, and CONVENTIONS.md §Function Naming).
+- **`log_json` call shape** — `log_json "<LEVEL>" "${fn}" "<message>" "key=value" "key2=value2"` (see `:1428`, `:1525`). New entries:
+ - D-04 resume detection: `log_json "WARN" "resume" "Inprogress sentinels found" "reason=inprogress_leftover" "funcs=${joined}"`
+ - D-09 disk abort: `log_json "ERROR" "${fn:-main}" "Disk space exhausted" "reason=disk_full" "available_gb=${avail}" "required_gb=${req}"`
+ - D-17 DNS timeout (already emitted by `_run_dns_with_heartbeat`; only adds `reason=dns_hard_timeout` key).
+- **Underscore-prefix-private helpers** — `_check_disk_mid_run`, `_abort_disk_full`, `_cleanup_inprogress`, `_timeout_kill_job` (CONVENTIONS.md §Function Naming: "Private helpers: `_snake_case` prefix").
+- **Guard `called_fn_dir` references** — `if [[ -n "${called_fn_dir:-}" ]]; then` wrap (pattern at `:1505`) for any new write to that directory. Prevents accidental writes when invoked outside `start()` (e.g., `--source-only` in tests).
+- **`2>/dev/null || true`** for filesystem ops that must not abort lifecycle (pattern at `:1506`, `:1508`).
+
+---
+
+### `modules/modes.sh` — `start()` orchestration entry (Plan 01-01 trap + banner + PRESERVE loop)
+
+**Role:** Mode orchestration. **Data flow:** Request-response (single call per workflow entry; sets up traps and writes one-shot banner).
+**Analog:** Itself — `start()` at `:13-163` is where all initialization happens; the existing INT/TERM trap at `:118` and ERR trap at `:140` are the templates the new EXIT trap must compose with.
+
+#### Existing INT/TERM trap (line 118) — analog for D-02 EXIT trap composition
+
+```bash
+ # Trap for cleanup on unexpected exit
+ trap 'cleanup_on_exit' INT TERM
+```
+
+The handler `cleanup_on_exit` lives in `modules/utils.sh:116-146` and currently handles tmp-chunk cleanup, child-pid kill, interactsh kill, and final `exit "$exit_code"`. It is registered for INT and TERM only — **EXIT is unused today**.
+
+#### Existing ERR trap (line 140) — analog for trap composition
+
+```bash
+ # Non-fatal error trap: log and continue (plus short explanation for common cases)
+ trap 'rc=$?; ts=$(date +"%Y-%m-%d %H:%M:%S"); cmd=${BASH_COMMAND}; loc_fn=${FUNCNAME[0]:-main}; loc_ln=${BASH_LINENO[0]:-0}; msg="[$ts] ERR($rc) @ ${loc_fn}:${loc_ln} :: ${cmd}"; if [[ -n "${LOGFILE:-}" ]]; then echo "$msg" >>"$LOGFILE"; else echo "$msg" >&2; fi; explain_err "$rc" "$cmd" "$loc_fn" "$loc_ln"' ERR
+```
+
+The ERR trap is a one-liner with the full handler inlined — this is the project's idiom (avoids defining a separate function). The new EXIT trap may either:
+1. **Extend the existing INT/TERM trap** to also fire on EXIT: `trap 'cleanup_on_exit' EXIT INT TERM` — then add a `_cleanup_inprogress` call **at the top of** `cleanup_on_exit()` in `modules/utils.sh:116`. This is the simpler composition.
+2. **Register a separate EXIT-only trap** that calls only `_cleanup_inprogress`, leaving INT/TERM behavior unchanged. Use this if the planner wants to avoid touching `cleanup_on_exit` semantics (which currently `exit "$exit_code"` at the end — fine for EXIT since the shell is already exiting).
+
+**D-02 / D-05 / D-04 insertion anchors:**
+- **D-05 PRESERVE=false orphan cleanup** lands at lines `:78-80` inside the existing `FORCE_RESCAN` block:
+ ```bash
+ if [[ "${FORCE_RESCAN:-false}" == "true" ]]; then
+ rm -f "$called_fn_dir"/.* 2>>"${LOGFILE:-/dev/null}" || true
+ fi
+ ```
+ The existing `rm -f "$called_fn_dir"/.*` already globs both `.<fn>` and any `.inprogress_<fn>` — so the `FORCE_RESCAN` path requires **no change** if dot-glob expansion is set. To be explicit and defensive, add an additional `rm -f "$called_fn_dir"/.inprogress_*` line at the same indent. Note this is `FORCE_RESCAN` (CLI `--force`), not `PRESERVE=false`; D-05 says "`PRESERVE=false` (default) already clears `.<fn>` checkpoints" — locate that loop. (It is the `end()` cleanup at `modes.sh:352-355` for empty files, not a checkpoint wipe. The actual checkpoint clear for `PRESERVE=false` happens implicitly because the **next** run with `PRESERVE=false` creates a fresh `dir` only when `FORCE_RESCAN=true`; otherwise existing `.<fn>` files persist.) Planner should re-verify the exact location: the leftover-clear must run during `start()` setup, **before** any `start_func` call, to prevent the resume banner from firing on a `PRESERVE=false` re-run.
+- **D-04 resume banner** lands **after** the existing `_print_rule` / `ui_header` block (lines 142-152) and **before** `tools_installed` at line 160. Glob `$called_fn_dir/.inprogress_*`, count, list — emit one `_print_msg WARN` line (or a dedicated `_print_resume_banner` helper) and one `log_json WARN resume` line. Pattern at `:155`:
+ ```bash
+ if [[ "${FORCE_RESCAN:-false}" == "true" ]]; then
+ _print_msg WARN "Force rescan enabled: ignoring cached module markers"
+ fi
+ ```
+ Mirror this exactly for resume reporting. Detection logic must run **after** the FORCE_RESCAN block clears stale sentinels so a forced rescan never reports a resume.
+- **D-02 EXIT trap** lands **immediately after** the existing INT/TERM trap at line 118. Two acceptable composition styles per CLAUDE'S DISCRETION above; option 1 (extend `cleanup_on_exit`) is recommended for minimal trap-surface churn.
+
+#### Conventions to preserve in `modules/modes.sh`
+
+- **Trap one-liner idiom** — handlers either name a function (`cleanup_on_exit`) or inline the full body (ERR trap). New EXIT handler should be a named function (`_cleanup_inprogress`) defined in `modules/utils.sh` next to `cleanup_on_exit`.
+- **`_print_msg WARN "..."`** for banner-style notices (pattern at `:155`); always visible at `OUTPUT_VERBOSITY>=1`.
+- **`notification` vs `_print_msg`** — `notification` (`modules/core.sh:1302`) goes through verbosity-gating-plus-notify-fanout; `_print_msg` is direct console only. Resume banner should use `_print_msg WARN` (per D-04 it's local UI only, not a notification-channel event); JSONL log is emitted separately via `log_json`.
+- **No `pushd`/`popd`** — all CWD changes are direct `cd "$dir"` at `:82` (CONVENTIONS.md §Path and CWD).
+- **Subshell pattern** — if any new helper needs a transient CWD or env, wrap in `( cd "$x" && cmd )` not `pushd`/`popd`.
+
+---
+
+### `modules/utils.sh` — `check_disk_space` sibling helpers (Plan 01-02 / RESIL-02) and `_run_dns_with_heartbeat` (no-op for Plan 01-03 / PERF-02)
+
+**Role:** Shared utility. **Data flow:** Request-response (called once per function boundary; returns 0/1).
+**Analog:** `check_disk_space()` at `:421-436` (the canonical `df`-based check); `_run_dns_with_heartbeat()` at `:1434-1452` (the DNS timeout consumer that already respects `0=disabled`).
+
+#### Existing `check_disk_space` (lines 421-436) — analog for `_check_disk_mid_run`
+
+```bash
+# Check available disk space
+# Usage: check_disk_space <required_gb> <path>
+# Returns 0 if enough space, 1 otherwise
+function check_disk_space() {
+ local required_gb="$1"
+ local check_path="${2:-.}"
+
+ # Get available space in GB (portable across macOS/Linux).
+ local available_gb
+ available_gb=$(df -Pk "$check_path" 2>/dev/null | awk 'NR==2 {print int($4 / 1024 / 1024)}')
+
+ if [ -z "$available_gb" ] || [ "$available_gb" -lt "$required_gb" ]; then
+ DISK_SPACE_INFO="Disk space LOW: required ${required_gb}GB, available ${available_gb:-0}GB at ${check_path}"
+ return 1
+ fi
+
+ DISK_SPACE_INFO="Disk space OK: ${available_gb}GB available at ${check_path}"
+ return 0
+}
+```
+
+**Insertion anchor (D-07/D-08/D-09):** New helpers sit **immediately after** `check_disk_space` (after line 436). Two helpers:
+1. `_check_disk_mid_run` — thin wrapper that calls `check_disk_space "${MIN_DISK_SPACE_GB:-5}" "${dir:-.}"` (reuses D-08 single-threshold source-of-truth) and returns its exit code. **No re-implementation** of `df` parsing; the analog populates `DISK_SPACE_INFO` which the caller can read.
+2. `_abort_disk_full` — emits `_print_error "$DISK_SPACE_INFO"` (always visible per CONVENTIONS.md §Error Handling), calls `log_json "ERROR" "${fn:-main}" "Disk space exhausted" "reason=disk_full" "info=${DISK_SPACE_INFO}"`, then `exit 1` (D-09 hard abort). The Bash EXIT trap from D-02 fires on the way out and clears any `.inprogress_<fn>` so a subsequent invocation does NOT see a fake resume.
+
+#### Existing `_run_dns_with_heartbeat` (lines 1434-1452) — analog for D-16 (NO CODE CHANGE)
+
+```bash
+_run_dns_with_heartbeat() {
+ local label="$1"
+ local timeout_value="$2"
+ shift 2
+
+ local heartbeat_interval="${DNS_HEARTBEAT_INTERVAL_SECONDS:-20}"
+ [[ "$heartbeat_interval" =~ ^[0-9]+$ ]] || heartbeat_interval=20
+
+ if _dns_timeout_enabled "$timeout_value"; then
+ if [[ -n "${TIMEOUT_CMD:-}" ]]; then
+ run_with_heartbeat "$label" "$heartbeat_interval" "$TIMEOUT_CMD" -k 10s "$timeout_value" "$@"
+ else
+ warn_once "dns-timeout-command-missing" "DNS timeout requested but timeout command is unavailable; continuing without hard timeout."
+ run_with_heartbeat "$label" "$heartbeat_interval" "$@"
+ fi
+ else
+ run_with_heartbeat "$label" "$heartbeat_interval" "$@"
+ fi
+}
+```
+
+**No modification to this function.** D-16 only changes the two **default values** that this function reads from `reconftw.cfg`:
+- `DNS_BRUTE_TIMEOUT=0` → `DNS_BRUTE_TIMEOUT=6h`
+- `DNS_RESOLVE_TIMEOUT=0` → `DNS_RESOLVE_TIMEOUT=4h`
+
+The `_dns_timeout_enabled` guard already short-circuits `0` (disabled), and non-zero `h`-suffix values are passed verbatim to `timeout`/`gtimeout` which accept that form. D-17 surfacing is via the existing `WARN` badge from `end_func` (the consuming function returns non-zero on timeout); the planner only adds `reason=dns_hard_timeout` to the existing JSONL log entry (if not already present in the helper's WARN path).
+
+#### Conventions to preserve in `modules/utils.sh`
+
+- **`function name() { ... }`** declaration for `_check_disk_mid_run` / `_abort_disk_full` (consistent with `check_disk_space` at `:421`).
+- **Comment doc block** above each new helper (CONVENTIONS.md §Comments), mirroring the `# Check available disk space` block at `:418-420`.
+- **`DISK_SPACE_INFO` global** is reused — no new global. Caller pattern: `_check_disk_mid_run || _abort_disk_full`.
+- **`_print_error`** for the abort message (always-visible, `2>&1` to stderr). `log_json` for the structured event.
+- **`exit 1`** for the hard-abort path is the only acceptable `exit` site in this code (rest of the file uses `return` per the "no subshell isolation per module" constraint). The EXIT trap from D-02 fires regardless and cleans up.
+
+---
+
+### `lib/parallel.sh` — heartbeat-loop timeout enforcement (Plan 01-03 / RESIL-03)
+
+**Role:** Parallel execution machinery. **Data flow:** Event-driven (1Hz `sleep 1` poll inside `while :; do ... done` until all batch PIDs exit).
+**Analog:** The heartbeat loop appears **twice** in `parallel_funcs` — once at lines 432-465 (batch-flush phase, when an in-progress batch fills to `max_jobs`) and once at lines 537-569 (final-wait phase, for the trailing partial batch). Both loops have identical structure; the timeout kill logic must be inserted in **both**.
+
+#### Existing batch-flush heartbeat loop (lines 432-465) — primary analog
+
+```bash
+# 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
+ 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]))
+ 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 ((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
+```
+
+**Insertion anchor (D-11/D-12/D-13/D-14):** Inside the `if kill -0 "${batch_pids[$idx]}" 2>/dev/null; then` branch (line 443), **after** the `job_dur=$((now - batch_starts[$idx]))` line (445). The `job_dur` is already computed — reuse it. Pseudocode for the new block:
+
+```bash
+# Timeout enforcement (D-11..D-14): if PARALLEL_JOB_TIMEOUT_SECONDS > 0 and
+# job_dur > threshold, kill the job and persist FAIL status with reason=timeout.
+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
+```
+
+`_timeout_kill_job` is a new private helper defined **above** `parallel_funcs` in `lib/parallel.sh` (near `_throttle_jobs` at `:33` and `_parallel_emit_job_output` at `:172`). It performs:
+1. `kill -TERM "$pid" 2>/dev/null || true`
+2. Poll loop: `for ((i=0; i<${PARALLEL_KILL_GRACE_SECONDS:-10}; i++)); do kill -0 "$pid" 2>/dev/null || break; sleep 1; done`
+3. `kill -KILL "$pid" 2>/dev/null || true` if still alive
+4. **Persist FAIL + reason=timeout** to the same files `end_func` uses (`called_fn_dir/.status_<fn>` and `.status_reason_<fn>`), so `_parallel_emit_job_output` picks them up via the existing read path at `:203-209` / `:223-224`:
+ ```bash
+ if [[ -n "${called_fn_dir:-}" ]]; then
+ printf "FAIL\n" >"${called_fn_dir}/.status_${func_name}" 2>/dev/null || true
+ printf "timeout\n" >"${called_fn_dir}/.status_reason_${func_name}" 2>/dev/null || true
+ fi
+ ```
+5. `log_json "ERROR" "${func_name}" "Job timed out" "reason=timeout" "duration_sec=${job_dur}"`
+
+The post-loop `wait "${batch_pids[$idx]}"` at line 470 then collects the killed process's non-zero rc, and `_parallel_emit_job_output` at line 483 reads the `FAIL` + `timeout` from the status files and emits the console badge per the existing reason-rendering code path (`:261-263`, `:279-281`).
+
+#### Existing final-wait heartbeat loop (lines 537-569) — identical analog, second insertion site
+
+Structure is identical to the batch-flush loop above (lines 432-465). Same insertion: at line ~549 inside the `kill -0` branch, after the `job_dur=$((now - batch_starts[$idx]))` line.
+
+#### Existing `_parallel_emit_job_output` (lines 172-300) — reason-rendering path is reused (D-14)
+
+The function already reads `.status_<fn>` (`:204`) and `.status_reason_<fn>` (`:224`) and renders the reason via:
+```bash
+if [[ -n "$reason_code" ]] && { [[ "$badge" == "SKIP" ]] || { [[ "$badge" == "CACHE" ]] && [[ "${SHOW_CACHE:-false}" == "true" ]]; }; }; then
+ printf " reason: %s\n" "$reason_code"
+fi
+```
+
+**This conditional currently renders reason only for SKIP/CACHE.** To surface `reason=timeout` for `FAIL` badges per D-14 ("Console badge: `FAIL func_name 600s (timeout)`"), extend the condition (in all three mode branches: `summary`, `tail`, `full`) to **also** print reason when `badge == "FAIL"`. The line-pattern stays the same — only the gate widens. Alternatively, render the reason inline on the badge line itself (right-side parenthetical, matching the FAIL example in CONVENTIONS.md §Output: `FAIL sub_dns 7s (see debug.log)`).
+
+#### Conventions to preserve in `lib/parallel.sh`
+
+- **Source-guard pattern at top of file** — `[[ -n "$_PARALLEL_SH_LOADED" ]] && return 0` at `:6` is preserved (no changes to the guard).
+- **`PARALLEL_*` variable naming** — new knobs follow the convention: `PARALLEL_JOB_TIMEOUT_SECONDS`, `PARALLEL_KILL_GRACE_SECONDS` (UPPER_SNAKE_CASE, prefix-aligned with `PARALLEL_HEARTBEAT_SECONDS` at `:15`).
+- **Default-via-parameter-expansion** — `local _to="${PARALLEL_JOB_TIMEOUT_SECONDS:-0}"` mirrors the existing `local hb="${PARALLEL_HEARTBEAT_SECONDS:-20}"` at `:433`. The integer-regex guard `[[ "$hb" =~ ^[0-9]+$ ]] && ((hb > 0))` at `:434` is the canonical "var must be a positive int" check — reuse it for `_to`.
+- **Helper-name convention** — `_timeout_kill_job` is `_snake_case` private prefix, matching `_throttle_jobs`, `_parallel_live_break`, `_parallel_emit_job_output`, `_parallel_snapshot`.
+- **`2>/dev/null || true`** for all `kill` calls (the target PID may have already exited between the check and the action). Already idiomatic — see `:443`, `:547`.
+- **Two-loop symmetry** — any block added inside the batch-flush loop **must** be added to the final-wait loop. The two loops are structurally identical and the audit history (CONCERNS.md §parallel_funcs Batch Flushing) treats them as one logical pattern.
+- **D-15 axiom uniformity** — the timeout kill operates on the local subshell PID; axiom-distributed jobs run inside that subshell as `axiom-scan` invocations, so killing the subshell signals `axiom-scan` which in turn signals remote nodes. No special-casing needed at the parallel layer.
+
+---
+
+### `reconftw.cfg` — DNS timeouts and new parallel knobs (Plan 01-03 / PERF-02 + RESIL-03)
+
+**Role:** Configuration defaults. **Data flow:** Static declaration sourced once at startup.
+**Analog:** Itself — `DNS_BRUTE_TIMEOUT` / `DNS_RESOLVE_TIMEOUT` at `:387-388` (the values that change) and `PARALLEL_HEARTBEAT_SECONDS` region (the new knobs are grouped beside it).
+
+#### Existing DNS timeouts block (lines 387-389) — D-16 modification site
+
+```bash
+PERMUTATIONS_LIMIT=2147483648 # Bytes, default is 2 GB (prevents accidental disk exhaustion)
+DNS_BRUTE_TIMEOUT=0 # timeout/gtimeout duration for DNS bruteforce (0 disables hard-timeout, e.g. 4h)
+DNS_RESOLVE_TIMEOUT=0 # timeout/gtimeout duration for DNS resolve (0 disables hard-timeout, e.g. 6h)
+DNS_HEARTBEAT_INTERVAL_SECONDS=20 # Progress heartbeat interval for long DNS jobs
+```
+
+**Modification (D-16):** Change the two default values in place. Note the existing comment example values (`e.g. 4h`, `e.g. 6h`) are **inverted** vs. CONTEXT.md D-16 (`DNS_BRUTE_TIMEOUT=6h`, `DNS_RESOLVE_TIMEOUT=4h`) — verify and align with CONTEXT.md authoritative values. Updated lines:
+
+```bash
+DNS_BRUTE_TIMEOUT=6h # timeout/gtimeout duration for DNS bruteforce (0 disables hard-timeout)
+DNS_RESOLVE_TIMEOUT=4h # timeout/gtimeout duration for DNS resolve (0 disables hard-timeout)
+```
+
+Inline doc comment **must mention** that the non-zero default protects against hung resolvers (D-17 rationale).
+
+#### Existing parallel knobs block (lines 302-312) — D-11/D-13 new-knob insertion site
+
+```bash
+# Parallelization
+PARALLEL_MODE=true # Run independent functions in parallel (faster, uses more resources). Disable with --no-parallel or set false.
+PERF_PROFILE="balanced" # Performance profile: low|balanced|max
+CONTINUE_ON_TOOL_ERROR=true # Continue recon when a tool/module fails in parallel batches (set false for fail-fast).
+PARALLEL_LOG_MODE="summary" # Parallel output mode: summary (compact) | tail (last N lines) | full (cat all)
+PARALLEL_TAIL_LINES=20 # Number of tail lines shown per job in 'tail' mode (doubled on failure)
+PARALLEL_UI_MODE="clean" # Parallel terminal UX: clean | balanced | trace
+PARALLEL_PROGRESS_SHOW_ETA=true # Show ETA in live progress once estimate is stable
+PARALLEL_PROGRESS_SHOW_ACTIVE=true # Show active tasks list in live parallel progress
+PARALLEL_PROGRESS_COMPACT_ACTIVE_MAX=4 # Max active/done items shown before compacting with "+N more"
+PARALLEL_TRACE_SLOW_SECONDS=30 # In balanced mode, show finished-line for jobs slower than this threshold
+```
+
+Note: `PARALLEL_HEARTBEAT_SECONDS` is defaulted only in `lib/parallel.sh:15` (not surfaced in `reconftw.cfg` today — that's a DOCS-01/Phase-5 concern). Per CONTEXT.md Integration Points: "parallel knobs should sit near `PARALLEL_HEARTBEAT_SECONDS` documentation" — interpret as: group the new knobs in this `# Parallelization` block, beside the existing `PARALLEL_*` declarations. Suggested insertion immediately after `PARALLEL_TRACE_SLOW_SECONDS` (line 312):
+
+```bash
+# Per-job timeout (D-11..D-14). Default 0 = disabled; suggested values:
+# 3600 (1h) for long unattended scans, 600 (10min) for CI smoke runs.
+# When set > 0, parallel_funcs heartbeat sends SIGTERM after the threshold
+# and SIGKILL after PARALLEL_KILL_GRACE_SECONDS if the job ignores TERM.
+PARALLEL_JOB_TIMEOUT_SECONDS=0
+PARALLEL_KILL_GRACE_SECONDS=10 # Seconds between TERM and KILL when enforcing PARALLEL_JOB_TIMEOUT_SECONDS
+```
+
+#### Conventions to preserve in `reconftw.cfg`
+
+- **Inline `#` comments** on every variable line — comment style is end-of-line (`VAR=value # doc`), not above-line. See every entry in this file.
+- **Group by section header** — `# Parallelization`, `# Timeouts`, etc. New knobs go in the existing section that owns them.
+- **No CLI flag for v1** — per CONTEXT.md §Established Patterns: "any new config knob (`PARALLEL_KILL_GRACE_SECONDS`) added in this phase does NOT need a CLI flag for v1". Skip the `CLI_*` re-apply pattern in `reconftw.sh`.
+- **Suggested-values in doc comment** — per CONTEXT.md D-11: "doc comment in `reconftw.cfg` should list the recommended values explicitly (3600 for long scans, 600 for CI) but ship disabled". The multi-line `# Per-job timeout...` block above embeds those examples.
+- **`0` as universal "disabled" sentinel** — matches existing convention (`DNS_BRUTE_TIMEOUT=0`, `WAF_PER_HOST_TIMEOUT=0`, `FFUF_RATELIMIT=0`).
+
+---
+
+## Shared Patterns
+
+### Status badge vocabulary (locked)
+
+**Source:** `lib/common.sh:467` (`_print_status`), `modules/core.sh:1485-1488` (`end_func` badge mapping), `lib/parallel.sh:203-227` (`_parallel_emit_job_output` badge resolution).
+**Apply to:** All Phase 1 changes. **No new badge values introduced.**
+
+| Concern | Badge | Reason key |
+|---------|-------|------------|
+| D-04 resume detection | `WARN` | `inprogress_leftover` |
+| D-09 disk full abort | `FAIL` (via `_print_error`, not via `end_func`) | `disk_full` |
+| D-14 timeout kill | `FAIL` | `timeout` |
+| D-17 DNS hard timeout | `WARN` (from existing `end_func` path) | `dns_hard_timeout` |
+
+### `log_json` event shape (locked)
+
+**Source:** `modules/core.sh:680-709`. **Apply to:** All new structured-log events in this phase.
+
+Canonical call:
+```bash
+log_json "<LEVEL>" "<function_name>" "<human_message>" "key1=value1" "key2=value2"
+```
+
+- Level: `INFO|WARN|ERROR|SUCCESS` (`modules/core.sh:712-725`).
+- Function name: `${FUNCNAME[0]}` or `${FUNCNAME[1]:-main}` (mirror surrounding code).
+- Always include a `reason=<snake_case>` key for non-INFO events (matches `.status_reason_<fn>` value convention).
+- Body is no-op when `STRUCTURED_LOGGING != true` — safe to call unconditionally.
+
+### Underscore-prefix-private helpers (locked)
+
+**Source:** CONVENTIONS.md §Function Naming. **Apply to:** All new helpers in this phase.
+
+| New helper | File | Sibling analog |
+|------------|------|----------------|
+| `_check_disk_mid_run` | `modules/utils.sh` | `check_disk_space` (`:421`) |
+| `_abort_disk_full` | `modules/utils.sh` | (new, no analog; sits with `_check_disk_mid_run`) |
+| `_cleanup_inprogress` | `modules/utils.sh` | `cleanup_on_exit` (`:116`) |
+| `_timeout_kill_job` | `lib/parallel.sh` | `_throttle_jobs` (`:33`), `_parallel_emit_job_output` (`:172`) |
+| `_print_resume_banner` *(optional)* | `lib/common.sh` or inline in `modules/modes.sh` | `_print_msg` / `_print_rule` |
+
+### Subshell-not-pushd (locked)
+
+**Source:** CONVENTIONS.md §Path and CWD. **Apply to:** Any new helper that needs a transient working directory.
+
+```bash
+# Correct:
+( cd "${dir}" && _check_disk_mid_run )
+
+# Forbidden:
+pushd "${dir}"; _check_disk_mid_run; popd
+```
+
+(None of Phase 1's new helpers actually need a CWD change — `_check_disk_mid_run` calls `check_disk_space "$req" "${dir:-.}"` and the analog already accepts an explicit path argument. The subshell rule is enforced as a defensive guideline only.)
+
+### `2>/dev/null || true` for filesystem fire-and-forget (locked)
+
+**Source:** `modules/core.sh:1506` / `:1508`, `lib/parallel.sh:198` / `:202` / `:209`, `modules/utils.sh:32` (typical patterns). **Apply to:** All sentinel-create, sentinel-remove, kill, and status-write operations added in this phase. These ops must never abort the lifecycle even if they fail (e.g., the directory was already removed by a concurrent cleanup).
+
+---
+
+## No Analog Found
+
+No files fall into this category. Every Phase 1 change has a direct sibling in the existing codebase.
+
+---
+
+## Metadata
+
+**Analog search scope:** `modules/core.sh`, `modules/modes.sh`, `modules/utils.sh`, `lib/parallel.sh`, `lib/common.sh`, `reconftw.cfg`.
+**Files scanned:** 6 (the 5 modified + `lib/common.sh` for `_print_*` helper sites).
+**Key line ranges read:** `modules/core.sh:1410-1530, 675-727`; `modules/modes.sh:1-163, 285-300, 340-360, 780-800, 1240-1260`; `modules/utils.sh:108-170, 410-440, 1420-1500`; `lib/parallel.sh:1-50, 165-300, 390-620`; `reconftw.cfg:1-50, 300-400`.
+**Pattern extraction date:** 2026-05-13.
+
+## PATTERN MAPPING COMPLETE
+
+Five existing files mapped to in-place insertion points with named sibling analogs, exact line anchors (`core.sh:1419/1437/1465/1505`, `modes.sh:13/78/118/140/152`, `utils.sh:421/1434`, `parallel.sh:172/432/537`, `reconftw.cfg:312/387`), and shared conventions (badge vocabulary, `log_json` shape, underscore-private helpers, subshell-not-pushd, `2>/dev/null || true`) — all driven by the existing reconFTW idioms with zero new badge values, no PID/timestamp staleness metadata, and no CLI flag additions.