Skip to content

Bound :exe_smokerun_hints' rerun timeout; close backlog items 12/13; compress agent docs - #410

Merged
mixmansoundude merged 8 commits into
mainfrom
claude/bootstrapper-execution-branches-ox2izi
Aug 1, 2026
Merged

Bound :exe_smokerun_hints' rerun timeout; close backlog items 12/13; compress agent docs#410
mixmansoundude merged 8 commits into
mainfrom
claude/bootstrapper-execution-branches-ox2izi

Conversation

@mixmansoundude

@mixmansoundude mixmansoundude commented Aug 1, 2026

Copy link
Copy Markdown
Owner

Summary

Started as backlog item 15 (bound :exe_smokerun_hints' untimed diagnostic re-run); grew to include two more independently-ready backlog fixes and a docs-compression pass, bundled here rather than split into separate PRs since each was ready before this PR's own long CI cycle (real/conda-full lanes run ~80-90 min) settled -- same reasoning as PR #408's own precedent.

Item 15: :exe_smokerun_hints' diagnostic re-run had no timeout

Closes CLAUDE.md's former Active Backlog item 15 (flagged by a CodeRabbit review on PR #402): :exe_smokerun_hints' diagnostic re-run of a freshly-failed EXE was the one user-code launch point in run_setup.bat with no timeout at all.

  • tools/exe_hint_rerun.ps1 (new, embedded as HP_EXE_HINT_RERUN): a dedicated bounded-launch helper. Diagnostic-only, never shown live to the user, so the kill is unconditional at the deadline -- unlike ~exe_smokerun.ps1's activity-aware philosophy.
  • run_setup.bat: :exe_smokerun_hints now emits and invokes the new helper instead of the raw untimed invocation.
  • tests/test_exe_hint_rerun.py (new).
  • CodeRabbit review found 3 real issues (missing explicit output path, Process.Kill() not killing descendant processes, a weak timing assertion) -- all fixed. Real CI then surfaced 2 more Windows-only bugs invisible from this sandbox (a too-tight timing bound under real CI load, and a PermissionError from a test that deliberately orphans a process) -- both fixed.

Item 12: embed-tier download-retry path had no CI test hook

:embed_dl_retry's genuine mid-download-failure-then-retry-once path had no coverage. Added HP_TEST_FORCE_EMBED_DL_FAIL_ONCE (mirrors the existing HP_TEST_FORCE_CONDA_CREATE_NETWORK_FAIL one-shot-then-succeed pattern) plus a new self.embed.dl.retry scenario in tests/selfapps_ux_hardening.ps1 proving retry-then-succeed end-to-end.

Item 13: self.warn.longpath silently reported an overall pass on an inconclusive result

Root-caused to PowerShell's Push-Location failing before cmd /c is ever reached, since default GitHub-hosted Windows runners don't have LongPathsEnabled. Confirmed persistent via a second real CI observation (this PR's own runs) matching the original finding's exact signature. Fixed by reporting skip=true instead of an overstated pass when the runner cannot even attempt the code path under test.

Docs compression

Trimmed discovery-narrative and superseded-implementation history from docs/agent-lessons-learned.md (1404 -> 1105 lines) and docs/agent-interconnect.md (1827 -> 1355 lines) while preserving every hazard, rule, exact error string, flag name, and table -- both auto-load into every future agent session via CLAUDE.md's @import, so their size is a per-session cost.

Test plan

  • tests/test_exe_hint_rerun.py: 7/7 passed locally
  • python tools/check_delimiters.py run_setup.bat -- clean
  • Full sanity sweep (tools/run_sanity_sweep.sh): compileall, pyflakes, delimiter check, markdownlint, yamllint, actionlint, ASCII sweep, PowerShell AST parse sweep, pytest (468 passed, 2 skipped) -- all clean, re-run after every commit
  • self.embed.dl.retry/self.warn.longpath PowerShell scenario changes verified via pwsh AST parse (no real Windows CI available locally -- watching real CI on this PR for confirmation)

🤖 Generated with Claude Code


Generated by Claude Code

The diagnostic re-run of a freshly-failed EXE (:exe_smokerun_hints) was
the one user-code launch point in run_setup.bat with no timeout at all
-- a plain, synchronous `"%ENVNAME%.exe" > "~exe_out.txt" 2>&1`. Any
non-determinism in the app (a race, an env check that sometimes
succeeds, anything that occasionally blocks on inherited stdin) could
hang this second, untimed invocation even though the first invocation
legitimately classified as a fast, non-hang failure.

Added tools/exe_hint_rerun.ps1 (embedded as HP_EXE_HINT_RERUN), a
dedicated bounded-launch helper with an UNCONDITIONAL kill deadline
(default 10s) -- deliberately not activity-aware like the sibling
~exe_smokerun.ps1/~failfast_probe.ps1 helpers, since this re-run is
diagnostic-only (never shown live) and partial output on a hang is
fine and preferred over hanging the bootstrap a second time.

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

Copy link
Copy Markdown

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

@mixmansoundude
mixmansoundude enabled auto-merge (squash) August 1, 2026 11:41
@coderabbitai

coderabbitai Bot commented Aug 1, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Summary by CodeRabbit

  • Bug Fixes

    • Added configurable timeouts and process cleanup for diagnostic executable reruns.
    • Improved diagnostic output capture and handling of hanging processes.
    • Added reliable retry handling for embedded-Python downloads.
    • Improved interpreter, workspace, and long-path scenario handling.
  • Tests

    • Added coverage for diagnostic reruns, retries, configuration overrides, and long-path outcomes.
  • Documentation

    • Expanded guidance on diagnostics, fallback behavior, caching, retries, and artifact handling.

Walkthrough

The PR adds a bounded PowerShell diagnostic rerun, deterministic embedded-Python retry coverage, PVW override self-tests, corrected long-path result classification, and updated bootstrap documentation.

Changes

Bootstrap hardening

Layer / File(s) Summary
Bounded diagnostic EXE rerun
tools/exe_hint_rerun.ps1, run_setup.bat, tests/test_exe_hint_rerun.py
The diagnostic rerun captures combined output, terminates timed-out process trees, bounds output draining, and synchronizes the embedded helper payload.
Fallback and environment override coverage
run_setup.bat, tests/selfapps_ux_hardening.ps1, tests/selfapps_pvw_overrides.ps1, .github/workflows/batch-check.yml, docs/agent-ndjson.md
The embedded-Python download path supports deterministic first-attempt failure testing. Self-tests cover retry behavior and valid or invalid PVW_PYTHON_EXE and PVW_WORKSPACE overrides.
Self-test result classification
tests/selftest.ps1, docs/agent-closed-backlog.md
Long-path results distinguish pass, skip, and fail states. Closed backlog entries record the completed coverage.
Bootstrap behavior documentation
docs/agent-interconnect.md, docs/agent-lessons-learned.md, docs/agent-closed-backlog.md
Documentation records provider fallback, process handling, payload synchronization, cache behavior, PEP 723 behavior, and completed backlog items.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Setup as run_setup.bat
  participant Helper as exe_hint_rerun.ps1
  participant DiagnosticEXE
  participant SelfTest as PowerShell self-tests
  participant Output as NDJSON or output file
  Setup->>Helper: Invoke bounded diagnostic rerun
  Helper->>DiagnosticEXE: Launch with redirected output
  Helper->>DiagnosticEXE: Terminate process tree at deadline
  Helper->>Output: Write combined diagnostic output
  SelfTest->>Setup: Run retry and override scenarios
  Setup->>Output: Record pass, skip, or fail result
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 9.09% 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 accurately identifies the timeout fix and the additional backlog and documentation changes.
Description check ✅ Passed The description clearly explains the timeout fix, added test coverage, backlog items, documentation changes, and validation performed.
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 coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 `@run_setup.bat`:
- Around line 4025-4028: Set HP_HINT_RERUN_OUT explicitly to the expected
dist\~exe_out.txt path before invoking ~exe_hint_rerun.ps1, then clear it
alongside HP_HINT_RERUN_EXE afterward so the helper output matches the file
consumed and deleted by the later hint-capture logic.

In `@tests/test_exe_hint_rerun.py`:
- Around line 97-120: Update both test_silent_hang_is_killed and
test_hang_after_output_is_ALSO_killed_unlike_exe_smokerun to record
time.monotonic() immediately before and after _run_hint_rerun, then assert the
elapsed duration stays below a generous bound such as 8 seconds, while
preserving their existing return-code and output assertions.

In `@tools/exe_hint_rerun.ps1`:
- Around line 49-61: Update the timeout cleanup in the process execution flow
around $p.Kill() to terminate the entire process tree, using the existing
platform-appropriate mechanism such as taskkill /F /T or a Job Object; retain
the subsequent pipe-draining behavior. Add a regression fixture that launches a
child process which keeps stdout open, and verify timeout handling completes
without waiting indefinitely.
🪄 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: 348b7580-deba-40a9-b299-5620428daad4

📥 Commits

Reviewing files that changed from the base of the PR and between 40e6187 and d34a97e.

📒 Files selected for processing (6)
  • CLAUDE.md
  • docs/agent-closed-backlog.md
  • docs/agent-lessons-learned.md
  • run_setup.bat
  • tests/test_exe_hint_rerun.py
  • tools/exe_hint_rerun.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 (uv-dl-fallback)
  • GitHub Check: Batch syntax/run check (contract-uv)
  • GitHub Check: Batch syntax/run check (conda-full)
  • GitHub Check: Batch syntax/run check (contract-uv-fail)
  • GitHub Check: Batch syntax/run check (justme-test)
  • GitHub Check: Batch syntax/run check (real)
  • GitHub Check: Batch syntax/run check (uv)
  • GitHub Check: Batch syntax/run check (cache)
🧰 Additional context used
📓 Path-based instructions (13)
**/*

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

  • tools/exe_hint_rerun.ps1
  • tests/test_exe_hint_rerun.py
  • docs/agent-closed-backlog.md
  • run_setup.bat
  • docs/agent-lessons-learned.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:

  • tools/exe_hint_rerun.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:

  • tools/exe_hint_rerun.ps1
  • tests/test_exe_hint_rerun.py
  • 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:

  • tools/exe_hint_rerun.ps1
  • tests/test_exe_hint_rerun.py
  • run_setup.bat
**/*.{bat,ps1,py,yml,json}

📄 CodeRabbit inference engine (CLAUDE.md)

Use ASCII-only content; avoid emojis, curly quotes, em-dashes, and other non-ASCII characters.

Files:

  • tools/exe_hint_rerun.ps1
  • tests/test_exe_hint_rerun.py
  • run_setup.bat
**/*.{bat,ps1}

📄 CodeRabbit inference engine (CLAUDE.md)

Use CRLF line endings for batch and PowerShell files.

Files:

  • tools/exe_hint_rerun.ps1
  • run_setup.bat
**/*.{py,bat,ps1}

📄 CodeRabbit inference engine (CLAUDE.md)

Before commits, run compilation/static checks, delimiter validation, PowerShell parsing, unit tests, workflow linting, and an ASCII sweep covering all changed files.

Files:

  • tools/exe_hint_rerun.ps1
  • tests/test_exe_hint_rerun.py
  • run_setup.bat
**/*.{py,sh}

📄 CodeRabbit inference engine (AGENTS.md)

Use python -m compileall -q ., python -m pyflakes ., and the canonical pipreqs command pipreqs . --force --mode compat --savepath requirements.auto.txt for relevant sanity checks.

Files:

  • tests/test_exe_hint_rerun.py
tests/test_*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Python unit tests should use the tests/test_.py naming convention and be run with pytest.

Files:

  • tests/test_exe_hint_rerun.py
**/*.{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-lessons-learned.md
docs/agent-*.md

📄 CodeRabbit inference engine (CLAUDE.md)

When a change teaches or invalidates a lesson, update the relevant knowledge document in the same commit; edit existing entries rather than only appending. Move fully resolved backlog items to docs/agent-closed-backlog.md.

Files:

  • docs/agent-closed-backlog.md
  • docs/agent-lessons-learned.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 for embedded helpers; update embedded payloads using python tools/sync_payload.py rather than manually encoding or splicing them.
Run python tools/check_delimiters.py run_setup.bat after every edit.
Pass --override-channels -c conda-forge on every conda installation or invocation that selects packages.
Invoke conda through call "%CONDA_BAT%" ... so the parent batch process continues running.
Avoid EnableDelayedExpansion; if it is necessary, scope it tightly.
Use tilde-prefixed temporary and generated files such as ~setup.log and ~bootstrap.status.json.
Every bootstrap run must write ~bootstrap.status.json with state set to ok, no_python_files, or error, plus exitCode and pyFiles fields.
Never depend on console scripts during bootstrap; anchor every tool invocation to an explicit interpreter path such as %HP_PY% or %CONDA_PREFIX%\python.exe.
Invoke pipreqs as python -m pipreqs.pipreqs, not through the pipreqs console script, and retain the pinned pipreqs version 0.4.13 unless its compatibility constraint is re-evaluated.
Bootstrap must fail fast and explicitl...

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
🧠 Learnings (2)
📓 Common learnings
Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-01T11:41:23.448Z
Learning: Do not duplicate content from README.md, AGENTS.md, or CONTRIBUTING.md; reference those authoritative sources instead.
Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-08-01T11:41:23.448Z
Learning: Freeze scope for the current iteration loop; defer new requirements to the backlog, fix CI before tests and product code, implement one missing feature slice, and add 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/agent-closed-backlog.md
🪛 ast-grep (0.45.0)
tests/test_exe_hint_rerun.py

[error] 61-69: Command coming from incoming request
Context: subprocess.run(
[PWSH, "-NoProfile", "-NonInteractive", "-File", str(SOURCE)],
cwd=str(dist),
env=env,
stdin=stdin_src,
capture_output=True,
text=True,
timeout=timeout,
)
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(subprocess-from-request)


[warning] 60-60: File path is request-/variable-derived; validate and normalize to prevent path traversal.
Context: open(script, "r", encoding="utf-8")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').

(open-filename-from-request)

🪛 PSScriptAnalyzer (1.25.0)
tools/exe_hint_rerun.ps1

[warning] 50-50: Empty catch block is used. Please use Write-Error or throw statements in catch blocks.

(PSAvoidUsingEmptyCatchBlock)


[warning] 60-60: Empty catch block is used. Please use Write-Error or throw statements in catch blocks.

(PSAvoidUsingEmptyCatchBlock)


[warning] 61-61: Empty catch block is used. Please use Write-Error or throw statements in catch blocks.

(PSAvoidUsingEmptyCatchBlock)

🪛 Ruff (0.16.0)
tests/test_exe_hint_rerun.py

[warning] 47-47: Missing return type annotation for private function _make_script

(ANN202)


[warning] 53-53: Missing return type annotation for private function _run_hint_rerun

(ANN202)


[warning] 61-61: Unnecessary mode argument

Remove mode argument

(UP015)


[error] 62-62: subprocess call: check for execution of untrusted input

(S603)


[warning] 62-62: subprocess.run without explicit check argument

Add explicit check=False

(PLW1510)


[warning] 73-73: Missing return type annotation for private function _out_path

(ANN202)

Comment thread run_setup.bat
Comment thread tests/test_exe_hint_rerun.py Outdated
Comment thread tools/exe_hint_rerun.ps1 Outdated
…tput path

Two real findings from CodeRabbit's review of the item-15 fix:

1. Process.Kill() only terminates the immediately-tracked process, not
   descendants -- a spawned child inheriting the redirected stdout/stderr
   pipe (e.g. from a PyInstaller onefile bootloader) can keep it open
   after the parent is killed, hanging the previously-unbounded
   ReadToEndAsync().Result forever and defeating the point of the fix.
   Fixed with taskkill /F /T /PID (process-tree kill) plus an independent
   bounded final read (Task.Wait) as a second safety net.

2. :exe_smokerun_hints never explicitly set HP_HINT_RERUN_OUT before
   invoking the helper, relying on its default -- an inherited/leaked
   value for that env var could silently redirect output away from the
   file the hint-matching findstr checks actually read. Fixed by setting
   it explicitly at the call site.

New test: ProcessTreeAndDrainTimeout, using a grandchild process that
inherits the pipe and outlives its own parent, proving the drain-wait
fallback bounds the hang even when taskkill's process-tree behavior
can't be exercised in this sandbox (no Windows environment available).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW
Two Windows-only bugs surfaced across every CI lane, neither reproducible
on Linux: the 8s upper bound for the HP_HINT_RERUN_KILL_MS-override
assertion was too tight for a loaded runner (observed 9.235s for a 500ms
kill window, mostly pwsh/taskkill.exe startup overhead) -- widened to 13s,
which still fails hard if the override were silently ignored. And the
grandchild-holds-pipe regression test's own tempfile.TemporaryDirectory()
cleanup failed with PermissionError/WinError 5/32, since the deliberately
orphaned sleeping grandchild's CWD is an open directory handle on Windows
(not an issue on POSIX) -- switched to a manual mkdtemp + best-effort
ignore_errors=True rmtree, since the test's own assertions already prove
the behavior under test and a leftover temp dir is a harmless CI artifact.

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

Copy link
Copy Markdown
Owner Author

CI was red across every Windows lane on the previous commit (e0691a7), all from the same two bugs in this PR's own new tests/test_exe_hint_rerun.py -- both are Windows-only and couldn't have been caught from this sandbox (no real Windows environment available for local verification):

  1. UnconditionalKill.test_hang_after_output_is_ALSO_killed_unlike_exe_smokerun: AssertionError: 9.235000000000014 not less than 8 -- the 8s upper bound for the HP_HINT_RERUN_KILL_MS=500 override assertion was too tight for a loaded real CI runner (pwsh startup + the new taskkill.exe process-tree kill both add real overhead beyond the intended 500ms window). Widened to 13s, which still fails hard if the override were silently ignored (10000ms default + the same overhead would land near 19s).
  2. ProcessTreeAndDrainTimeout.test_grandchild_holding_pipe_open_does_not_hang_forever: PermissionError: [WinError 32/5] on tempfile.TemporaryDirectory()'s own cleanup. This test deliberately leaves a sleeping grandchild process alive (that's the whole point of the regression test), and on Windows a process's CWD is an open directory handle -- rmtree can't delete a directory a live process is sitting in, unlike POSIX. Switched to manual mkdtemp() + best-effort ignore_errors=True cleanup in finally; the test's own assertions already prove the behavior under test, so a leftover temp dir is a harmless CI-runner artifact.

Fixed in daafe9c. Bonus: since this now runs on real Windows CI (confirmed clean returncode/timing on the cache/contract-uv-fail lanes before the cleanup-only failure), the taskkill /T process-tree-kill path itself is now indirectly exercised there too -- updated that test's own comment, which previously said this was Linux-sandbox-only.


Generated by Claude Code

claude added 2 commits August 1, 2026 12:30
…st_effort

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW
…essons-learned.md

Bundled onto this branch per this repo's own established practice of landing
multiple independently-ready fixes together rather than idling on separate
PRs while a long CI cycle (real/conda-full lanes run ~80-90 min) is already
in flight -- see PR #408's own precedent for the same reasoning.

Item 12: :embed_dl_retry's genuine mid-download-failure-then-retry-once path
had no CI test hook. Added HP_TEST_FORCE_EMBED_DL_FAIL_ONCE (mirrors the
existing HP_TEST_FORCE_CONDA_CREATE_NETWORK_FAIL one-shot-then-succeed
pattern) plus a new self.embed.dl.retry scenario in
tests/selfapps_ux_hardening.ps1 proving retry-then-succeed end-to-end.

Item 13: self.warn.longpath silently reported an overall pass even when the
bootstrap never actually ran (ranBootstrap:false) -- root-caused to
PowerShell's Push-Location failing before cmd /c is ever reached, since
default GitHub-hosted Windows runners don't have LongPathsEnabled. Confirmed
persistent via a second real CI observation (this session's own PR #410
runs) matching the original finding's exact signature. Fixed by reporting
skip=true instead of an overstated pass when the runner cannot even attempt
the code path under test, mirroring this repo's established skip-pattern
convention.

Doc compression (user request, tracked internally all session): trimmed
discovery-narrative and superseded-implementation history from
docs/agent-lessons-learned.md (1404 -> 1105 lines) and
docs/agent-interconnect.md (1827 -> 1355 lines) while preserving every
hazard, rule, exact error string, flag name, and table -- these two files
are auto-loaded into every future agent session's context via CLAUDE.md's
@import mechanism, so their size is a per-session cost for every future
agent working in this repo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW
@mixmansoundude mixmansoundude changed the title Bound :exe_smokerun_hints' diagnostic re-run with a timeout (backlog item 15) Bound :exe_smokerun_hints' rerun timeout; close backlog items 12/13; compress agent docs Aug 1, 2026
New tests/selfapps_pvw_overrides.ps1 (uv lane only, non-gating) covers the
two previously-zero-coverage PVW_* super-user overrides in full per the
backlog item's own suggested shape: valid-value paths for both variables,
plus 2 representative invalid-value scenarios (a nonexistent
PVW_PYTHON_EXE absorbed by the existing interpreter smoke-test WARN, and a
PVW_WORKSPACE occupied by a file cascading to the established
:uv_venv_fail -> conda-create fallback) rather than the full 5x2
combinatorial matrix, matching the item's own reasoning that the
failure-absorption mechanism is shared/generic across most combinations.

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 `@docs/agent-interconnect.md`:
- Around line 827-830: Update the documentation around :run_exe_smokerun and
run_postexec_checkpoint to describe the timed EXE smoke as the primary
verification, not the sole or at-most-once verification; explicitly note that an
accepted checkpoint may launch an optional second user-code run.
- Around line 889-900: Update the HP_PROBE_ARGS documentation in both referenced
sections to use a single caller-owned quoting contract: callers must provide a
ready-to-use argument string, and :run_failfast_probe must assign it verbatim
without adding quotes. Remove the stale raw/unquoted argument description and
clarify that multiple arguments must remain separate tokens.
- Around line 326-335: Update the provider-cascade documentation to consistently
place embed before venv and system in the fallback order. Remove the documented
:cascade_from_system-to-:try_embed_fallback flow and any claim that system
cascades to embed when system is terminal; revise the related sections around
the cascade order and call sites to match the actual implementation.
- Around line 550-552: Update the contract description for
tools/autopep_merge.py::main to state that it normally returns 0 for no-op and
successful paths, but may exit nonzero when an OSError from file reads or writes
is uncaught. Preserve the “never gates the lane” behavior by documenting that
run_setup.bat continues with pipreqs-only results after such a failure, and
qualify the existing “always exits 0” wording accordingly.

In `@docs/agent-lessons-learned.md`:
- Around line 52-57: Add blank lines immediately before and after the fenced bat
code block in the documented CI failure example, preserving the existing code
content and surrounding prose.
🪄 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: a7c0ba43-c4e3-40b9-b158-fc198171cefa

📥 Commits

Reviewing files that changed from the base of the PR and between daafe9c and cd89840.

📒 Files selected for processing (11)
  • .github/workflows/batch-check.yml
  • CLAUDE.md
  • docs/agent-closed-backlog.md
  • docs/agent-interconnect.md
  • docs/agent-lessons-learned.md
  • docs/agent-ndjson.md
  • run_setup.bat
  • tests/selfapps_pvw_overrides.ps1
  • tests/selfapps_ux_hardening.ps1
  • tests/selftest.ps1
  • tests/test_exe_hint_rerun.py
💤 Files with no reviewable changes (1)
  • CLAUDE.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (17)
**/*

📄 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 sanity sweep before every commit, extending the ASCII file list to cover files touched by the current change.
Freeze scope for the current iteration loop; defer new requirements to the backlog, fix CI before test failures and product code, implement exactly one missing feature slice, and add exactly one missing test per loop.
When a change teaches or invalidates a lesson, update the relevant knowledge document in the same commit; move fully resolved Active Backlog items to docs/agent-closed-backlog.md.

Files:

  • tests/selfapps_pvw_overrides.ps1
  • tests/selftest.ps1
  • tests/selfapps_ux_hardening.ps1
  • tests/test_exe_hint_rerun.py
  • run_setup.bat
  • docs/agent-closed-backlog.md
  • docs/agent-ndjson.md
  • docs/agent-lessons-learned.md
  • 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/selfapps_pvw_overrides.ps1
  • tests/selftest.ps1
  • tests/selfapps_ux_hardening.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/selfapps_pvw_overrides.ps1
  • tests/selftest.ps1
  • tests/selfapps_ux_hardening.ps1
  • tests/test_exe_hint_rerun.py
  • 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/selfapps_pvw_overrides.ps1
  • tests/selftest.ps1
  • tests/selfapps_ux_hardening.ps1
  • tests/test_exe_hint_rerun.py
  • run_setup.bat
**/*.{bat,cmd,ps1}

📄 CodeRabbit inference engine (CLAUDE.md)

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

Files:

  • tests/selfapps_pvw_overrides.ps1
  • tests/selftest.ps1
  • tests/selfapps_ux_hardening.ps1
  • run_setup.bat
**/*.{bat,cmd,ps1,py,yml,json}

📄 CodeRabbit inference engine (CLAUDE.md)

Tag non-obvious constraints with comments in the form # derived requirement: <why> so future changes do not regress subtle fixes.

Files:

  • tests/selfapps_pvw_overrides.ps1
  • tests/selftest.ps1
  • tests/selfapps_ux_hardening.ps1
  • tests/test_exe_hint_rerun.py
  • run_setup.bat
**/tests/**/*.ps1

📄 CodeRabbit inference engine (CLAUDE.md)

Wire new PowerShell scenario tests into tests/harness.ps1 and the relevant batch-check.yml job steps.

Files:

  • tests/selfapps_pvw_overrides.ps1
  • tests/selftest.ps1
  • tests/selfapps_ux_hardening.ps1
**/*.ps1

📄 CodeRabbit inference engine (CLAUDE.md)

Validate PowerShell syntax using the PowerShell parser; CI must not download from PSGallery and should use syntax-only validation instead.

Files:

  • tests/selfapps_pvw_overrides.ps1
  • tests/selftest.ps1
  • tests/selfapps_ux_hardening.ps1
**/.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 modified GitHub Actions workflows with both yamllint and actionlint before committing.

Files:

  • .github/workflows/batch-check.yml
**/*.{py,sh}

📄 CodeRabbit inference engine (AGENTS.md)

Use python -m compileall -q ., python -m pyflakes ., and the canonical pipreqs command pipreqs . --force --mode compat --savepath requirements.auto.txt for relevant sanity checks.

Files:

  • tests/test_exe_hint_rerun.py
**/tests/test_*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Place Python unit tests in files named tests/test_<topic>.py.

Files:

  • tests/test_exe_hint_rerun.py
**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Run Python compilation and lint checks (python -m compileall -q . and python -m pyflakes .) before committing.

Files:

  • tests/test_exe_hint_rerun.py
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.

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
**/run_setup.bat

📄 CodeRabbit inference engine (CLAUDE.md)

**/run_setup.bat: Keep run_setup.bat self-contained: helper logic must be base64-encoded inside :define_helper_payloads; update embedded helpers with python tools/sync_payload.py HP_VARNAME tools/the_file.py rather than hand-editing encoded payloads.
Run python tools/check_delimiters.py run_setup.bat after every edit to run_setup.bat.
Every conda invocation in run_setup.bat must use call "%CONDA_BAT%" ... so the parent batch process continues.
All conda installs must include --override-channels -c conda-forge; do not allow defaults-channel contamination.
Do not depend on console scripts during bootstrap; invoke tools through an explicit interpreter path or direct Python module/API, such as python -m pipreqs.pipreqs.
Anchor every bootstrap tool invocation to an explicit Python executable such as %HP_PY% or %CONDA_PREFIX%\python.exe; never rely on PATH or activation to select the interpreter.
Bootstrap must fail fast and explicitly when interpreter, environment, or dependency availability cannot be guaranteed; do not use silent fallbacks unless they are explicitly logged.
Preserve the bootstrap status contract: every run writes ~bootstrap.status.json with state equal to ok, no_python_files, or error, plus exitCode and pyFiles fields.
Avoid EnableDelayedExpansion; if it is necessary, scope it tightly to avoid collisions with parent shells using /V:ON.
Test all three bootstrap code paths—cache, real, and conda-full—after significant changes by checking CI results across all lanes.

Files:

  • 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-lessons-learned.md
  • 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
🪛 markdownlint-cli2 (0.23.1)
docs/agent-lessons-learned.md

[warning] 54-54: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)


[warning] 57-57: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

docs/agent-interconnect.md

[warning] 198-198: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)


