# Agent Cold Storage -- Python_vs_Windows

**This file is NOT auto-loaded into every session's context** (unlike
`docs/agent-lessons-learned.md` and `docs/agent-interconnect.md`, which CLAUDE.md's own
`@import` lines pull in automatically). Read it on demand: when CLAUDE.md's own pointer below
sends you here, or when you're about to propose something that might already be a deliberately-
shelved idea worth checking against first.

Moved out of `CLAUDE.md` directly (2026-07-31) specifically to reduce that file's per-session
context footprint -- CLAUDE.md is loaded in full every session, so keeping reference-only
material (ideas gated on a trigger that hasn't fired, not something any session needs to act on
by default) here instead measurably shrinks that footprint without losing the content. See
CLAUDE.md's own "Cold Storage" pointer for the one-paragraph scope summary.

---

## Cold Storage (promising ideas, deliberately shelved -- revisit only if a named trigger fires)

**Scope, and how this differs from Active Backlog and Known Findings**: an Active Backlog item is
work this repo intends to get to eventually, with no special precondition beyond bandwidth. A
Known Finding is a settled decision with genuinely no action ever planned. This section is a
third category: a real, technically-sound idea that is NOT being pursued right now, gated on one
or more SPECIFIC, checkable triggers -- not "eventually," not "never," but "only if X happens."
2026-07-26 owner instruction: park these here (rather than either of the other two sections) so
they stay visible without implying either imminent work or a closed door, and thaw one only when
its own named trigger genuinely fires -- do not speculatively build any of these ahead of that.

- **Total build-attempt budget cap across nested repair loops** (hidden-import recovery x
  DLL-bundle recovery x REQ-009 provider-cascade tiers, each with its own iteration cap that
  compounds with the others -- see CLAUDE.md's closed Active Backlog Item 45 and still-open Item 46
  discussion for the no-`HP_PY` case this overlaps with). Raised during a 2026-08-14 real Windows
  Sandbox debugging session as a theoretical concern (many PyInstaller invocations possible in the
  worst case with no single circuit breaker), not a confirmed problem -- the individual loops are
  each already capped
  and this repo's own history with them (CLAUDE.md's DLL-bundling/hidden-import interconnect
  entries) shows real, hard-won caution about touching them without strong justification. **Trigger
  to thaw**: a real CI run or user report showing the repair-loop product actually causing a
  meaningfully long hang or wasted build time, not just the theoretical worst case being
  mathematically possible.

- **Binary presence guards beyond PowerShell** (curl, findstr, robocopy, fc, reg, timeout, ping,
  more, sort, expand, tar). Only `choice.exe` and, as of the 2026-08-14 line-ending self-check
  (CLAUDE.md's former Active Backlog Item 44), `powershell` are checked for presence before use;
  every other external binary this bootstrapper depends on fails as an opaque errorlevel if absent.
  Not pursued now: all of these are core Windows components present by default on any Windows 10+
  install this bootstrapper already targets, so the realistic trigger rate is low relative to the
  PowerShell case (which has a real, known restriction mechanism -- Constrained Language Mode --
  that these do not). **Trigger to thaw**: a real user report of a missing-binary failure on one of
  these specific tools, not a speculative preemptive sweep.

- **PYSPEC-aware venv-vs-embed decision function.** `:try_venv_fallback` currently uses whatever
  ambient Python is on the machine unconditionally, with no check of whether it actually
  satisfies `PYSPEC` (the same value `~detect_python.py` already computes for uv/conda/embed).
  This means the current linear order (embed before venv) always pays embed's network cost even
  in the common case where the ambient Python already satisfies the pin and venv would have been
  strictly better (instant, no network dependency, no extra disk). The flip side also matters:
  embed is reached immediately after conda, so by the time it's attempted, uv and conda have
  already both failed -- and since all three of uv/conda/embed need network, embed is
  disproportionately likely to fail for the *same* underlying reason (see the README's REQ-009
  failure-causes table), making it a low-odds attempt in exactly the scenario where it's tried. A
  smarter design would check "does the ambient Python (if any) already satisfy PYSPEC?" and
  prefer venv when yes, falling to embed only when the ambient Python is absent or
  version-mismatched -- turning the fixed uv/conda/embed/venv/system chain into
  uv/conda/(venv-if-it-already-satisfies-PYSPEC, else embed)/system. Not pursued now: it changes
  `:try_venv_fallback`'s dispatch shape (must read `PYSPEC` before deciding, not just on
  creation), and the current fixed order is not wrong, just not optimal in either direction.
  **Trigger to thaw**: the network-correlated-embed-failure pattern this item predicts shows up
  for real, in CI or in an actual user report -- not a speculative build ahead of that evidence.
  **Re-examined 2026-07-25 per an owner request to raise confidence-to-implement wherever
  possible**: this was never actually a confidence question -- the design sketch above is sound
  and could be implemented with reasonable confidence in its own correctness. What was missing is
  evidence that it's WORTH the added complexity; raising implementation confidence doesn't
  manufacture that evidence, which is exactly why this belongs in Cold Storage rather than Active
  Backlog -- the blocker is the trigger, not readiness to build.

