Item 25: distinct 'exhausted' outcome for :dll_bundle_recover

[mixmansoundude]

Summary

CodeRabbit review finding on PR #414 (Item 24), deliberately deferred as its own follow-up loop (CLAUDE.md Active Backlog Item 25) rather than folded into that already-large PR.

:dll_bundle_loop found the next DLL candidate (HP_NEXT_DLL) before checking whether the 3-iteration cap had already been hit. When a real, locatable DLL candidate turned up on the 4th (or later) scan, that information was silently discarded -- the loop just jumped to :dll_bundle_recover_done, where HP_DLL_ITER GEQ 1 read true (3 DLLs had genuinely been bundled in earlier iterations), so it logged [REPAIR][DLL_BUNDLE] Native-DLL bundling complete and emitted the repaired NDJSON state -- indistinguishable from a clean, fully-resolved run, even though a real dependency was left unbundled.

Changes

• run_setup.bat: new HP_DLL_EXHAUSTED flag, set in :dll_bundle_loop's cap-check branch (reaching that branch at all already implies a real candidate was found, since the empty case returns earlier). :dll_bundle_recover_done now checks this flag before the repaired branch, logging a new [WARN][DLL_BUNDLE] line and emitting a new exhausted NDJSON state instead. Reset alongside HP_DLL_FAILED at both the top-of-loop reset and :dll_bundle_recover_exit, so a stale exhausted outcome can't leak across a REQ-009 provider cascade re-entry.
• tests/harness.ps1: batch.dll_bundle.ndjson extended with the new exhausted state token and 7th call site -- the same "static wiring guard, not runtime execution" coverage already accepted for this subroutine's other low-trigger-rate states (needs 4+ conda-forge packages under one PyInstaller build each separately needing --add-binary, never observed for a real package in this repo's testing).
• docs/agent-ndjson.md / docs/agent-interconnect.md: updated with the new state and full mechanism trace.
• CLAUDE.md: Item 25 moved to docs/agent-closed-backlog.md.

Test plan

• tools/run_sanity_sweep.sh -- all clean, 515 passed / 3 skipped.
• python tools/check_delimiters.py run_setup.bat -- clean.
• PowerShell AST parse sweep on tests/harness.ps1 -- clean.

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • DLL bundling now reports an exhausted outcome when unresolved candidates remain after the recovery limit, instead of incorrectly indicating success.
  • Added warning and machine-readable reporting for exhausted recovery attempts.
  • Recovery state is properly reset during cleanup and repeated runs.

• Documentation

  • Updated recovery and telemetry documentation to describe the new outcome and reporting behavior.

Walkthrough

The DLL recovery loop now reports exhausted when unresolved DLL candidates remain after three recovery attempts. The state resets during cleanup, emits NDJSON telemetry, remains passing, and is covered by updated documentation and harness checks.

Changes

DLL recovery exhaustion