[warning] 199-199: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above

(MD022, blanks-around-headings)

🪛 PSScriptAnalyzer (1.25.0)
tests/selfapps_pvw_overrides.ps1

[warning] 30-30: The cmdlet 'Invoke-WithEnvOverrides' uses a plural noun. A singular noun should be used instead.

Suggested fix: Singularized correction of 'Invoke-WithEnvOverrides'

(PSUseSingularNouns)

tests/selfapps_ux_hardening.ps1

[warning] 1046-1046: The variable 'embedRetryLog' is assigned but never used.

(PSUseDeclaredVarsMoreThanAssignments)

🔇 Additional comments (12)
docs/agent-interconnect.md (1)

24-129: LGTM!

Also applies to: 149-173, 201-325, 336-366, 393-401, 527-549, 554-609, 610-702, 719-725, 750-752, 875-887, 901-938, 946-1003, 1005-1049, 1051-1089, 1091-1099, 1115-1167, 1169-1213, 1233-1307, 1328-1334

docs/agent-lessons-learned.md (1)

26-51: LGTM!

Also applies to: 58-193, 263-266, 306-321, 331-344, 355-367, 384-406, 416-416, 461-470, 479-516, 571-586, 777-778, 794-879, 918-924, 981-985, 1019-1041, 1054-1058, 1096-1096

