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

.github/workflows/batch-check.yml

@@ -681,6 +681,17 @@ jobs:
         run: |
           & tests\selfapps_pvw_idempotent.ps1
 
+      # CLAUDE.md former Active Backlog item 10: PVW_PYTHON_EXE and PVW_WORKSPACE had ZERO test
+      # coverage of any kind, unlike the other three PVW_* super-user overrides. Non-gating for
+      # its first landing, matching this repo's established graduation pattern for a new
+      # PowerShell scenario not yet proven stable across several real runs.
+      - name: "Self-test: PVW_PYTHON_EXE / PVW_WORKSPACE super-user overrides (uv lane only)"
+        if: ${{ matrix.mode == 'uv' }}
+        continue-on-error: true
+        shell: pwsh
+        run: |
+          & tests\selfapps_pvw_overrides.ps1
+
       - name: "Self-test: pre-build collect-submodules double-gate (real/conda-full only)"
         if: ${{ !cancelled() && (matrix.mode == 'real' || (matrix.mode == 'conda-full' && steps.conda_avail.outputs.available == 'true')) }}
         shell: pwsh

CLAUDE.md

@@ -492,107 +492,6 @@ Once an item is fully resolved it is removed from here entirely and archived (ke
 original number) in `docs/agent-closed-backlog.md`, which is why the numbering below does not
 start at 1 and has gaps.
 
