docs/fix: follow-up CodeRabbit fixes from PR #404 (item-7 wording, AllUsers exit code, audit tool hardening)

[mixmansoundude]

Summary

PR #404 merged before these two follow-up commits (already reviewed and confirmed-addressed by
CodeRabbit on that PR) could be pushed, per this session's "one fix per CI run, don't push while
CI is in progress" constraint. Rebased cleanly onto the new main (#404's squash-merge tip) with
no conflicts; this PR carries only that leftover, already-reviewed work.

run_setup.bat / demo doc: :tci_justme's genuine-AllUsers-failure WARN line now captures
and logs the installer's real exit code (HP_CONDA_ALLUSERS_RC) and a reason=installer_failed
token instead of a bare "failed" message, per this repo's own convention that external/
environmental failures must be explicit in logs. Demo doc and docs/agent-closed-backlog.md
updated to match.

tests/selfapps_justme.ps1: the new skip/failed-wording assertions now check
$setupText (the envsmoke-scoped log) instead of $combinedText, since a negative
("must NOT appear") assertion is vulnerable to unrelated stale content in the shared
repo-root ~setup.log that the positive assertions aren't.

tools/audit_console_messages.py: normalize() now handles %%M/%%~zS-style for-loop
variables and %~dp0/%~1/bare %1-%9 positional params (previously only %VAR% was
handled), and the %VAR% pattern requires no internal whitespace so an isolated literal %
can't be greedily paired with a later real %VAR%. extract_records now strips a leading @,
lowercases control tokens before comparing, matches call :log case-insensitively, and skips
redirected call :log ... >> lines too. main() uses is_file() instead of exists() and
wraps the file reads in try/except OSError. Added tests/test_audit_console_messages.py
(12 cases) covering all of the above.

.github/workflows/batch-check.yml / CLAUDE.md: reworded the three stale
"Active Backlog item 7" comments to "closed Item 7" (item 7 has been closed since 2026-07-27).
Added an explicit exception clause to CLAUDE.md's Active Backlog numbering policy documenting
that a collision with an already-retired number requires renumbering to the next unused number
when archiving, citing the 11→16 / 9→17 precedent from #404 by name.

Two CodeRabbit findings on the originating review round were investigated and declined, with
reasoning posted on the original PR: adding NDJSON telemetry for the AllUsers fallback (new
feature scope beyond this fix; already covered by existing conda.install.justme/
self.conda.bothfail rows), and wiring tools/audit_console_messages.py into CI (deliberately
a hand-run, human-in-the-loop tool, matching the tools/audit_batch_exit_paths.py precedent).
A third claim (an actionlint failure on a pre-existing, deliberately-commented if: false
toggle) was verified false against actionlint v1.7.1 both on the real file and an isolated
repro, and was withdrawn by CodeRabbit after the reply.

Test plan

• python -m compileall -q . / pyflakes -- clean
• python tools/check_delimiters.py run_setup.bat -- clean
• ASCII sweep, yamllint, actionlint -- all clean
• pwsh AST parse sweep over all .ps1 files -- clean
• python -m pytest tests/test_*.py -q -- 449 passed, 2 skipped
• git diff --stat against current origin/main reviewed for scope (9 files, matches the
  two carried-over commits exactly)

---

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

  • Improved Miniconda installation handling to distinguish skipped elevated installation attempts from genuine installer failures.
  • Failure messages now include clearer reasons and installer exit codes, with more accurate fallback and final-error reporting.
  • Improved console-log auditing for batch syntax, case variations, redirected lines, and literal percent text.
  • Invalid or inaccessible audit inputs now produce clear errors and an appropriate failure status.

• Documentation

  • Updated installation guidance and backlog references to reflect the revised behavior and numbering rules.

• Tests

  • Added regression coverage for installation messaging and console-audit scenarios.

Walkthrough

The bootstrapper now distinguishes skipped AllUsers installation from genuine installer failure. The console audit tool handles additional batch syntax and invalid inputs. Documentation, workflow references, and regression tests reflect the updated behavior and backlog rules.