run_setup.bat (3)

264-268: LGTM!

Also applies to: 2250-2277


4021-4157: LGTM!


4123-4157: 🗄️ Data Integrity & Integration

No delimiter issue found in run_setup.bat. The delimiter check passes.

			> Likely an incorrect or invalid review comment.
tests/test_exe_hint_rerun.py (1)

25-39: LGTM!

tests/selfapps_ux_hardening.ps1 (1)

1020-1095: LGTM!

tests/selfapps_pvw_overrides.ps1 (1)

1-378: LGTM!

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

684-694: LGTM!

docs/agent-ndjson.md (1)

75-75: LGTM!

Also applies to: 235-235, 307-347, 671-678

tests/selftest.ps1 (1)

686-722: LGTM!

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

758-925: LGTM!

Comment thread docs/agent-interconnect.md Outdated
Comment thread docs/agent-interconnect.md Outdated
Comment thread docs/agent-interconnect.md
Comment thread docs/agent-interconnect.md Outdated
Comment thread docs/agent-lessons-learned.md
…regressions from compression

The wall-clock timing assertion in tests/test_exe_hint_rerun.py's
UnconditionalKill class kept flaking upward across real Windows CI runs
(9.235s, 13.468s, 14.578s, 16.328s of overhead for the identical 500ms
override, never converging) -- bumping the bound was chasing a moving
target instead of fixing the actual problem: the test was inferring
correctness from noisy wall-clock time it can't control.

