fix: backlog items 8, 14, 19 -- UNC WARN, misleading syntax error, cache-lane trap

[mixmansoundude]

Summary

Three independent backlog-item fixes landed on this branch while its CI cycles were already running -- bundled here rather than split into separate PRs, since each was ready before the prior commit's CI settled and pushing a new commit resets the required checks anyway.

Item 8 -- broken/redundant UNC-paths WARN check:

• run_setup.bat's top-of-file findstr /C:"\\\\" >nul check fired [WARN] UNC paths not supported on every ordinary local CI checkout path, not just genuine UNC paths.
• The companion check two lines below already does the real, correctly-targeted UNC-prefix detection. Removed the broken/redundant line rather than repairing it.
• No test anywhere referenced the removed line (confirmed via repo-wide grep before removing).

Item 14 -- misleading "syntax error" on total Python-provider exhaustion:

• :after_env_mode_selection's HP_PY guard relied on :die's call-frame-only exit /b, so on total REQ-009 provider-tier exhaustion, execution fell through ~15 lines to :preflight_compile, which ran py_compile against an empty interpreter path and reported a fabricated "Your Python program has a syntax error" instead of the real "no Python interpreter found" cause. Confirmed via real CI capture (run 30328748330).
• Fix: the guard now also sets HP_NO_INTERPRETER=1; :preflight_compile checks it first and reports the real cause instead, which also skips the doomed PyInstaller build attempt entirely via the existing HP_PREFLIGHT_FAILED check.
• No test asserted on the old misleading text; the genuine syntax-error path and the one test reaching this code path (self.embed.fallback.decline) are both unaffected, verified before landing.

Item 19 -- cache CI lane's self-perpetuating corruption trap:

• Once a restored cache was flagged corrupted, the lane had no code path that ever produced a fresh valid cache again: both the only step that could do a fresh install and the save step were gated on the same HP_CACHE_CORRUPTED flag, so a poisoned blob (from a restore-keys prefix match) got restored, correctly detected as corrupted, and never replaced -- every single run, permanently. Matches the maintainer's own "cache lane never works" report.
• Fix: distinguish an EXACT cache-key hit (unfixable in place; left as-is, needs a cache-deletion API follow-on) from a restore-keys PREFIX match (the common case). On a corrupted prefix match, delete the stale directory and don't set HP_CACHE_CORRUPTED, letting the run fall through like a genuine cache miss so a real fresh install + fresh save can happen. Falls back to the original safe behavior if deletion is blocked (same AV/indexer file-lock hazard class already documented for :try_embed_fallback's directory swap).
• Not held back for dedicated multi-cycle verification -- cache runs on every future PR regardless of subject, so ordinary subsequent work already re-exercises it (maintainer guidance).

Test plan

• python tools/check_delimiters.py run_setup.bat -- clean
• python -m yamllint .github/workflows/batch-check.yml -- clean
• actionlint -oneline .github/workflows/batch-check.yml -- clean
• tools/run_sanity_sweep.sh (compileall, pyflakes, delimiter check, markdownlint, yamllint, actionlint, ASCII sweep, PowerShell AST parse sweep, full pytest) -- all green, 458 passed / 2 skipped, run fresh after each commit

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW

[chatgpt-codex-connector]

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

[coderabbitai]

Warning

Review limit reached

@mixmansoundude, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 7 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c159f9a2-58ab-4024-90f0-c393a877c0eb

📥 Commits

Reviewing files that changed from the base of the PR and between fd52a3f and a0a28b1.

📒 Files selected for processing (6)

• .github/workflows/batch-check.yml
• docs/agent-closed-backlog.md
• docs/agent-lessons-learned.md
• docs/demo-bootstrapper-output.md
• run_setup.bat
• tests/selfapps_ux_hardening.ps1

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Removed a misleading UNC-path warning for ordinary local paths while preserving valid UNC detection.
  • Improved setup behavior when no Python interpreter can be found, reporting that execution and build steps were skipped.
  • Improved cache recovery by rebuilding installations restored from corrupted cache prefixes when possible.
  • Preserved safe handling for corruption in exact cache matches.

• Documentation

  • Updated setup output and backlog documentation to reflect these fixes and closed related open questions.

Walkthrough

The setup script corrects UNC-path detection and reports unresolved interpreters without attempting compilation. The CI workflow distinguishes exact cache hits from prefix restores during corruption handling. Documentation records the corrected behavior and closes the related backlog items.

Changes

Bootstrapper path and interpreter handling

Layer / File(s)	Summary
Path and interpreter failure handling run_setup.bat, docs/demo-bootstrapper-output.md, docs/agent-closed-backlog.md	The script uses a direct UNC-prefix check. When no interpreter is resolved, preflight reports the acquisition failure, marks preflight as failed, and skips py_compile. Documentation records both changes.

Cache corruption recovery