-- **10. Two of the five `PVW_*` super-user override variables (`PVW_PYTHON_EXE`, `PVW_WORKSPACE`)
-   have ZERO test coverage of any kind, and ALL FIVE have zero coverage of their invalid-value
-   behavior -- found 2026-07-29 while documenting them for `docs/demo-bootstrapper-output.md`'s
-   Part V.** Confirmed via a repo-wide search across every `tests/*.ps1` file and every lane of a
-   recent clean CI run (`30328748330`): `PVW_PYTHON_EXE` and `PVW_WORKSPACE` have zero references
-   anywhere -- not even a valid-value smoke test. `PVW_UV_EXE` (`tests/selfapps_contract_uv.ps1`)
-   and `PVW_TARGET_PY` (`tests/selfapps_pipgap.ps1`) each have real, valid-value end-to-end CI
-   coverage, but that coverage is incidental to each test's own actual purpose (avoiding a
-   redundant uv re-download; pinning a Python version for an unrelated opencv-python wheel test),
-   not a dedicated test of the override mechanism itself. `PVW_CONDA_EXE` is the one exception with
-   dedicated, purpose-built coverage (`self.corrupt.conda.override_exit`, CLAUDE.md's own earlier
-   Active Backlog item 12 history).
-   - **No test anywhere exercises an INVALID value for any of the five** -- e.g. `PVW_PYTHON_EXE`
-     pointing at a nonexistent file, `PVW_UV_EXE` pointing at something that isn't actually uv,
-     `PVW_TARGET_PY` set to a malformed version spec, `PVW_WORKSPACE` pointing at an unwritable or
-     already-occupied-by-something-else path. Static tracing (done for the demo doc, see Part V)
-     shows each case is plausibly absorbed gracefully by pre-existing fallback/cascade machinery
-     (the REQ-009 provider cascade, the `:uv_venv_fail` chain, the interpreter smoke-test WARN),
-     never an uncontrolled crash -- but this is reasoned from source, not empirically confirmed by
-     any real run.
-   - **Not fixed in this pass** -- documentation-only task, and building 5+ new dedicated test
-     scenarios (a `PVW_PYTHON_EXE`-focused test, a `PVW_WORKSPACE`-focused test, plus invalid-value
-     variants for all five) is real, multi-scenario engineering work, not a quick addition. Suggested
-     shape for a future pass: one new `tests/selfapps_pvw_overrides.ps1`-style file (mirroring the
-     existing `tests/selfapps_ux_hardening.ps1`/`...contract_uv.ps1` pattern) covering the two
-     currently-zero-coverage variables' valid-value paths first (cheapest, highest-value gap), then
-     a smaller number of representative invalid-value scenarios (not all 5x2 combinations -- the
-     failure-absorption mechanism is shared/generic across most of them per the static trace above,
-     so 2-3 representative invalid-value cases would likely cover the real risk without a
-     combinatorial test matrix).
-
-- **12. `:embed_dl_retry`'s genuine mid-download-failure-then-retry-once path (REQ-009 Tier 5) has
-   no CI test hook at all -- found 2026-07-29 while documenting the embed-tier download for
-   `docs/demo-bootstrapper-output.md`'s Part VI, Scenario 20.** Confirmed via `run_setup.bat`
-   source and a repo-wide grep: only two test hooks exist for this tier --
-   `HP_TEST_FORCE_EMBED_FAIL` (immediate decline, no download attempted at all) and
-   `HP_TEST_FORCE_EMBED_REAL` (a full, real, successful download end-to-end). Neither exercises
-   the retry branch itself: `:embed_dl_retry`'s own `[WARN] embed fallback: download failed;
-   retrying once.` line (both the curl and PowerShell download attempts failing on the FIRST try,
-   then succeeding on the second) and the sibling checksum/extraction-failure retry branch
-   (`[WARN] embed fallback: checksum verification or extraction failed; retrying download once.`)
-   are both reachable in principle but have never been observed firing in any real CI run
-   examined for this documentation pass -- the demo doc's own Scenario 20 correctly labels the
-   retry-branch text `[Extrapolated Branch]`, cited from source, for exactly this reason. **Not
-   fixed in this pass** -- documentation-only task; a dedicated test would need a new hook (e.g.
-   `HP_TEST_FORCE_EMBED_DL_FAIL_ONCE=1`, mirroring the existing `HP_TEST_FORCE_CONDA_CREATE_
-   NETWORK_FAIL`-style one-shot-then-succeed pattern already used for REQ-022's conda-create
-   retry) that fails the first curl+PowerShell attempt deterministically without touching the
-   real network, then lets the second attempt through for real. Suggested as a small, well-scoped
-   future addition to `tests/selfapps_ux_hardening.ps1` alongside the existing
-   `self.embed.fallback.decline`/`.real` scenarios.
-
-- **13. `self.warn.longpath`'s own real CI run examined for this documentation pass shows an
-   INCONCLUSIVE result (`ranBootstrap:false`), yet the test still reports an overall pass -- found
-   2026-07-29 while documenting the path-length pre-flight guard for
-   `docs/demo-bootstrapper-output.md`'s Part VI, Scenario 24.** The test's own NDJSON row in run
-   `30328748330` (`real` lane) reads `warnFound: false, ranBootstrap: false, pathLen: 312` -- the
-   scratch directory this specific CI run created did not actually reach a state where the
-   sub-bootstrap could run at all (most likely an OS-level path-length limit on the CI runner
-   itself was hit before `run_setup.bat`'s own ~200-char check ever got a chance to fire), yet the
-   test apparently tolerates this as a passing outcome rather than treating it as inconclusive.
-   This means the guard's actual WARN-firing behavior (`*** WARNING: Script path is <N> chars.
-   Paths near 260 chars may cause cmd.exe failures.`) has NOT been positively confirmed by this
-   specific real-CI observation -- the demo doc's own Scenario 24 correctly labels the guard's
-   exact text `[Extrapolated Branch]`, cited from source, for this reason, rather than presenting
-   an inconclusive test result as if it were a real, confirmed capture. **Not fixed in this pass**
-   -- documentation-only task, and root-causing exactly why the scratch directory's own path
-   didn't reach the runner's practical limit (or why the test tolerates `ranBootstrap:false`)
-   needs its own investigation into `tests/selftest.ps1`'s long-path scenario, not a rushed fix
-   folded into an unrelated docs PR. Worth checking in a future pass whether this is a persistent,
-   reproducible gap (in which case the test's own pass/fail logic may need tightening) or a
-   one-off artifact of this particular run's CI-runner path layout.
-
-- **15. `:exe_smokerun_hints`'s diagnostic re-run of a freshly-failed EXE has no timeout, unlike
-   every other user-code launch point in this file -- found 2026-07-31, flagged by a CodeRabbit
-   review on PR #402 while documenting the hint mechanism for
-   `docs/demo-bootstrapper-output.md`'s Scenario 37, verified against source before logging.**
-   `:exe_smokerun_hints` (`run_setup.bat`) does `pushd dist` then `"%ENVNAME%.exe" > "~exe_out.txt"
-   2>&1` with no `.NET Process`/`WaitForExit(ms)`/`Kill()` wrapper at all -- a plain, synchronous,
-   unbounded batch invocation. Every OTHER place in this file that launches a frozen EXE or the
-   interpreter (`:run_exe_smokerun`'s primary verification, `:run_failfast_probe`'s three call
-   sites, `:hidden_import_recover`'s own repair-check re-run) is deliberately bounded, either by
-   the ~30s hard-kill ceiling (the one place this bootstrapper is allowed to `Kill()` a process) or
-   by the fail-fast-probe's classify-then-never-kill design -- this is the one exception. The call
-   site's own guard (`if not "%HP_EXE_EXIT%"=="-1" call :exe_smokerun_hints`, in `:smokerun_ndjson`)
-   only confirms the FIRST launch (inside `:run_exe_smokerun`) exited with a real, non-hang code --
-   it says nothing about whether the SAME program will behave identically on this SECOND, separate
-   launch a few lines later. A program with any non-determinism (a race condition, an environment
-   check that sometimes succeeds, or anything that occasionally blocks on stdin instead of exiting
-   fast) could hang this second, untimed invocation and hang the whole bootstrap, even though the
-   first invocation legitimately fell into the "fast, real, non-hang failure" classification that
-   is this subroutine's own precondition for being called at all. **Not fixed in this pass** --
-   documentation-only task, and the correct fix (reuse the existing bounded-launch pattern, e.g.
-   `tools/exe_smokerun.ps1`'s own `.NET Process` + timeout wrapper, or add an independent
-   termination deadline before the stderr pattern-match) touches `run_setup.bat` itself, out of
-   scope for a docs-only PR. `docs/demo-bootstrapper-output.md`'s Scenario 37 was not changed to
-   caveat this specifically, since the two real captures it documents are both genuine, already-
-   completed runs (the hang risk is about a DIFFERENT, hypothetical program, not about the accuracy
-   of what's shown) -- but a future pass fixing this should also confirm no currently-passing test
-   silently relies on the unbounded behavior before adding a timeout.
-
 ## Cold Storage (promising ideas, deliberately shelved -- revisit only if a named trigger fires)
 
 Moved to `docs/agent-cold-storage.md` (2026-07-31, to reduce this file's per-session context