Changes

Miniconda installation messaging

Layer / File(s)	Summary
AllUsers result handling run_setup.bat	The batch flow captures the AllUsers installer exit code and reports separate fallback and terminal messages for failure and non-elevated skips.
Installer output validation docs/agent-closed-backlog.md, docs/demo-bootstrapper-output.md, tests/selfapps_conda_bothfail.ps1, tests/selfapps_justme.ps1	Documentation and PowerShell tests validate the new exit-code, skip, and JustMe failure wording.

Console message audit

Layer / File(s)	Summary
Batch normalization and extraction tools/audit_console_messages.py, tests/test_audit_console_messages.py	The audit handles positional parameters, loop variables, literal percent text, case-insensitive log calls, control tokens, and redirected lines.
Coverage and CLI validation tools/audit_console_messages.py, tests/test_audit_console_messages.py	The CLI validates file inputs, reports read errors with status 2, and tests coverage detection and invalid paths.

Backlog archival references

Layer / File(s)	Summary
Archived Item 7 references and numbering rules .github/workflows/batch-check.yml, CLAUDE.md, docs/demo-bootstrapper-output.md	References now use the closed Item 7 entry. Active Backlog guidance documents permanent-number collision handling.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant run_setup.bat
  participant AllUsersInstaller
  participant JustMeInstaller
  run_setup.bat->>AllUsersInstaller: Run installer and capture exit code
  AllUsersInstaller-->>run_setup.bat: Return exit code
  run_setup.bat->>JustMeInstaller: Fall back after failure or skip
  JustMeInstaller-->>run_setup.bat: Return installation result
  run_setup.bat-->>run_setup.bat: Report the final installation status

Loading

Possibly related PRs

• mixmansoundude/Python_vs_Windows#404: Modified the same Miniconda installation and fallback messages.
• mixmansoundude/Python_vs_Windows#401: Updated related Miniconda installation documentation and backlog references.
• mixmansoundude/Python_vs_Windows#390: Implemented the Item 7 workflow changes referenced by this pull request.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the follow-up fixes, including Item 7 wording, AllUsers exit-code logging, and audit-tool hardening.
Description check	✅ Passed	The description directly explains the logging, documentation, test, audit-tool, and backlog changes in the pull request.
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 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 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: 5

🤖 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 `@run_setup.bat`:
- Around line 4517-4518: Update the HP_CONDA_ALLUSERS_ATTEMPTED handling around
:run_installer_timeout to preserve and detect its timeout sentinel separately
from the installer exit code. When the helper returns 1 for a timeout, log
reason=timeout without reporting exitCode=1; otherwise retain the
installer-failure message with the actual installer exit code.
- Around line 4509-4518: Add deterministic CI coverage for the AllUsers
installation flow around the `:tci_justme` and double-failure branches:
introduce a test-only `HP_*` failure hook or fake installer returning a fixed
nonzero exit code, then add NDJSON assertions referencing the log artifact path
for successful AllUsers, attempted-failure fallback with propagated exit code,
and genuine double-failure terminal output. Ensure each scenario has a dedicated
CI lane or flag and preserves the existing non-elevated skip behavior.