Fixed by having tools/exe_hint_rerun.ps1 write its resolved $killMs
directly to a new HP_HINT_RERUN_KILLMS_OUT file, unconditionally, right
after computing it (production callers never read it, so this costs
nothing there). The test now asserts on that value directly -- proving
the override was read and used, deterministically, with zero CI-load
dependency. A loose 45s wall-clock ceiling remains only as a sanity net
against the kill mechanism being completely broken.

Also fixes 3 real documentation regressions CodeRabbit's review caught in
the doc-compression pass on this same PR: a stale HP_PROBE_ARGS contract
description in one section that contradicted the (correct) description
in another after the Argv passthrough feature changed it; a provider-
cascade call-site list that still described the pre-reorder order
(embed after venv/system instead of right after conda) because the
compression pass dropped the sentence marking it as historical; and an
"always exits 0" claim about tools/autopep_merge.py that doesn't hold --
two of its open() calls aren't wrapped in try/except OSError, unlike a
third one that is.

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

Copy link
Copy Markdown
Owner Author

Redesigned the flaky timing test and fixed the doc-review findings in 721df58:

Timing fix (root cause, not another guessed bound): UnconditionalKill's wall-clock assertion had failed 4 times across different real CI runs at 4 different elapsed values (9.2s, 13.5s, 14.6s, 16.3s) for the identical HP_HINT_RERUN_KILL_MS=500 override -- clearly not converging, so bumping the bound again wasn't going to fix it. tools/exe_hint_rerun.ps1 now writes its resolved $killMs to a dedicated file (HP_HINT_RERUN_KILLMS_OUT) right after computing it, unconditionally -- production callers never read it, so this is zero-cost there. The test now asserts on that value directly instead of inferring it from timing, which removes CI-runner noise from the assertion entirely. A loose 45s ceiling remains only as a sanity check that the kill mechanism isn't completely broken.