- **AV-Safe Build Path Tier B (reprovisioned pinned-3.12 environment).** Full PRD at
  `docs/prd-av-safe-build-path.md`; Tier A (real Nuitka fallback build in the existing
  environment) and requirement 9 (the elective "optimized build?" upsell) are both SHIPPED --
  see their own dedicated Closed Backlog entries -- and remain the complete, working AV-quarantine
  mitigation this repo ships today. Tier B was the PRD's second tier: a reprovisioned environment
  pinned to Python 3.12 specifically to route around Nuitka's MinGW64 backend not supporting
  Python 3.13+ (Finding 1 in the PRD, last re-confirmed unresolved as of Nuitka 4.1.2 in the
  2026-07-20 downtime re-check). Building it means a second provider-chain traversal, a
  pinned-version environment, and the stale-PATH/`VIRTUAL_ENV` hazard research Finding 6 already
  flagged -- real complexity with no user-observed need yet (the PRD itself notes it as
  preemptive, "no real user report yet, a documented industry-wide problem").
  **Trigger to thaw, two and only two conditions**: (a) the owner personally hits a real
  PyInstaller AV-quarantine failure that Tier A does not already resolve, giving the reprovision
  complexity a concrete justification instead of a speculative one; or (b) Nuitka's own upstream
  MinGW64 backend gains Python 3.13+ support, which would remove the entire reason Tier B needs a
  narrow version pin in the first place -- at that point Tier B's whole design would need
  re-evaluating (it might not need a pin at all anymore), not just a version bump. Condition (b)
  is exactly what the "Next-pin probe concept" section (under Periodic Maintenance Checks) already
  tracks quarterly for any future pin justified by one specific, checkable fact -- re-check that
  same fact each scan (Nuitka's MinGW64 Python-version support), not a generic "try a newer
  Nuitka" probe. If either condition fires, read the PRD's own "Notes from Claude" section before
  restarting Tier B -- it has the original reasoning plus a deliberately blunt writeup of why
  Tier B's narrow, well-justified 3.12 pin should **never** be generalized into a
  bootstrapper-wide "stay a version or two behind latest" default (this repo has no telemetry or
  auto-update mechanism, so any such pin freezes permanently into every already-distributed copy
  of `run_setup.bat`). Requirements 6 (loop avoidance) and 8 (connectivity check before Tier B)
  depend on Tier B existing and thaw with it, for the same reason.

- **pipreqs internalization (clean-room AST-based scanner + mapping table, replacing pipreqs as
  the primary dependency-discovery tool).** pipreqs (bndr/pipreqs) is stagnant (maintenance-only,
  looking for maintainers) but not at risk of disappearing from PyPI outright -- PyPI does not
  delete established packages. The real risk the community cites is future-Python bitrot (an AST
  parser silently failing on new syntax), which this repo has already pre-empted twice over: the
  0.4.13 pin (see "pipreqs pin rationale" above) avoids 0.5.0's `<3.13` Requires-Python ceiling,
  and the warnfix build-time safety net (see "Dependency Discovery Fallback: warnfix" above) means
  the bootstrap **never hard-fails** even if pipreqs is 100% unavailable -- confirmed by
  `self.stub.pipreqs_version_fail` (Closed Backlog), which forces pipreqs's own install to fail via
  `HP_PIPREQS_VERSION=99.99.99` (already an env-overridable variable, no code change needed to
  trigger this) and proves the bootstrap still reaches a working, fully-run EXE via warnfix alone.
  It is technically feasible and roughly the size a 3rd-party estimate suggested (a few hundred
  lines + a small mapping table), but it duplicates a safety net that already works and is tested,
  and is its own nontrivial project (matching pipreqs's accumulated edge-case handling: encoding
  fallback, syntax-error tolerance, stdlib filtering).
  **Trigger to thaw**: a real user run (not just CI) hits a pipreqs failure the warnfix safety net
  doesn't cleanly cover, OR pipreqs is genuinely removed from PyPI, OR the quarterly "next-pin
  probe" (Periodic Maintenance Checks, "pipreqs ecosystem status") finds pipreqs's own
  Requires-Python ceiling has moved in a way that reopens the future-Python-bitrot risk this
  section exists to track. A one-off CI observation is not enough on its own -- this needs a
  signal from how the tool behaves for a real user, or a concrete ecosystem change.
  **When it is eventually undertaken**: write a **clean-room** scanner rather than copying
  pipreqs's actual source or mapping file (pipreqs is MIT-licensed; copying it verbatim would
  require carrying its copyright notice -- a clean-room reimplementation sidesteps this entirely,
  though crediting pipreqs by name/link as prior art in a code comment is a fair courtesy). Seed
  the mapping table by extending this repo's own already-license-clear `tools/parse_warn.py`
  `TRANSLATIONS` dict rather than importing external mapping databases (showmereqs/FawltyDeps/
  marimo/Grayskull all carry their own licenses needing separate audit, and none of those tables
  have been vetted against this repo's actual needs). Use `sys.stdlib_module_names` with a
  `try/except ImportError` guard per the existing "Embedded-helper Python baseline" convention
  (it's a 3.10+ feature; must degrade gracefully on an older ambient interpreter on the
  venv/system fallback tiers). Do not chase alternative tools as a wholesale replacement: `pigar`
  was correctly ruled out elsewhere (its wheel bundles an ~40 MB SQLite package database, a
  non-starter for a single-file bootstrapper).

- **Conda native-DLL bundling repair loop (CLAUDE.md Active Backlog Item 24) -- THAWED 2026-08-04,
  no longer cold-storaged.** The owner explicitly brought this forward the same day (see
  `docs/prd-conda-native-dll-bundling.md`'s now-updated Finding 1/6 and Confidence Assessment for
  the research completed since the original draft). Active implementation is now tracked directly
  under CLAUDE.md's Active Backlog Item 24, not here -- this entry is kept only as a historical
  record of the original shelve-and-thaw-trigger reasoning; see Item 24 itself for current status.

- **Blinter in the sanity sweep, scoped to a vetted rule subset.** Investigated 2026-08-04 --
  current evidence (false-positive detail, rule counts) lives in AGENTS.md's own Blinter entry;
  not duplicated here to avoid drift between the two. Proposal: a scoped, per-rule-audited
  `blinter.ini` allowlist, mirroring how the sanity sweep already scopes markdownlint to MD029
  only, rather than running Blinter's full default rule set. **Trigger to thaw**: someone does
  the actual per-rule audit described in AGENTS.md and confirms a scoped allowlist produces ZERO
  findings against the current, already-clean `run_setup.bat`. Not worth doing speculatively
  ahead of that audit.

- **PSScriptAnalyzer in the sanity sweep, scoped to a vetted rule subset.** Investigated
  2026-08-04 -- current evidence (finding counts, which rules fire against this repo's own
  deliberate conventions) lives in AGENTS.md's own PSScriptAnalyzer entry, which also corrects a
  stale "PSGallery blocked by proxy" note this same investigation disproved; not duplicated here
  to avoid drift. Proposal: a `PSScriptAnalyzerSettings.psd1` excluding the rules AGENTS.md
  identifies as firing against established repo conventions, wired into
  `tools/run_sanity_sweep.sh`. Somewhat more promising than Blinter (per AGENTS.md, a smaller
  false-positive surface concentrated in fewer rules), but the same principle applies. **Trigger
  to thaw**: someone builds that settings file, confirms a full sweep against the current codebase
  comes back clean. Not worth doing speculatively ahead of that audit.

- **Force UTF-8 console encoding for the user's own launched process (`PYTHONUTF8=1` /
  `PYTHONIOENCODING=utf-8`).** Found via a 2026-08-08 third-party-analysis pass (a generic
  50-scenario "getting Python running on Windows" guide, cross-checked against this repo's own
  coverage): confirmed via grep that `run_setup.bat` sets neither `PYTHONUTF8` nor
  `PYTHONIOENCODING` anywhere, so a script printing non-ASCII text (accented characters, emoji, a
  degree symbol) can still hit `UnicodeEncodeError` or print garbled text under Windows' legacy
  console code page, exactly as it would for a fully manual setup -- one of the few genuinely
  common beginner gotchas this bootstrapper does nothing for today, despite otherwise
  systematically removing PATH/interpreter/dependency friction. Proposal: set
  `PYTHONUTF8=1` (Python 3.7+, forces UTF-8 mode process-wide) on every launch of the user's own
  code (build verification, EXE smoke run, direct interpreter run) -- a single environment
  variable at each launch site, no `run_setup.bat` architecture change. **Trigger to thaw**: a
  dedicated investigation confirming this has no unwanted side effect on any existing test's
  output-matching assertions (several tests grep captured stdout/stderr for exact strings; UTF-8
  mode is very unlikely to change ASCII-only output but this needs verifying, not assuming,
  before touching every user-code launch site in the file) and confirming it doesn't change
  behavior for a script that already explicitly manages its own encoding.

- **Corporate-proxy / SSL-MITM diagnostic messaging.** Same 2026-08-08 pass: confirmed via grep
  that `run_setup.bat` has no `HTTP_PROXY`/`HTTPS_PROXY` detection or messaging anywhere (the
  underlying tools -- curl, PowerShell, pip, conda, uv -- already pick up system/env proxy
  settings the same way a manual setup would, so this is about diagnostic messaging on failure,
  not new proxy-traversal capability this bootstrapper doesn't have). REQ-013's connectivity
  check already distinguishes "genuinely offline" from other failure modes; a corporate MITM
  proxy with a self-signed root CA would currently surface as a generic SSL/connection failure
  with no hint toward the actual cause. **Trigger to thaw**: lower confidence than the two items
  above that a reliable, low-false-positive detection signal exists (a corporate proxy failure
  and a genuine network outage can look identical from a single failed request) -- needs a
  dedicated investigation into what signal (if any) reliably distinguishes the two before
  proposing a specific fix, not implemented speculatively ahead of that.