Layer / File(s)	Summary
Cache corruption recovery .github/workflows/batch-check.yml, docs/agent-closed-backlog.md, docs/open-questions.md	Exact-key corruption retains the skip behavior. Prefix-restored corrupt caches are deleted and rebuilt when possible. The cache question is removed from the open-items document.

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

Possibly related PRs

• mixmansoundude/Python_vs_Windows#400: Directly relates to the UNC-path warning fix and Scenario 8 documentation.
• mixmansoundude/Python_vs_Windows#402: Directly relates to interpreter-failure handling and the associated backlog documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the three backlog fixes: UNC warning behavior, misleading syntax errors, and cache corruption handling.
Description check	✅ Passed	The description accurately explains the three fixes, their rationale, affected files, 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: 3

🤖 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 `@docs/agent-closed-backlog.md`:
- Around line 591-593: Update the backlog entry in the unlabeled prologue to
remove the exact run_setup.bat:57-58 reference, citing the removed findstr
UNC-path check or another stable label instead. Preserve the existing
description of the C-runtime backslash-before-quote rule.
- Around line 592-597: The findstr incident descriptions must avoid asserting
unresolved parser behavior. In docs/agent-closed-backlog.md lines 592-597 and
docs/demo-bootstrapper-output.md lines 648-651, remove the two-backslash
explanation and C-runtime parser attribution, and state only that the removed
check emitted [WARN] for an ordinary local path and was removed.

In `@docs/demo-bootstrapper-output.md`:
- Around line 655-657: Update the backlog cross-reference in the documented
UNC-detection note to point to Item 8 in docs/agent-closed-backlog.md instead of
CLAUDE.md's Closed Backlog, preserving the surrounding explanation.

🪄 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: d1c22331-6136-479d-8138-08e9f3d7f731

📥 Commits

Reviewing files that changed from the base of the PR and between d5a2686 and a1ea693.

📒 Files selected for processing (4)

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

💤 Files with no reviewable changes (2)

• CLAUDE.md
• run_setup.bat

📜 Review details

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

• GitHub Check: auto_merge
• GitHub Check: Batch syntax/run check (contract-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)
• GitHub Check: Batch syntax/run check (cache)
• GitHub Check: Batch syntax/run check (contract-uv-fail)
• GitHub Check: Batch syntax/run check (real)
• GitHub Check: Batch syntax/run check (uv)

🧰 Additional context used

📓 Path-based instructions (3)