Doc findings, all verified against source before fixing:

  • HP_PROBE_ARGS stale contract (Major) -- confirmed. Fixed the earlier section to match the correct, later one.
  • Provider-cascade call-site list describing the pre-reorder order (Minor) -- confirmed; my compression pass on this PR dropped the sentence marking that list as historical. Rewrote it to match current code.
  • autopep_merge.py "always exits 0" claim (Minor) -- verified against actual source: existing_names()'s and main()'s open() calls aren't wrapped in try/except OSError, unlike extract_autopep_deps(), which is. Corrected the claim; run_setup.bat's own behavior (continue with pipreqs-only results) is unaffected either way.
  • "Sole verification"/"at most once" wording (Minor) -- confirmed genuinely ambiguous against the documented elective post-execution checkpoint. Qualified as "primary (mandatory) verification."

The MD031 markdownlint nitpick is intentionally left as-is per the policy just established in this thread (non-root .md style nitpicks are out of scope unless a hard render error).


Generated by Claude Code

@mixmansoundude
mixmansoundude merged commit 734a50a into main Aug 1, 2026
16 checks passed
@mixmansoundude
mixmansoundude deleted the claude/bootstrapper-execution-branches-ox2izi branch August 1, 2026 18:27
mixmansoundude added a commit that referenced this pull request Aug 2, 2026
…411)