In `@tests/selfapps_justme.ps1`:
- Around line 69-70: Update the $failedWordingAbsent assertion in
tests/selfapps_justme.ps1 to reject the current stable failure-message prefix,
“Miniconda AllUsers install failed (”, rather than only the obsolete exact
wording without parentheses. Keep the existing assertion that verifies the
skipped wording.

In `@tools/audit_console_messages.py`:
- Around line 49-51: Update the batch-parameter normalization logic near the
existing `%~...` and `%[0-9]` substitutions to replace `%*` with the same `<V>`
placeholder, and add a regression test covering `%*` so audit output no longer
reports it as an undocumented expansion.
- Around line 70-77: Update the redirect checks in the echo and call :log
parsing branches of the audit script to skip unescaped single `>` redirects as
well as `>>`, while preserving escaped redirect handling. Add regression cases
covering both echo and call :log overwrite redirects.

🪄 Autofix (Beta)

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: 0a950975-a4f5-4ddb-acff-d1b9c751a341

📥 Commits

Reviewing files that changed from the base of the PR and between 15b0990 and c378f51.

📒 Files selected for processing (9)

• .github/workflows/batch-check.yml
• CLAUDE.md
• docs/agent-closed-backlog.md
• docs/demo-bootstrapper-output.md
• run_setup.bat
• tests/selfapps_conda_bothfail.ps1
• tests/selfapps_justme.ps1
• tests/test_audit_console_messages.py
• tools/audit_console_messages.py

📜 Review details

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

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

🧰 Additional context used

📓 Path-based instructions (14)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

Treat GitHub Actions results, especially Windows runner results, as authoritative; local or sandbox runs are advisory.

**/*: Update the relevant knowledge document in the same commit when a change teaches or invalidates a lesson; edit existing entries instead of only appending.
Freeze scope during an iteration loop; defer new requirements to the backlog and implement exactly one missing feature slice and one missing test per loop.

Files:

• tests/selfapps_justme.ps1
• tests/selfapps_conda_bothfail.ps1
• tests/test_audit_console_messages.py
• run_setup.bat
• CLAUDE.md
• docs/demo-bootstrapper-output.md
• docs/agent-closed-backlog.md
• tools/audit_console_messages.py

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

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{bat,cmd,ps1,py,yml,yaml,json}: Every new observable log line, disk file, or assertion-detectable behavior must have an NDJSON row and its artifact path must be included in the batch-check.yml test-logs upload using both existing slash variants.
Keep source text ASCII plain text and avoid non-ASCII punctuation.
Run the repository delimiter and syntax-regression checks; for batch files respect caret escaping and comments, and for PowerShell respect comments and here-strings.

Files:

• tests/selfapps_justme.ps1
• tests/selfapps_conda_bothfail.ps1
• tests/test_audit_console_messages.py
• run_setup.bat
• tools/audit_console_messages.py

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

📄 CodeRabbit inference engine (AGENTS.md)

Keep bootstrapper messages and CI parsers synchronized: update workflow checks when messages change, and preserve expected phrases when parser logic changes.

Files:

• tests/selfapps_justme.ps1
• tests/selfapps_conda_bothfail.ps1
• run_setup.bat

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

📄 CodeRabbit inference engine (AGENTS.md)

Prepend the TLS 1.2 SecurityProtocol assignment to every PowerShell Invoke-WebRequest call and retain -UseBasicParsing.

Files:

• tests/selfapps_justme.ps1
• tests/selfapps_conda_bothfail.ps1

**/*.ps1

📄 CodeRabbit inference engine (AGENTS.md)

Validate modified PowerShell scripts with pwsh; use AST parsing as the default syntax check and run modified scripts directly with realistic environment variables.

Files:

• tests/selfapps_justme.ps1
• tests/selfapps_conda_bothfail.ps1

**/*.{bat,ps1}

📄 CodeRabbit inference engine (CLAUDE.md)

Preserve CRLF line endings in .bat and .ps1 files; use LF for other files as configured by .gitattributes.

Files:

• tests/selfapps_justme.ps1
• tests/selfapps_conda_bothfail.ps1
• run_setup.bat

tests/**/*.ps1

📄 CodeRabbit inference engine (CLAUDE.md)

Parse-check all PowerShell test scripts with PowerShell’s parser before committing changes.

Files:

• tests/selfapps_justme.ps1
• tests/selfapps_conda_bothfail.ps1

tests/test_*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Run Python unit tests with python -m pytest tests/test_*.py -v when modifying Python code or tests.

Files:

• tests/test_audit_console_messages.py

run_setup.bat

📄 CodeRabbit inference engine (AGENTS.md)

run_setup.bat: run_setup.bat must function as a single bootstrapper when placed beside the application, without committed helper files.
Every branch added to run_setup.bat or related helpers must have a CI test, including feature flags, fallback/error-recovery paths, and fast/full paths; use an NDJSON assertion and a dedicated lane or HP_* flag when necessary.
When changing an embedded helper payload, update its matching base64 HP_* line from the canonical tools/ source and run delimiter checks.
Preserve tilde-prefixed runtime artifact paths and the documented ~env.state.json schema; unknown schemas must trigger a stale/full rebuild rather than an error.
Update the [VERSION_METADATA] block when CI verifies a newer Windows, PowerShell, or Python environment.

run_setup.bat: Keep run_setup.bat self-contained: helper logic must be embedded as base64 payloads under :define_helper_payloads; update payloads with python tools/sync_payload.py, never by hand.
Run python tools/check_delimiters.py run_setup.bat after every edit.
Pass --override-channels -c conda-forge on every conda installation command.
Invoke conda through call "%CONDA_BAT%" ... so the parent batch process continues running.
Avoid EnableDelayedExpansion; if required, scope it as narrowly as possible.
Use tilde-prefixed temporary files such as ~setup.log and ~bootstrap.status.json.
Every bootstrap run must write ~bootstrap.status.json with state ok, no_python_files, or error, plus exitCode and pyFiles fields.
Use explicit interpreter paths for bootstrap tool invocations; never depend on PATH, activation state, or console scripts.
Invoke pipreqs as python -m pipreqs.pipreqs, not the pipreqs console command.
Keep pipreqs pinned to version 0.4.13; do not upgrade it to 0.5.0 without reevaluating Python-version compatibility.
Tag non-obvious constraints with comments of the form # derived requirement: <why>.

Files:

• run_setup.bat

**/*.{bat,cmd}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{bat,cmd}: Use set "VAR=value" for batch assignments; execute filesystem paths as "%VAR%" at filesystem call sites. The NSIS /D= argument is the exception and must remain /D=%VAR%.
Before system-wide installation, silently test elevation with fsutil dirty query %systemdrive% >nul 2>&1; on failure, use the per-user installation path.
Avoid EnableDelayedExpansion unless it is strictly scoped, and disable it afterward; quote and escape batch syntax rather than silencing errors.

Keep Windows batch files ASCII-only; avoid emojis, curly quotes, em-dashes, and other non-ASCII characters.

Files:

• run_setup.bat

**/*.{md,bat,cmd}

📄 CodeRabbit inference engine (AGENTS.md)

Document run_setup.bat locations using stable label or subroutine names rather than exact line numbers.

Files:

• run_setup.bat
• CLAUDE.md
• docs/demo-bootstrapper-output.md
• docs/agent-closed-backlog.md

.github/workflows/*.yml

📄 CodeRabbit inference engine (CLAUDE.md)

Do not download packages from PSGallery in CI; use syntax-only PowerShell validation instead.

Files:

• .github/workflows/batch-check.yml

CLAUDE.md

📄 CodeRabbit inference engine (AGENTS.md)

Run the narrowly scoped advisory Markdown lint for CLAUDE.md; new Active Backlog entries must be bullets with the identifier in prose, reserving literal ordered-list syntax for grandfathered item 7.

Files:

• CLAUDE.md

tools/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Place new non-trivial helper logic in tools/ rather than embedding it inline in YAML, batch, or PowerShell files.

Files:

• tools/audit_console_messages.py

🔇 Additional comments (9)

.github/workflows/batch-check.yml (1)

334-334: LGTM!

Also applies to: 350-350, 443-443

CLAUDE.md (1)

487-494: LGTM!

tools/audit_console_messages.py (1)

90-113: LGTM!

tests/test_audit_console_messages.py (1)

4-7: LGTM!

Also applies to: 13-41, 56-80

run_setup.bat (1)

4484-4485: LGTM!

Also applies to: 4538-4540

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

511-530: LGTM!

docs/demo-bootstrapper-output.md (1)

1537-1537: LGTM!

Also applies to: 1549-1555, 1564-1564

tests/selfapps_conda_bothfail.ps1 (1)

12-16: LGTM!

Also applies to: 118-122

tests/selfapps_justme.ps1 (1)

60-68: LGTM!