Layer / File(s)	Summary
Track capped recovery state run_setup.bat	The recovery loop tracks HP_DLL_EXHAUSTED, reports unresolved candidates as exhausted, and resets the state during cleanup.
Document exhausted telemetry docs/agent-interconnect.md, docs/agent-ndjson.md, docs/agent-closed-backlog.md	The documentation defines the exhausted NDJSON outcome and updates emission coverage from six to seven sites.
Validate recovery wiring tests/harness.ps1	The harness checks the exhausted outcome, its emission call, and the seven-site coverage requirement.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• mixmansoundude/Python_vs_Windows#414: Introduced the DLL-bundling recovery loop extended by this change.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: adding a distinct exhausted outcome for dll_bundle_recover.
Description check	✅ Passed	The description directly explains the DLL bundling issue, implementation changes, documentation updates, and validation results.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/bootstrapper-execution-branches-ox2izi

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/harness.ps1`:
- Around line 473-487: Add executable CI coverage for the exhausted recovery
outcome, using a deterministic HP_* hook or scan fixture to drive a fourth
locatable candidate through the recovery loop. Assert the warning, exactly one
self.dll_bundle.recover NDJSON record with state=exhausted and pass=true,
absence of a repaired record, and the expected reset behavior. Integrate this as
a dedicated test lane or flag in the existing harness rather than relying only
on run_setup.bat text scanning.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 478596dc-2bad-4112-823a-0c58fe5da50e

📥 Commits

Reviewing files that changed from the base of the PR and between 0858fc8 and e26f589.

📒 Files selected for processing (6)

• CLAUDE.md
• docs/agent-closed-backlog.md
• docs/agent-interconnect.md
• docs/agent-ndjson.md
• run_setup.bat
• tests/harness.ps1

💤 Files with no reviewable changes (1)

• CLAUDE.md

📜 Review details

⏰ Context from checks skipped due to timeout. (9)

• GitHub Check: auto_merge
• GitHub Check: Batch syntax/run check (justme-test)
• GitHub Check: Batch syntax/run check (contract-uv-fail)
• GitHub Check: Batch syntax/run check (uv)
• GitHub Check: Batch syntax/run check (conda-full)
• GitHub Check: Batch syntax/run check (real)
• GitHub Check: Batch syntax/run check (contract-uv)
• GitHub Check: Batch syntax/run check (uv-dl-fallback)
• GitHub Check: Batch syntax/run check (cache)

🧰 Additional context used

📓 Path-based instructions (12)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

The single-bootstrapper directive requires run_setup.bat to work when dropped next to the application without committed helper files; test-only helpers may live under tests/ but cannot be required by the real flow.

Freeze scope for the current iteration loop; defer new requirements to the backlog, implement exactly one missing feature slice, and add exactly one missing test per loop.

Files:

• tests/harness.ps1
• docs/agent-closed-backlog.md
• docs/agent-ndjson.md
• run_setup.bat
• docs/agent-interconnect.md

**/*.{ps1,psm1,psd1}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ps1,psm1,psd1}: Prepend TLS 1.2 configuration to every PowerShell 5.1 Invoke-WebRequest call and retain -UseBasicParsing.
Validate touched PowerShell files with PowerShell AST parsing; do not skip validation on Linux, and run modified scripts directly with realistic environment variables when practical.

Files:

• tests/harness.ps1

**/*.{bat,cmd,ps1,py,yml,yaml,json}

📄 CodeRabbit inference engine (AGENTS.md)

Run delimiter and repository-specific syntax regression checks using tools/check_delimiters.py, respecting comments, escapes, and here-strings as applicable.

Files:

• tests/harness.ps1
• run_setup.bat

**/*.{py,ps1,psm1,psd1,yml,yaml,json,bat,cmd}

📄 CodeRabbit inference engine (AGENTS.md)

Keep source text ASCII plain text and avoid non-ASCII punctuation.

Files:

• tests/harness.ps1
• run_setup.bat

**/*.{bat,ps1}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{bat,ps1}: Use CRLF line endings for .bat and .ps1 files; do not manually override the repository's .gitattributes behavior.
Keep batch and PowerShell source ASCII-only; avoid emojis, curly quotes, em-dashes, and other non-ASCII characters.

Files:

• tests/harness.ps1
• run_setup.bat

tests/**/*.ps1

📄 CodeRabbit inference engine (CLAUDE.md)

Validate PowerShell syntax without downloading from PSGallery; use parser-based or syntax-only checks in CI.

Files:

• tests/harness.ps1

**/*.{bat,ps1,py,yml,json}

📄 CodeRabbit inference engine (CLAUDE.md)

Run the repository's full sanity sweep before every commit, extending the ASCII file list to include all files touched by the change.

Files:

• tests/harness.ps1
• run_setup.bat

**/*.{md,txt}

📄 CodeRabbit inference engine (AGENTS.md)

When documenting run_setup.bat, cite labels or subroutine names rather than exact line numbers unless a line number provides immediate value for the introducing commit.

Files:

• docs/agent-closed-backlog.md
• docs/agent-ndjson.md
• docs/agent-interconnect.md

docs/agent-ndjson.md

📄 CodeRabbit inference engine (CLAUDE.md)

Update the NDJSON row registry in the same commit when rows are added, renamed, or removed.

Files:

• docs/agent-ndjson.md

run_setup.bat

📄 CodeRabbit inference engine (AGENTS.md)

run_setup.bat: Every branch added to run_setup.bat or related helpers must have a CI test, including feature flags, fallback and recovery paths, and fast versus full paths; add an NDJSON assertion and a dedicated lane or HP_* flag when necessary.
All embedded helpers must remain base64 payloads under :define_helper_payloads; changing a payload requires updating the matching HP_* line from its canonical tools/ source.
Do not remove tilde prefixes from runtime artifact files such as ~bootstrap.status.json, ~setup.log, ~environment.lock.txt, and ~env.state.json.
Treat unknown ~env.state.json schemas as stale and trigger a full rebuild rather than reporting an error.
Update [VERSION_METADATA] after CI verifies a newer Windows, PowerShell, or Python environment, including the verification date and current versions.

run_setup.bat: Keep run_setup.bat self-contained: do not commit helper files; embed helpers as base64 payloads under :define_helper_payloads, and refresh them only with python tools/sync_payload.py.
Run python tools/check_delimiters.py run_setup.bat after every edit to run_setup.bat.
Pass --override-channels -c conda-forge on every conda installation or invocation that resolves packages.
Use call "%CONDA_BAT%" ... for all conda invocations so the parent batch process continues running.
Avoid EnableDelayedExpansion; if it is necessary, scope it tightly.
Use tilde-prefixed temporary files such as ~setup.log and ~bootstrap.status.json so they remain easy to ignore and survive crashes.
Every run must write ~bootstrap.status.json with the contract {"state":"ok|no_python_files|error","exitCode":0,"pyFiles":0}.
Bootstrap execution must be deterministic: do not depend on console scripts, PATH, activation state, or shell state; anchor tool invocations to an explicit interpreter such as %HP_PY% or %CONDA_PREFIX%\python.exe.
Keep pipreqs pinned to 0.4.13; do not upgrade it to 0.5.0, and invoke it as `python -m ...