**/*

📄 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.

Files:

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

**/*.{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/demo-bootstrapper-output.md

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

📄 CodeRabbit inference engine (CLAUDE.md)

Use ASCII-only characters in repository files; avoid emojis, curly quotes, and em dashes.

Files:

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

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-01T02:20:06.201Z
Learning: Freeze scope during an iteration loop; defer newly discovered requirements to the backlog.

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-01T02:20:06.201Z
Learning: Fix CI and pipeline issues before test errors, test assertions, and product code; after success, verify no false positives.

[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 `@docs/agent-closed-backlog.md`:
- Around line 591-595: Remove the unverified findstr backslash-doubling and
cmd.exe C-runtime parsing explanation from docs/agent-closed-backlog.md lines
591-595 and docs/demo-bootstrapper-output.md lines 648-651. In both locations,
retain only the observed warning, ordinary local-path behavior, redundant-check
removal rationale, and separate UNC-prefix guard.

🪄 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: c81ff1d4-18d9-4885-9162-086a52aba9cb

📥 Commits

Reviewing files that changed from the base of the PR and between a1ea693 and 629f3a9.

📒 Files selected for processing (2)

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

📜 Review details

🧰 Additional context used

📓 Path-based instructions (2)

**/*

📄 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.

**/*: Run the full mandatory sanity sweep before every commit, including compilation, linting, delimiter checks, workflow validation, ASCII checks, PowerShell parsing, and pytest.
Update the relevant knowledge document in the same commit when a change teaches or invalidates a lesson; edit existing entries rather than only appending.
When an Active Backlog item is fully resolved, remove it from the active list and move it to docs/agent-closed-backlog.md while preserving its original number.
Freeze scope for the current iteration loop; implement exactly one missing feature slice and add exactly one missing test per loop.

Files:

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

**/*.{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/demo-bootstrapper-output.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
• docs/demo-bootstrapper-output.md

[coderabbitai]

Actionable comments posted: 4

🤖 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 @.github/workflows/batch-check.yml:
- Around line 107-112: Update the comment in the cache handling block to
reference docs/agent-closed-backlog.md instead of CLAUDE.md, preserving the
existing incident description and behavior guidance.

In `@run_setup.bat`:
- Around line 1017-1019: Stop execution immediately after the fatal
interpreter-resolution path calls :die, preventing the script from continuing
into success handling with an invalid HP_PY. Add an unconditional non-zero
termination or transfer to a top-level fatal cleanup label after :die, ensuring
bootstrap cleanup remains correct and the final status cannot be rewritten as
exitCode:0.
- Around line 1017-1019: Update the interpreter validation around HP_PY and the
existing HP_NO_INTERPRETER path to verify that the selected executable both
exists and successfully runs a minimal canary command before continuing. Route
any missing, stale, or non-runnable HP_PY value through the existing explicit
no-interpreter failure path, preserving fail-fast behavior and avoiding silent
fallback.
- Around line 3410-3421: Add regression assertions to the exhaustion-case test
for the HP_NO_INTERPRETER branch, covering the “No Python interpreter is
available” message, absence of “Your Python program has a syntax error,” no
PyInstaller build attempt, and preservation of the error status. Locate the
relevant self.embed.fallback.decline assertions and extend that case without
changing the existing ordinary syntax-error test.

🪄 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: 1f68ecd6-b233-4461-9faf-73a7d18d44e7

📥 Commits

Reviewing files that changed from the base of the PR and between 629f3a9 and fd52a3f.

📒 Files selected for processing (6)

• .github/workflows/batch-check.yml
• CLAUDE.md
• docs/agent-closed-backlog.md
• docs/demo-bootstrapper-output.md
• docs/open-questions.md
• run_setup.bat

💤 Files with no reviewable changes (1)

• CLAUDE.md

📜 Review details

🧰 Additional context used

📓 Path-based instructions (9)

**/*

📄 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.

Files:

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

**/.github/workflows/*.{yml,yaml}

📄 CodeRabbit inference engine (AGENTS.md)

**/.github/workflows/*.{yml,yaml}: Use GitHub Actions CI results, especially Job Summary, grouped log tails, and workflow PR failure comments, as the source of truth; local runs are advisory.
Isolate slow, flaky, or environment-dependent diagnostics in separate non-gating lanes using continue-on-error rather than weakening deterministic gating lanes.
Keep CI parser checks synchronized with exact bootstrapper messages and preserve the single parser-facing iterate signal * Iterate logs: {found|missing}.
The iterate job must upload one artifact named iterate-logs-${run_id}-${run_attempt} containing iterate/_temp/ and the job summary; do not alter the intentional pre-flight gate failure for missing NDJSON inputs.

Files:

• .github/workflows/batch-check.yml

.github/workflows/*.yml

📄 CodeRabbit inference engine (CLAUDE.md)

Validate workflow YAML with yamllint and actionlint before committing changes.

Files:

• .github/workflows/batch-check.yml

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 add committed helper files; embed helpers as base64 payloads under :define_helper_payloads.
After every edit to run_setup.bat, run python tools/check_delimiters.py run_setup.bat.
Invoke conda with call "%CONDA_BAT%" ... so the parent batch process continues.
All conda installs must use --override-channels -c conda-forge to prevent defaults-channel contamination.
Avoid EnableDelayedExpansion; if required, scope it as tightly as possible.
Use tilde-prefixed temporary files such as ~setup.log and ~bootstrap.status.json.
The bootstrapper must write ~bootstrap.status.json on every run with state, exitCode, and pyFiles fields.
Test all three bootstrap code paths—cache, real, and conda-full—after significant changes.
Never depend on console scripts during bootstrap; invoke tools through an explicit interpreter or direct Python module/API.
Anchor every bootstrap tool invocation to an explicit Python executable such as %HP_PY% or %CONDA_PREFIX%\python.exe.
Use python -m pipreqs.pipreqs, not the pipreqs console script, and retain the pinned pipreqs versi...

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

**/*.{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:

• 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:

• run_setup.bat

**/*.{bat,ps1}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{bat,ps1}: Use ASCII-only characters in Windows batch and PowerShell files; avoid emojis, curly quotes, and em dashes.
Preserve CRLF line endings in .bat and .ps1 files; use LF for other files according to .gitattributes.

Files:

• run_setup.bat

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-01T02:54:13.822Z
Learning: Keep knowledge documents current in the same commit when a change teaches or invalidates a lesson; edit existing entries rather than only appending.

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-01T02:54:13.822Z
Learning: When an Active Backlog item is fully resolved, remove it from the active file and move it to `docs/agent-closed-backlog.md` while preserving its original number.

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-01T02:54:13.822Z
Learning: Freeze scope during an iteration loop; implement exactly one missing feature slice and add exactly one missing test per loop.

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-01T02:54:13.822Z
Learning: Fix issues in this order: CI pipeline/configuration, test errors, test assertions, then product code; verify no false positives after achieving a green build.

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

🔇 Additional comments (5)

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

95-96: 📐 Maintainability & Code Quality

Confirm required workflow validation.

The supplied validation summary reports delimiter checks. It does not identify yamllint or actionlint results. Run both checks before merge.

As per coding guidelines, “Validate workflow YAML with yamllint and actionlint before committing changes.”

Source: Coding guidelines

docs/open-questions.md (1)

12-12: LGTM!

run_setup.bat (1)

57-57: LGTM!

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

645-658: LGTM!

Also applies to: 2304-2320, 2340-2365

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

586-618: LGTM!

Also applies to: 619-669, 671-728