Item 33: reason= tokens for PyInstaller/Nuitka build-tool failures

[mixmansoundude]

Summary

Closes CLAUDE.md Active Backlog Item 33 (a CodeRabbit review finding on PR #423 that wasn't
implemented there since it needed its own design pass).

:run_entry_after_smoke's three build-exhaustion :die call sites (both PyInstaller and the
Nuitka Tier A fallback have failed) all produced one of two generic [ERROR] messages with no
way to distinguish which of three genuinely different conditions actually fired. Added reason=
tokens, mirroring the existing UV_FALLBACK reason=<token> convention exactly (which already has
a reason=test_forced_fail precedent for the identical "this is a CI test hook, not a real
failure" distinction) -- no new probing of PyInstaller's own stderr needed, since the three
conditions are already distinguishable purely by which code branch reached :die:

• reason=test_forced_fail -- HP_TEST_FORCE_PYINSTALLER_FAIL simulated the failure; no real
  PyInstaller invocation ever ran.
• reason=build_error -- a genuine PyInstaller invocation returned a nonzero exit code. Real
  code, but not exercised by any deterministic CI hook (same "extrapolated, not tested" status as
  a real Nuitka compiler failure documented elsewhere in the demo doc).
• reason=missing_output -- the build reported success but dist\<env>.exe never appeared
  (HP_TEST_FORCE_OUTPUT_VANISH in CI; a real AV/indexer deletion in production).

self.exe.smokerun's NDJSON row turned out not to need a matching change: :run_exe_smokerun
exits immediately whenever dist\<env>.exe is missing, before ever reaching the row emission --
so no row is emitted for a total build failure in the first place. The two :die messages' own
reason= tokens (now in %LOG%) are the actual legibility improvement. No tests/harness.ps1
static guard referenced either message string (confirmed via grep), so no harness change was
needed either, contrary to the original item's own speculation.

Also updated tests/selfapps_pyinstaller_fail.ps1's self.exe.build.xfail scenario to assert the
expected reason= token per sub-scenario, and docs/demo-bootstrapper-output.md's Scenario
38a/38b real-CI-capture quotes to include the new token (spliced from current source, labeled
honestly as a post-capture splice rather than a fresh capture, so the doc stays accurate).

Item 33 moved from CLAUDE.md's Active Backlog to docs/agent-closed-backlog.md's Closed Active
Backlog Items section (keeping its original number).

Test plan

• tools/run_sanity_sweep.sh run_setup.bat tests/selfapps_pyinstaller_fail.ps1 docs/demo-bootstrapper-output.md docs/agent-closed-backlog.md -- all clean, 515 passed /
  3 skipped.
• python tools/check_delimiters.py run_setup.bat -- clean.
• python tools/check_ndjson_registry.py -- 298/298, no doc/code mismatch (no new row IDs;
  only existing self.exe.build.xfail row's details shape changed).
• PowerShell AST parse sweep on the modified test file -- clean.
• Traced self.exe.smokerun's emission path directly against source (:run_exe_smokerun's
  early exit /b 0 guard) to confirm it genuinely never fires for a build failure, rather than
  assuming the backlog item's own premise.

---

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.

[mixmansoundude]

@coderabbitai review

---

Generated by Claude Code

[coderabbitai]

@mixmansoundude: I will review the changes in #427.

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b250b1fa-aa56-4b01-9ad5-0434ec24654a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • PyInstaller build failure messages now identify whether the failure was forced for testing, caused by a build error, or resulted from missing output.
  • Improved diagnostics make it easier to distinguish genuine build problems from expected test scenarios.

• Documentation

  • Updated demo documentation with the new failure-reason indicators and explanations.
  • Added documentation covering build-failure classifications and expected scenarios.

Walkthrough

PyInstaller failure messages now identify forced failures, build errors, and missing output. The self-test validates each scenario-specific token. Demo and backlog documentation record the classifications, and the active backlog entry is removed.

Changes

PyInstaller failure reason classification

Layer / File(s)	Summary
Failure reason implementation and validation run_setup.bat, tests/selfapps_pyinstaller_fail.ps1	PyInstaller failure branches emit reason=test_forced_fail, reason=build_error, or reason=missing_output. The self-test checks the expected token and records the diagnostic result.
Documentation and backlog closure docs/demo-bootstrapper-output.md, docs/agent-closed-backlog.md, CLAUDE.md	Demo output documents the new tokens. Backlog Item 33 is recorded as closed, and its active entry is removed.

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

Possibly related PRs

• mixmansoundude/Python_vs_Windows#402: Updates Scenario 38 PyInstaller output documentation.
• mixmansoundude/Python_vs_Windows#423: Defines the Active Backlog Item 33 classifications implemented here.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly identifies the main change: adding reason tokens for PyInstaller and Nuitka build-tool failures.
Description check	✅ Passed	The description accurately explains the reason tokens, affected paths, tests, documentation updates, and backlog closure.

✨ 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: 2

🤖 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/selfapps_pyinstaller_fail.ps1`:
- Around line 141-146: Add deterministic CI coverage in
tests/selfapps_pyinstaller_fail.ps1 for the genuine nonzero PyInstaller exit
path: introduce or reuse a CI-only hook that makes PyInstaller return a nonzero
status without forcing output disappearance, then exercise the relevant scenario
and assert the combined output contains reason=build_error. Preserve the
existing assertions for reason=test_forced_fail and reason=missing_output.
- Around line 145-146: Update the reason assertion in the test around
$expectedReasonFound to search only the log line containing $expectedMsg, rather
than the entire $combined bootstrap log. Extract or identify that PyInstaller
error line, then verify it contains $expectedReason while preserving the
existing scenario-specific expected reason selection.

🪄 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: 6d8e504a-bd03-487a-bdd8-6e4c9c071bbd

📥 Commits

Reviewing files that changed from the base of the PR and between 2418b50 and 9da53f5.

📒 Files selected for processing (5)

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

💤 Files with no reviewable changes (1)

• CLAUDE.md

📜 Review details

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

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

🧰 Additional context used

📓 Path-based instructions (10)

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

📄 CodeRabbit inference engine (AGENTS.md)

Keep text ASCII-only and do not manually change line endings; follow .gitattributes.

Files:

• docs/demo-bootstrapper-output.md
• tests/selfapps_pyinstaller_fail.ps1
• run_setup.bat
• docs/agent-closed-backlog.md

**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

Cite run_setup.bat locations by stable label or subroutine name rather than exact line number in documentation.

Files:

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

**/*.ps1

📄 CodeRabbit inference engine (AGENTS.md)

**/*.ps1: Prepend the TLS 1.2 SecurityProtocol assignment and retain -UseBasicParsing on every PowerShell 5.1 Invoke-WebRequest call.
Before system-wide installation, silently check elevation with fsutil dirty query %systemdrive% >nul 2>&1; on failure, use the per-user fallback.

Files:

• tests/selfapps_pyinstaller_fail.ps1

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

📄 CodeRabbit inference engine (AGENTS.md)

Validate modified PowerShell files with the .NET AST parser or tools/ps-compileall.ps1; do not skip validation on Linux, and directly invoke modified scripts after installing pwsh where practical.

Files:

• tests/selfapps_pyinstaller_fail.ps1

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

📄 CodeRabbit inference engine (AGENTS.md)

Run tools/check_delimiters.py to validate paired delimiters and quotes while respecting language-specific comments and escaping.

Files:

• tests/selfapps_pyinstaller_fail.ps1
• run_setup.bat

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

📄 CodeRabbit inference engine (AGENTS.md)

Enforce conda-forge only: add conda-forge and remove defaults before updates or installs, and always install with --override-channels -c conda-forge.

Files:

• tests/selfapps_pyinstaller_fail.ps1
• run_setup.bat

tests/*.ps1

📄 CodeRabbit inference engine (CLAUDE.md)

Add PowerShell scenario tests as tests/selfapps_<scenario>.ps1 and wire new scenarios into tests/harness.ps1 with NDJSON rows.

Files:

• tests/selfapps_pyinstaller_fail.ps1

run_setup.bat

📄 CodeRabbit inference engine (AGENTS.md)

run_setup.bat: run_setup.bat must function as a single bootstrapper when dropped beside the application, without requiring committed helper files.
Every branch added to run_setup.bat or its related helpers must have a CI test, including feature flags, fallbacks, recovery paths, and fast/full paths.
Keep bootstrapper log messages synchronized with CI parsers; update workflow checks whenever messages or status summaries change.
All embedded helpers must remain base64-encoded under :define_helper_payloads; changing one requires synchronizing the matching HP_* line and rerunning delimiter checks.
Do not remove tilde prefixes from runtime artifact paths such as ~bootstrap.status.json, ~setup.log, ~environment.lock.txt, and ~env.state.json.

run_setup.bat: Keep run_setup.bat self-contained: do not add committed helper files; embed helpers as base64 payloads under :define_helper_payloads, and refresh them with python tools/sync_payload.py rather than manually editing encoded content.
Run python tools/check_delimiters.py run_setup.bat after every edit to run_setup.bat.
Preserve the bootstrap status contract: every run must write ~bootstrap.status.json with state, exitCode, and pyFiles fields.
Use --override-channels -c conda-forge on every conda installation command.
Invoke conda through call "%CONDA_BAT%" ... so the parent batch process continues running.
Do not depend on console scripts during bootstrap; anchor every tool invocation to an explicit interpreter path such as %HP_PY% or %CONDA_PREFIX%\python.exe.
Avoid EnableDelayedExpansion; if it is necessary, scope it tightly.
Use tilde-prefixed temporary files such as ~setup.log and ~bootstrap.status.json.
Keep the three cache, real, and conda-full execution paths working and test all three after significant changes.
Keep non-obvious constraints documented inline with comments such as # derived requirement: <why>.
Keep pipreqs pinned to version 0.4.13 and invoke it as ...

Files:

• run_setup.bat

**/*.{bat,cmd}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{bat,cmd}: For batch assignments, use set "VAR=value"; do not use set VAR="value". Quote variables at every filesystem command call site, except NSIS /D= parameters, which must remain unquoted.
Avoid unscoped EnableDelayedExpansion, preserve correct escaping of special characters, and use ASCII plain text.
Run tools/check_delimiters.py and apply its batch heuristics, including caret escaping, quoted filesystem variables, escaped pipes, PowerShell operator placement, and spacing after rem.
Use tools/sync_payload.py as the only sanctioned method for re-encoding embedded HP_* payloads in run_setup.bat; never hand-roll the splice process.

Files:

• run_setup.bat

*.bat

📄 CodeRabbit inference engine (CLAUDE.md)

Use CRLF line endings for batch files; do not manually override the repository's .gitattributes behavior.

Files:

• run_setup.bat

🧠 Learnings (3)

📓 Common learnings

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-09T06:48:29.858Z
Learning: Update the relevant knowledge document in the same commit when a change teaches or invalidates a lesson; move fully resolved Active Backlog items to `docs/agent-closed-backlog.md`.

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-09T06:48:29.858Z
Learning: Before every commit, run the full mandatory sanity sweep, extending the ASCII file list to cover files touched by the change.

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-09T06:48:29.858Z
Learning: Follow the iteration contract: freeze scope, fix CI before tests and product code, implement exactly one missing feature slice, and add exactly one missing test per loop.

📚 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/demo-bootstrapper-output.md
• docs/agent-closed-backlog.md

📚 Learning: 2026-08-09T04:42:17.730Z

Learnt from: mixmansoundude
Repo: mixmansoundude/Python_vs_Windows PR: 426
File: tests/selftest.ps1:79-124
Timestamp: 2026-08-09T04:42:17.730Z
Learning: For PowerShell scenario tests in tests/, use tests/selfapps_<scenario>.ps1 with tests/harness.ps1 and CI registration for standalone full-bootstrap scenarios. Keep closely related extensions of flows already covered by tests/selftest.ps1—including empty-folder and shared stub-flow scenarios—in tests/selftest.ps1, reusing its Invoke-Setup helper and scratch-directory infrastructure instead of adding separate harness or CI wiring.

Applied to files:

• tests/selfapps_pyinstaller_fail.ps1

🔇 Additional comments (5)

run_setup.bat (1)

3460-3461: LGTM!

Also applies to: 3470-3475, 3487-3488

tests/selfapps_pyinstaller_fail.ps1 (1)

174-185: LGTM!

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

3110-3138: LGTM!

---

3148-3160: LGTM!

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

1818-1856: LGTM!

[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/selfapps_pyinstaller_fail.ps1`:
- Around line 146-151: Add a nearby comment using the exact format “# derived
requirement: <why>” explaining that the failure reason must appear on the same
log line as $expectedMsg to verify the PyInstaller error line itself. Keep the
existing $expectedFailureLines and $expectedReasonFound logic unchanged.

🪄 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: de66afef-459c-4fee-bd2f-4f4fd31629f8

📥 Commits

Reviewing files that changed from the base of the PR and between 9da53f5 and bf20001.

📒 Files selected for processing (1)

• tests/selfapps_pyinstaller_fail.ps1

📜 Review details

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

• GitHub Check: analyze

🧰 Additional context used

📓 Path-based instructions (8)

**/*.ps1

📄 CodeRabbit inference engine (AGENTS.md)

**/*.ps1: Prepend the TLS 1.2 SecurityProtocol assignment and retain -UseBasicParsing on every PowerShell 5.1 Invoke-WebRequest call.
Before system-wide installation, silently check elevation with fsutil dirty query %systemdrive% >nul 2>&1; on failure, use the per-user fallback.

Files:

• tests/selfapps_pyinstaller_fail.ps1

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

📄 CodeRabbit inference engine (AGENTS.md)

Validate modified PowerShell files with the .NET AST parser or tools/ps-compileall.ps1; do not skip validation on Linux, and directly invoke modified scripts after installing pwsh where practical.

Files:

• tests/selfapps_pyinstaller_fail.ps1

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

📄 CodeRabbit inference engine (AGENTS.md)

Run tools/check_delimiters.py to validate paired delimiters and quotes while respecting language-specific comments and escaping.

Files:

• tests/selfapps_pyinstaller_fail.ps1

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

📄 CodeRabbit inference engine (AGENTS.md)

Enforce conda-forge only: add conda-forge and remove defaults before updates or installs, and always install with --override-channels -c conda-forge.

Files:

• tests/selfapps_pyinstaller_fail.ps1

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

📄 CodeRabbit inference engine (AGENTS.md)

Keep text ASCII-only and do not manually change line endings; follow .gitattributes.

Files:

• tests/selfapps_pyinstaller_fail.ps1

**/*.{bat,ps1}

📄 CodeRabbit inference engine (CLAUDE.md)

Use CRLF line endings for .bat and .ps1 files; use LF for other files, as controlled by .gitattributes.

Files:

• tests/selfapps_pyinstaller_fail.ps1

tests/selfapps_*.ps1

📄 CodeRabbit inference engine (CLAUDE.md)

Add PowerShell scenario tests as tests/selfapps_<scenario>.ps1 and wire new scenarios into tests/harness.ps1 and the relevant CI job steps.

Files:

• tests/selfapps_pyinstaller_fail.ps1

**/*

📄 CodeRabbit inference engine (CLAUDE.md)

**/*: Use ASCII-only content; avoid emojis, curly quotes, em-dashes, and other non-ASCII characters because batch and CMD parsing can break.
Tag non-obvious constraints with a comment in the form # derived requirement: <why>.

Files:

• tests/selfapps_pyinstaller_fail.ps1

🧠 Learnings (1)

📚 Learning: 2026-08-09T04:42:17.730Z

Learnt from: mixmansoundude
Repo: mixmansoundude/Python_vs_Windows PR: 426
File: tests/selftest.ps1:79-124
Timestamp: 2026-08-09T04:42:17.730Z
Learning: For PowerShell scenario tests in tests/, use tests/selfapps_<scenario>.ps1 with tests/harness.ps1 and CI registration for standalone full-bootstrap scenarios. Keep closely related extensions of flows already covered by tests/selftest.ps1—including empty-folder and shared stub-flow scenarios—in tests/selftest.ps1, reusing its Invoke-Setup helper and scratch-directory infrastructure instead of adding separate harness or CI wiring.

Applied to files:

• tests/selfapps_pyinstaller_fail.ps1

🔇 Additional comments (2)

tests/selfapps_pyinstaller_fail.ps1 (2)

141-145: Duplicate: add coverage for reason=build_error.

This test still covers only reason=test_forced_fail and reason=missing_output. The genuine nonzero PyInstaller exit branch remains untested. A regression in that branch can pass CI. The previous review already reported this gap.

---

179-190: LGTM!

[mixmansoundude]

@coderabbitai review

---

Generated by Claude Code

[coderabbitai]

@mixmansoundude I will review the changes in #427.

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.