* Release-prep pass: reorg demo doc, fix stale content, small product fixes

docs/demo-bootstrapper-output.md:
- Complete the owner-requested reorg TODO: move the "no .py files" scenario
  to the front as the doc's simplest, most foundational case; push the
  AV-Safe Build Path and CLI-interactivity Parts to the end. All 38
  scenarios renumbered, table of contents and cross-references rebuilt to
  match, done as a flow-only pass with no scenario content changed.
- Add a house-style note to the intro: describe current behavior, not the
  doc's own revision history -- drop hedges like "not yet re-confirmed
  against a fresh capture" and internal backlog-item bookkeeping from
  scenario prose; real historical gotchas stay welcome.
- Remove a stale "[WARN] UNC paths not supported" console line from three
  capture blocks (the broken check that produced it was already removed
  from run_setup.bat) and trim the now-inapplicable explanation.
- Update the long-path guard writeup to reflect this session's fix to
  self.warn.longpath (now correctly reports skip:true instead of an
  inconclusive pass) and fill in a concrete example path length.
- Update PVW_PYTHON_EXE/PVW_WORKSPACE and the embed-tier download-retry
  scenarios to reflect real CI coverage added this session (previously
  documented as untested/extrapolated).
- Add a new Part with five full startup-to-shutdown walkthrough panels:
  the ordinary happy path, uv cascading to conda on a dependency-resolve
  failure, warnfix repair+rebuild, hidden-import auto-recovery, and
  HP_PVW_KNOWN_IDEMPOTENT with actual input/output file contents.