Files:

• run_setup.bat

**/*.{bat,cmd}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{bat,cmd}: For batch assignments use set "VAR=value", never set VAR="value"; quote %VAR% at every filesystem call site, except NSIS /D= parameters, which must remain /D=%VAR%.
Before system-wide installation, silently check elevation with fsutil dirty query %systemdrive% >nul 2>&1; on failure, skip the system-wide path and fall back to per-user installation.
Avoid EnableDelayedExpansion unless it is strictly scoped, and disable it afterward; use careful quoting and escaping rather than silencing errors.
Use tools/sync_payload.py as the only sanctioned method for re-encoding embedded HP_* payload lines after editing canonical helper sources; run delimiter checks after payload changes.

Files:

• run_setup.bat

docs/agent-interconnect.md

📄 CodeRabbit inference engine (CLAUDE.md)

Update cross-component dependency lessons in the same commit when a change teaches or invalidates one.

Files:

• docs/agent-interconnect.md

🧠 Learnings (1)

📚 Learning: 2026-08-01T02:27:53.952Z

Learnt from: mixmansoundude
Repo: mixmansoundude/Python_vs_Windows PR: 408
File: docs/agent-closed-backlog.md:0-0
Timestamp: 2026-08-01T02:27:53.952Z
Learning: In the documentation files describing the removed UNC warning check in `run_setup.bat`, state only verified behavior: the check emitted `[WARN] UNC paths not supported` for an ordinary local path and was removed because the separate UNC-prefix guard already handles UNC detection. Do not assert the exact `findstr` or cmd.exe backslash-parsing mechanism, since it was not independently verified.

Applied to files:

• docs/agent-closed-backlog.md

🪛 PSScriptAnalyzer (1.25.0)

tests/harness.ps1

[info] 487-487: Cmdlet 'Write-Result' has positional parameter. Please use named parameters instead of positional parameters when calling a command.

(PSAvoidUsingPositionalParameters)

🔇 Additional comments (4)

run_setup.bat (1)

4023-4023: LGTM!

Also applies to: 4058-4065, 4133-4137, 4149-4149

docs/agent-interconnect.md (1)

355-367: LGTM!

Also applies to: 369-409

docs/agent-ndjson.md (1)

230-244: LGTM!

Also applies to: 266-273

docs/agent-closed-backlog.md (1)

1528-1564: LGTM!