run_setup.bat:
- :pick_entry_interactive now prints the same "Tip: to skip this question
  next time" guidance in the >9-candidate-files branch, not just the
  normal picker menu -- it's the guidance a user who just hit that limit
  needs most.

tools/exe_hint_rerun.ps1:
- Update a stale header comment: the descendant-holds-the-pipe taskkill /T
  path is now confirmed exercised on real Windows CI (two lanes on
  PR #410), not just the drain-wait fallback.

docs/agent-closed-backlog.md:
- Add a note that Part/Scenario citations in historical entries reflect
  the demo doc's structure at the time each entry was written, since the
  reorg above renumbered everything.

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

* Address CodeRabbit review: fix stale TOC anchors, MD031, wording, add >9-picker test

- Fix Part VI's own local scenario index: 4 links still pointed at the
  pre-reorg anchors (#scenario-34.. through #scenario-37..) even though
  their visible text had already been renumbered to 28-31. The main table
  of contents was verified programmatically during the reorg; this local
  bulleted list inside Part VI's scope note was a second, separate index
  the check didn't cover. Verified no other stale anchors exist anywhere
  else in the file via a full anchor-vs-header scan.
- Fix 2 markdownlint MD031 violations (missing blank lines around fences).
- Trim a residual mechanism claim from the UNC-check writeup (the removed
  check's exact findstr/backslash-parsing behavior was never independently
  verified, per an existing CodeRabbit learning from PR #408).
- Extend the sourcing-convention paragraph to explicitly cover Part VII's
  composite walkthroughs (spliced from independently-real fragments) as a
  third case, distinct from a verbatim capture or a source-only quote.
- Fix run_setup.bat's new >9-candidates Tip wording: "to avoid the
  alphabetical fallback next time" instead of "to skip this question next
  time" -- no question was actually asked in that branch.
- Add tests/selfapps_entry_picker.ps1's second scenario (self.entry.picker.
  overflow): stages 10 candidate files, asserts the numbered menu is
  skipped, the overflow log line and Tip guidance both fire, and the
  alphabetical default is kept. Closes the CI-coverage gap the demo doc
  itself flagged. Registered in docs/agent-ndjson.md.

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

* Address second CodeRabbit review round: sourcing labels, stale coverage note

- Sourcing convention: use explicit REAL CI CAPTURE / source-excerpt /
  [Extrapolated Branch] labels instead of prose that called a source-only
  excerpt a "job log" -- a source excerpt is not a CI capture and
  shouldn't be described as one.
- Scenario 28's >9-candidates paragraph still said "a real coverage gap,
  not yet a dedicated test" after the previous commit had already added
  self.entry.picker.overflow -- fixed to point at the real test/NDJSON
  registration while keeping [Extrapolated Branch] for the exact console
  text (that test only dumps a full log to CI on failure).

Declined (reason given inline, no code change): CodeRabbit's outside-diff
suggestion to add an explicit `exit 0` to tools/exe_hint_rerun.ps1. Its
caller (run_setup.bat's EXE-hint-rerun call site) never checks the
PowerShell process's own exit code, and three commands run before the
first `if errorlevel` check that matters afterward (each of which resets
ERRORLEVEL), so the omission is provably inconsequential. Neither sibling
helper (exe_smokerun.ps1, failfast_probe.ps1) has an explicit exit code
either -- adding one here alone would be inconsistent with an established,
already-shipped pattern rather than fixing a real gap.

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

* Make cache-lane self-heal regression-testable and its outcome visible

Owner asked whether Item 19's cache self-heal fix is holding, then asked
for a way to make a regression in it actually surface -- not silently
absorbed. Digging into the first real post-fix run's raw job log found
direct proof the fix works (corrupted-prefix-match cache -> deleted ->
fresh install -> fresh save, all in one run), but also confirmed two real
gaps: nothing recorded whether a run's self-heal fired at all, and even a
hard failure inside the `cache` lane could never surface as a real CI
failure (job-level continue-on-error covers that whole lane).

- Extract the inline health-check-and-heal PowerShell out of
  batch-check.yml into tools/ci_cache_selfheal.ps1, a small parameterized
  script with 4 distinct exit codes -- including a new one for "self-heal
  itself failed to clear the stale directory" (the regression case: this
  fix reverting to its own pre-fix trap).
- Add tests/test_ci_cache_selfheal.ps1: a deterministic test exercising
  all 4 outcomes against a scratch temp directory (including a genuine
  locked-file reproduction of the heal-failure case), wired into the
  `real` lane -- a GATING lane -- so a regression here fails CI for real,
  unlike the ambient `cache` lane which structurally cannot.
- Add self.cache.selfheal.fired: an always-emitted visibility row when
  the ambient cache lane's own self-heal branch fires, recording whether
  it actually succeeded -- queryable on the diagnostics site instead of
  requiring a raw-log dig to notice an organic occurrence happened.
- Add a loud ::error:: tripwire for the self-heal-failed case, mirroring
  the existing diag.conda.available.gate pattern -- explicitly documented
  as not a substitute for the gating test above.
- Document the investigation and the fix in docs/agent-closed-backlog.md's
  Item 19 entry (in place, not appended), including the exact log lines
  that proved the original fix fired and worked.

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

* Address CodeRabbit review: 5th cache-selfheal scenario, doc provenance fixes

- tests/test_ci_cache_selfheal.ps1: add the missing "no conda.bat present
  at all" scenario -- exit code 0 covered two distinct branches in
  ci_cache_selfheal.ps1 but only one (healthy) had a test.
- docs/agent-ndjson.md: fix a mid-identifier line break inside a code
  span (HP_CACHE_SELFHEAL_ATTEMPTED).
- docs/demo-bootstrapper-output.md: Scenario 40a claimed its console dump
  was "verbatim" while also saying one line was "updated in place" --
  a real self-contradiction; reworded to state plainly which line was
  edited and which lines are real capture. Scenario 37 reworded to lead
  with the mixed-provenance framing instead of an unqualified "real CI"
  claim. Scenario 41's cross-reference incorrectly claimed Scenario 37
  shows the same WARN line "in situ" -- it actually shows the
  "(fallback build system)" variant, not "(PyInstaller)"; fixed.

Declined (reasons given inline on the PR, no code change):
- CodeRabbit's actionlint failure claim at batch-check.yml:3512 (if:
  false) does not reproduce -- actionlint v1.7.1 runs clean locally
  against that exact line, which is also pre-existing, documented,
  intentional code (a toggle switch), not part of this PR's diff.
- PSScriptAnalyzer's ShouldProcess nag on New-FakeCondaDir -- no other
  test helper in this repo implements ShouldProcess (not a repo-native
  check), and it's disproportionate for a private, unconditionally-
  invoked test-only helper.

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

* Guard against silent fixture-creation failure in cache-selfheal test

Address CodeRabbit's outside-diff finding: New-FakeCondaDir used
-ErrorAction SilentlyContinue throughout, so a silently-failed Set-Content
would leave the fixture directory with no conda.bat -- which
ci_cache_selfheal.ps1 correctly treats as a genuine cache miss (exit 0),
the same exit code Scenario 1 expects for a HEALTHY conda.bat. That made
fixture-creation failure indistinguishable from success instead of
failing the test loudly.

Declined the broader $ErrorActionPreference = 'Stop' sweep proposed
alongside it (reason given inline on the PR): making cleanup
(Remove-Item -ErrorAction SilentlyContinue at setup and final teardown)
fail-fast would be inconsistent with how every other selfapps test in
this repo treats scratch-directory cleanup as best-effort, and could
introduce new flakiness on real Windows CI against exactly the
AV/indexer file-lock class this repo already designs around elsewhere
(see docs/agent-lessons-learned.md). Targeted the actual described
failure mode instead: verify the fixture exists after creation, throw
if not.

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

* Assert Scenario 5's cache dir genuinely starts empty

Address CodeRabbit's follow-up finding: New-Item -Force on $dir5 doesn't
clear pre-existing content, so a leftover conda.bat from a prior
interrupted run (surviving both that run's own best-effort teardown and
this run's top-level scratchRoot recreation) could make Scenario 5
silently exercise the wrong branch while still passing on rc==0. Adds an
explicit pre-invocation assertion that neither condabin\conda.bat nor
Scripts\conda.bat exist before calling the script, throwing if they do.

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

---------

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants