patch-cc 0.3.3__tar.gz → 0.5.0__tar.gz

{patch_cc-0.3.3 → patch_cc-0.5.0}/AGENTS.md

@@ -17,9 +17,15 @@ point it at the pristine copies in `~/.local/share/patch-cc/backups/` to sweep
 older builds). There is no test suite by design — doctor against real bundles
 is the check.
 
-Be exact about what that covers: doctor runs the **matchers** and parses the
-bundle they produce. It never runs the gateway, the translator, the OAuth flow
-or the menu, so a change under `src/patch_cc/codex/` (the bridge — all of it
-runtime, none of it a patch; the Codex *patch* is `patches/codex.py`, which the
-sweep does cover) or in `menu.py` is checked by exercising it — a real `codex
-serve` against a real turn — and a green sweep says nothing about it.
+Be exact about what that covers: doctor runs the **matchers**, parses the
+bundle they produce, then **bakes it into a temp binary and executes
+`--version`** — so the sweep also proves every build writes and boots (the
+container layer included; 2.1.246 is why). It still never runs the gateway,
+the translator, the OAuth flow or the menu, so a change under
+`src/patch_cc/codex/` (the bridge — all of it runtime, none of it a patch; the
+Codex *patch* is `patches/codex.py`, which the sweep does cover) or in
+`menu.py` is checked by exercising it — a real `codex serve` against a real
+turn — and a green sweep says nothing about it. Nor does `--version` exercise
+a patch's *feature* at runtime: it proves the patched code loads and runs, not
+that a streamed turn renders — behaviour changes still want a real turn
+watched.

{patch_cc-0.3.3 → patch_cc-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patch-cc
-Version: 0.3.3
+Version: 0.5.0
 Summary: Interactive patcher for the Claude Code native binary
 Project-URL: Homepage, https://github.com/anfreire/patch-cc
 Project-URL: Repository, https://github.com/anfreire/patch-cc
@@ -94,7 +94,7 @@ patch-cc                       # then just run it
 | Chrome & branding | Disable spinner tips | No rotating tips on the spinner |
 | | Mark `--version` | Appends `(patched)` — or any marker you choose |
 | | Custom startup name | Defaults to `<your username>'s Code` |
-| | Startup org/email label | Replace the org/email on the welcome screen — or hide it (demo mode keeps the stock line) |
+| | Startup org/email label | Replace the org/email on the welcome screen — or hide it (demo mode keeps the stock line). Upstream stopped drawing the segment in 2.1.246, so newer builds offer this dimmed as *not on this build* |
 
 ## Usage
 
@@ -113,8 +113,8 @@ uvx patch-cc apply --org-label "Ada's Lab"    # ...or show this instead
 uvx patch-cc apply --codex gpt-5.6-sol        # + a Codex model (see below)
 uvx patch-cc apply --from-cache               # replay your last remembered selection
 uvx patch-cc status                           # exactly what is applied
-uvx patch-cc doctor                           # do all patches match this build?
-uvx patch-cc doctor path/to/claude            # ...or match some other binary
+uvx patch-cc doctor                           # do all patches match this build, and does it bake + boot?
+uvx patch-cc doctor path/to/claude            # ...same, for some other binary
 uvx patch-cc list                             # every patch, described
 uvx patch-cc restore                          # put the original back
 ```
@@ -198,14 +198,16 @@ startup name / `--version` marker are visible tells too.
 ## Why native-only, and why it stays small
 
 Claude Code now ships only as a Bun single-file executable; the npm package is a
-wrapper that downloads it. patch-cc edits the JavaScript bundle embedded in the
-binary's `.bun` section in place. It also drops the entry module's stale
-precompiled bytecode — editing the source invalidates it anyway, and it is more
-than half the download — so on Linux, where the ELF section is rewritten in
-place, a patched binary is *smaller* than the original, not larger. (On macOS
-the freed bytes are not yet reclaimed, so the file keeps its size; it still runs
-correctly.) [docs/INTERNALS.md](docs/INTERNALS.md#the-bytecode-and-why-we-drop-it)
-has the measurements; `patch-cc status` has yours.
+wrapper that downloads it. patch-cc edits the JavaScript modules embedded in the
+binary's `.bun` section in place — since 2.1.242 the app is code-split across
+~1,300 of them, and patch-cc treats every one as a single surface. It also drops
+the stale precompiled bytecode of the modules it edits — editing a module's
+source invalidates its bytecode anyway — so on Linux, where the ELF section is
+rewritten in place, a patched binary is *smaller* than the original, not larger
+(83 MB smaller on 2.1.243). (On macOS the freed bytes are not yet reclaimed, so
+the file keeps its size; it still runs correctly.)
+[docs/INTERNALS.md](docs/INTERNALS.md#the-bytecode-and-why-we-drop-it) has the
+measurements; `patch-cc status` has yours.
 
 See [docs/INTERNALS.md](docs/INTERNALS.md) for the container format and
 [docs/PLAYBOOK.md](docs/PLAYBOOK.md) for repairing a patch after an update.

{patch_cc-0.3.3 → patch_cc-0.5.0}/README.md

@@ -63,7 +63,7 @@ patch-cc                       # then just run it
 | Chrome & branding | Disable spinner tips | No rotating tips on the spinner |
 | | Mark `--version` | Appends `(patched)` — or any marker you choose |
 | | Custom startup name | Defaults to `<your username>'s Code` |
-| | Startup org/email label | Replace the org/email on the welcome screen — or hide it (demo mode keeps the stock line) |
+| | Startup org/email label | Replace the org/email on the welcome screen — or hide it (demo mode keeps the stock line). Upstream stopped drawing the segment in 2.1.246, so newer builds offer this dimmed as *not on this build* |
 
 ## Usage
 
@@ -82,8 +82,8 @@ uvx patch-cc apply --org-label "Ada's Lab"    # ...or show this instead
 uvx patch-cc apply --codex gpt-5.6-sol        # + a Codex model (see below)
 uvx patch-cc apply --from-cache               # replay your last remembered selection
 uvx patch-cc status                           # exactly what is applied
-uvx patch-cc doctor                           # do all patches match this build?
-uvx patch-cc doctor path/to/claude            # ...or match some other binary
+uvx patch-cc doctor                           # do all patches match this build, and does it bake + boot?
+uvx patch-cc doctor path/to/claude            # ...same, for some other binary
 uvx patch-cc list                             # every patch, described
 uvx patch-cc restore                          # put the original back
 ```
@@ -167,14 +167,16 @@ startup name / `--version` marker are visible tells too.
 ## Why native-only, and why it stays small
 
 Claude Code now ships only as a Bun single-file executable; the npm package is a
-wrapper that downloads it. patch-cc edits the JavaScript bundle embedded in the
-binary's `.bun` section in place. It also drops the entry module's stale
-precompiled bytecode — editing the source invalidates it anyway, and it is more
-than half the download — so on Linux, where the ELF section is rewritten in
-place, a patched binary is *smaller* than the original, not larger. (On macOS
-the freed bytes are not yet reclaimed, so the file keeps its size; it still runs
-correctly.) [docs/INTERNALS.md](docs/INTERNALS.md#the-bytecode-and-why-we-drop-it)
-has the measurements; `patch-cc status` has yours.
+wrapper that downloads it. patch-cc edits the JavaScript modules embedded in the
+binary's `.bun` section in place — since 2.1.242 the app is code-split across
+~1,300 of them, and patch-cc treats every one as a single surface. It also drops
+the stale precompiled bytecode of the modules it edits — editing a module's
+source invalidates its bytecode anyway — so on Linux, where the ELF section is
+rewritten in place, a patched binary is *smaller* than the original, not larger
+(83 MB smaller on 2.1.243). (On macOS the freed bytes are not yet reclaimed, so
+the file keeps its size; it still runs correctly.)
+[docs/INTERNALS.md](docs/INTERNALS.md#the-bytecode-and-why-we-drop-it) has the
+measurements; `patch-cc status` has yours.
 
 See [docs/INTERNALS.md](docs/INTERNALS.md) for the container format and
 [docs/PLAYBOOK.md](docs/PLAYBOOK.md) for repairing a patch after an update.

patch_cc-0.5.0/docs/INTERNALS.md

@@ -0,0 +1,266 @@
+# Internals
+
+How patch-cc gets from a Claude binary to a patched, smaller one.
+
+## The shape of a native Claude binary
+
+Claude Code ships as a [Bun](https://bun.sh) single-file executable. The whole
+app — a ~20 MB minified JS bundle plus a few asset modules — is embedded in the
+binary:
+
+- **Linux**: an ELF section named `.bun`
+- **macOS**: a Mach-O section `__BUN,__bun`
+- **Windows**: a PE `.bun` section (not supported here)
+
+Inside that section is a *Bun module graph*: a flat arena of payloads, a module
+table describing them, and a trailer. Before 2.1.242 the graph was the app in one
+module plus a few asset modules; since then the app is **code-split** across
+~1,300 `chunk-*.js` modules that the entry lazily imports (see
+[the split](#the-21242-split-and-the-patchable-surface)). Either way patch-cc
+treats every module the container declares to be JavaScript as one surface.
+
+```
+.bun section
+└── [u64 size prefix]           (u32 on Bun < 1.3.4)
+    └── Bun blob
+        ├── payload arena       name / contents / sourcemap / bytecode / ... bytes,
+        │                       plus the record chain's own payloads (Bun >= 1.4.1)
+        ├── module table        N records × 52 bytes (36 on old Bun)
+        ├── record chain        flag-gated records (Bun >= 1.4.1), see below
+        ├── compileExecArgv
+        ├── offsets struct       32 bytes: byteCount, modulesPtr, entryId, argvPtr, flags
+        └── "\n---- Bun! ----\n"  15-byte trailer
+```
+
+Every pointer is a `(u32 offset, u32 length)` pair relative to the blob start,
+and pointers live in exactly three places: the module table, the offsets
+struct, and the record chain. That is what makes rewriting tractable — move a
+payload, fix the handful of pointers that describe it.
+
+Two invariants ride on payload *positions* rather than pointers, and `rebuild`
+preserves both by keeping every payload's inter-payload gap and its offset
+phase modulo 128 — so a rebuild with no edits reproduces the blob byte for
+byte, and one with edits moves payloads only in whole alignment steps:
+
+- Bytecode payloads (module bytecode, and the record chain's bytecode blobs)
+  sit at blob `offset % 128 == 120`, which is 128-byte alignment once the
+  section's 8-byte size prefix is in front. Bun ≥ 1.4.1 deserializes bytecode
+  in place and calls misalignment "a runtime assertion error or segfault"
+  (`append_bytecode_aligned`); older Bun quietly tolerated the phase drift the
+  rewriter used to introduce.
+- `count_z` payloads (names, contents) carry a NUL terminator in the gap
+  after them.
+
+A module record (new 52-byte format) is six such pairs — `name`, `contents`,
+`sourcemap`, `bytecode`, `moduleInfo`, `bytecodeOriginPath` — followed by four
+`u8` flags (`encoding`, `loader`, `moduleFormat`, `side`).
+
+Code: `src/patch_cc/bun/blob.py`.
+
+## The record chain (Bun ≥ 1.4.1)
+
+2.1.246 moved to Bun 1.4.1, whose `StandaloneModuleGraph.rs` chains optional
+records directly after the module table, each announced by a new `flags` bit
+and read back in flag order:
+
+| bit | record |
+|---|---|
+| 5 | `[u32; modules]` — each module's WTF hash of its source text (0 = none) |
+| 6 | `u32 count`, then `count` × `{u32 id, ptr}` — internal-module bytecode |
+| 7 | one pointer: the **shared bytecode string table** |
+| 8 | `u32` — how many leading modules load before the first `import()` |
+| 9 | one pointer: the string table `moduleInfo` bodies index |
+
+The pointers point back into the arena: the shared string table (~9.9 MB on
+2.1.246) is the string data **every chunk's bytecode references by ordinal**,
+so it is load-bearing for every module we did *not* touch. The hash is JSC's
+SourceCodeKey hash, how a launch that runs from bytecode avoids paging in
+source text just to hash it.
+
+patch-cc parses the chain record for record (`_parse_records` — a build with
+none of the bits, which is every Bun before 1.4.1, walks zero records through
+the same code), carries the pointed-at payloads through `rebuild` like any
+module payload, copies the whole tail between table and offsets struct
+verbatim, and re-points the pointers in place. Two details matter:
+
+- An **edited** module's hash word is zeroed — upstream's own "none, compute
+  it" value — because the pristine text's hash must not key our bytes in JSC's
+  source cache.
+- **Unknown** record bits are refused at parse: a record of unknown size
+  cannot be walked past nor re-pointed, and rewriting around it is exactly how
+  a graph gets corrupted. 2.1.246 against patch-cc ≤ 0.4.0 is the lesson: the
+  chain-blind rewriter dropped the records and zero-filled the string table
+  while every *module* round-tripped byte-perfect — matcher-green, dead at
+  launch, `SIGSEGV` from inside Bun's graph loader.
+
+## The 2.1.242 split, and the patchable surface
+
+Through 2.1.241 the entrypoint module *was* the app: one ~28 MB `contents`
+carrying every line patch-cc anchors on. 2.1.242 turned on Bun code-splitting
+with lazy loading, and the shape changed under the tool:
+
+| build | modules | entrypoint `contents` |
+|---|---|---|
+| 2.1.241 | 11 | 28,249,679 bytes (the whole app) |
+| 2.1.243 | 1,385 | 19,952 bytes (an argv shim) |
+
+The entrypoint is now a ~20 KB shim that parses argv and lazily
+`import()`s the app across ~1,300 `/$bunfs/root/chunk-*.js` modules; ~46 MB of
+JS, the largest chunk 7.3 MB. The code did not disappear — every anchor is still
+in the binary — but it left the one module patch-cc used to read, and it does not
+concentrate in a single chunk (`branding` spans a dozen modules, `org-label` ten,
+`spinner-tips` six).
+
+So the patchable surface is **every module the container declares to be
+JavaScript**, discovered the way the entrypoint itself is discovered — off the
+artifact, never hardcoded. A module's *loader* (the second trailing flag) is how
+Bun decides whether to compile it as source or hand it over as opaque bytes, and
+the entrypoint is by definition the JS Bun runs, so its loader *is* the JS loader
+(`Blob.js_modules`). The asset modules (the native addons, the bundled
+`mermaid`/`hljs`, the HTML template) carry other loaders and are left alone. A
+pre-split build is the one-module case of this — `js_modules()` returns just the
+monolith — so [`js.Source`](PLAYBOOK.md#the-many-module-surface) spans one module
+or a thousand through the same code.
+
+The entrypoint still matters for one thing: it is where the manifest lives and
+what `status` reads, named by the offsets struct's `entry_point_id` — the same
+index Bun resolves it by. Its *name* is upstream's to change and we never read
+it: 2.1.229 renamed it `/$bunfs/root/src/entrypoints/cli.js` → `/$bunfs/root/cli`.
+
+## The bytecode, and why we drop it
+
+Modules carry precompiled Bun **bytecode** — most of the binary. Before the
+split only the entry module had any (~half of it); the code-split builds carry it
+on nearly every chunk (232 MB of 377 on 2.1.243, across ~1,375 modules).
+
+Any edit to a module's `contents` invalidates *that module's* bytecode; Bun
+detects the mismatch and recompiles that module from source at launch. So keeping
+a stale copy buys nothing — the recompile is paid either way — and dropping it
+reclaims the space and guarantees our edits are what runs. patch-cc drops the
+bytecode of exactly the modules it edited (`rebuild` over `changed_modules`) and
+leaves every untouched module its bytecode and its fast start — which is why
+the shared bytecode string table those modules' bytecode indexes
+([the record chain](#the-record-chain-bun--141)) is never droppable. On Linux,
+where the ELF section is rewritten in place, the binary is smaller by exactly
+the edited modules' bytecode.
+
+Measured on 2.1.243, the full patch set:
+
+| binary | size | bytecode | startup |
+|---|---|---|---|
+| pristine | 378 MB | 232 MB (every module) | ~13 ms `--version` |
+| patched (edited modules' bytecode dropped) | **295 MB** | 150 MB (untouched modules) | ~15 ms |
+
+The 83 MB reclaimed is the ~45 edited modules' bytecode; the rest stays, which is
+why a split-build patched binary is smaller but not the *half* a patched monolith
+was. The recompile is now per lazily-imported edited module rather than the whole
+app at once, so startup barely moves. Read the current figures off any binary
+with `patch-cc status` rather than off this table — the bytecode total grows every
+few builds.
+
+The size story is the **ELF** path: the `.bun` section is rewritten in place, so
+the dropped bytecode is genuinely reclaimed (`container.verify` refuses a Linux
+write that did not shrink by about that much). On **macOS** the file keeps its
+original size: `macho.py` grows a segment but never shrinks one, so the freed
+bytes stay as dead space. The binary still runs correctly (the bytecode is gone),
+it is just not smaller — reclaiming it means shrinking the Mach-O segment and
+re-laying `__LINKEDIT`, which is not done yet.
+
+Every write asserts each **edited** module carries `bytecode == 0` in the binary
+it produced (`container.verify`, beside the round-trip check), and `patch-cc
+status` reports the total for an installed one. `doctor`'s dry run cannot — a
+clean bundle still has all its bytecode by definition — but its smoke bake
+writes a temp binary through the same `container.write` and then *executes* it,
+so the sweep exercises the assert, and the loader itself, on every corpus
+build. If a future Bun build makes bytecode authoritative over source, that
+assert is the tripwire — every edit would silently no-op otherwise.
+
+## Writing it back without ballooning
+
+`.bun` is the last *allocated* ELF section; only non-allocated metadata
+(`.comment`, `.symtab`, `.strtab`, `.shstrtab`) follows it. patch-cc rewrites
+the ELF bytes in place:
+
+1. Splice the new (smaller) blob over the old `.bun` bytes.
+2. Shift `e_shoff`, `e_phoff`, and the trailing non-alloc sections/segments by
+   the size delta.
+3. Grow or shrink the containing `PT_LOAD` segment's `filesz`/`memsz` to match.
+
+`.bun` keeps its original file offset. This is deliberately *not* done with a
+general ELF library: LIEF rebuilds the binary and relocates `.bun` so its file
+offset equals its virtual address (`0x20000000`), which inflates the file to
+~715 MB. Raw in-place surgery avoids that entirely.
+
+Guards refuse anything that could corrupt the mapping: allocated sections after
+`.bun`, growth into a header table, an unrelated spanning segment, or a
+misaligned `PT_LOAD` shift. If any fires, the write aborts rather than guesses.
+
+Code: `src/patch_cc/bun/elf.py`. macOS uses LIEF (`macho.py`) — Mach-O segment
+growth is page-aligned and bounded, with no relocation pathology, and every
+edit is followed by an ad-hoc `codesign` (mandatory on Apple Silicon).
+
+## The manifest
+
+Every patched bundle carries a single comment line — appended to the **entry
+module**, the one module always present and always re-extracted, and the one
+`status` reads — describing its shape; [PLAYBOOK.md](PLAYBOOK.md) covers what it
+means for matcher health:
+
+```
+//patch-cc {"v":1,"tool":"<version>","patches":[...],"brand":...,"suffix":...,
+            "models":{...},"org":...,"codex":{"port":8817,"models":["gpt-5.6-sol"]}}
+```
+
+Every key after `patches` is a configurable patch's own, declared in one place
+(`Patch.setting`) so the manifest here, the cache, and the menu cannot spell it
+three ways. Each is written only when *that* patch landed **and** has a value
+worth recording, so `status` can never assert a name, marker, or model the
+bundle does not contain — and so this is the *widest* the line gets, not its
+fixed shape.
+
+That line is why `patch-cc status` can name exactly what is applied: several
+patches are value flips (`verbose:!0`) that leave no other trace. A comment
+can't collide with code and travels with the bundle through extract/repack.
+The menu also reads it to pre-select the current patch set — the binary is the
+state.
+
+Each key records what was *asked for*, never what was derived from it. `codex`
+carries model ids and a port and nothing else: a Codex model's display name and
+context window are already baked into the bundle, and repeating them here would
+be a second copy — one that a relabelling upstream could make disagree with the
+binary it claims to describe. That is also what makes the manifest the single
+home for the gateway port: `codex serve` and `codex status` read it from here
+rather than from a store of their own.
+
+## Safety
+
+- Before the first patch of a version, the pristine binary is copied to
+  `~/.local/share/patch-cc/backups/`. `restore` copies it back — never an
+  inverse patch (insertions cascade, so a reverse diff is meaningless).
+- Patching always starts from that pristine copy, so re-applying never stacks
+  edits on edits, and an apply where **nothing lands** — every selected patch
+  broken, so the manifest would claim nothing — leaves the binary untouched
+  entirely (stripping bytecode for nothing would only slow startup). A patch
+  that *lands* still writes even where it changed no bytes, because landing
+  includes an override the build already satisfies: the manifest records what
+  was asked and verified present, so `status` can report it.
+- The bundle is parsed, and any syntax error aborts before the binary or the
+  backup is touched — the two checks below answer "did we write what we meant
+  to", which a corrupt splice satisfies perfectly. The parse is the same one
+  the patches locate with, so it costs nothing extra and sits at *every* batch
+  of edits as well as on the final bytes: a patch that produces rubble is named
+  and dropped rather than aborting the run. See
+  [PLAYBOOK.md](PLAYBOOK.md#the-syntax-gate).
+- Every write is verified: patch-cc re-extracts the JS from the binary it just
+  wrote and asserts every module equals what it meant to write, that each
+  module it edited carries no leftover bytecode to run instead of the edit, and
+  that the graph around the modules survived — the record chain kept its
+  length and flags, its arena payloads (the shared bytecode string table above
+  all) round-trip byte-identical, and every source-hash word is the pristine
+  one, except an edited module's, which must be zero. The chain checks exist
+  because 2.1.246 failed *only* there: every module compared equal while the
+  written binary was dead.
+- Patching a binary that is already marked, when no pristine backup exists, is
+  refused outright — there is nothing clean to start from, and our edits change
+  lengths, so a second pass would corrupt rather than update. `restore` or a
+  reinstall are the only honest fixes; there is deliberately no override.

{patch_cc-0.3.3 → patch_cc-0.5.0}/docs/PLAYBOOK.md

@@ -152,6 +152,56 @@ gone green, and every one buys a branch against a single build. The counting
 below is the net for drift; the rule above is the only thing standing between a
 repair and the next repair.
 
+## The many-module surface
+
+Through 2.1.241 the bundle was one module — the entrypoint carried the whole app
+— and every matcher searched that one buffer. 2.1.242 code-split it: the
+entrypoint became a ~20 KB argv shim that lazily imports the app across ~1,300
+`chunk-*.js` modules ([INTERNALS](INTERNALS.md#the-21242-split-and-the-patchable-surface)).
+The anchors did not move — they scattered. So `js.Source` **spans every
+JavaScript module the container declares** (`Blob.js_modules`, discovered off the
+entrypoint's own loader), and the one-module world is exactly the many-module
+world with one module: `find`/`literals`/`count` sweep every module, `apply`
+routes each edit to the module its node came from, and a patch says
+`source.find(name)` / `source.apply(edits)` unchanged. This is representation
+change of the crudest kind — the same code in more files — so it *moved* no
+invariant and abolished none; the surface widened, the rules held. Three things
+the move made explicit, each a rule the single-module world could leave unsaid
+because the module was the bundle:
+
+- **A node carries its module; an offset does not.** An `Edit` is built from a
+  node, and the node's program root (`node.id`, distinct across parses) names the
+  module the edit belongs to, so a batch spanning a dozen chunks routes each
+  splice home and reparses only the modules it touched. It is why dedup keys are
+  the node's `id`, never its `start_byte`: a minified offset repeats in a
+  thousand modules, and two different sites at the same local offset are two
+  sites, not one to skip.
+
+- **A minified local is scoped to its module.** Resolving one — a hoisted
+  `agentType:uu` constant read through its value — searches *its own* module
+  (`Source.find_local`), never the bundle, where `uu` binds a string in a dozen
+  unrelated chunks and `js.only` would rightly refuse to choose. Before the split
+  the module *was* the bundle, so a bundle-wide `find` was a module-wide one; the
+  two only came apart when the app was dealt across files. The same lesson the
+  playbook already states for identifiers within a build — "a name is a spelling
+  until its scope is said" — now reaches the module boundary too. A scope search
+  that climbs outward (`live-thinking`'s state and memo resolution) reads the
+  module wrapper by what it *is* — the pre-split monolith's whole-body IIFE is a
+  module of one top-level statement; a split module's `program` is dozens, and
+  its top-level components are real scopes to search — never by a fixed position,
+  which read every split component as the un-searchable wrapper and found nothing.
+
+- **The gate reads code, not linkage.** tree-sitter's JavaScript grammar does not
+  model a reserved word as an import/export alias (`export{x as if}`,
+  `import{if as a}` — legal ES2015, which the split minifier emits when its
+  two-letter alias generator lands on `if`/`in`/`do`), so it plants a localized
+  `ERROR` inside the clause. patch-cc never locates in or edits module linkage —
+  every anchor is executable code — so `Source.defect` reads *past* an error
+  confined to an import/export statement and returns the first one that is not,
+  while a splice that broke real code still lands outside linkage and is still
+  caught. It is the gate's scope stated precisely, not a tolerance bolted on: the
+  eight such modules on 2.1.243 parse clean for every purpose the tool has.
+
 ## Discovery instead of hardcoding
 
 Anything the binary can enumerate for us, it does:
@@ -259,6 +309,20 @@ isolation was cheaper and could not see the one ordering this project calls
 load-bearing — `codex-models` registering the ids `subagent-models` then pins —
 nor anything at all about the bundle the run produced, which it discarded.
 
+The composed result is then **baked and executed**: doctor writes it into a
+temp binary through the same `container.write` as a real apply — staging,
+round-trip verification, the container checks — and runs `<binary> --version`,
+expecting the version-marker suffix in the output (our own edit's print, so the
+check proves patched code *executes*, not merely that the binary boots around
+it). Matching and running are different truths with different failure owners:
+matchers break in the patches, the run breaks in the container layer, and
+2.1.246 is the build where they split — every matcher green, every module
+round-tripping byte-perfect, and the written binary `SIGSEGV`ing in Bun's graph
+loader because what the rewrite had destroyed (the Bun 1.4.1 record chain and
+the shared bytecode string table, docs/INTERNALS.md) lives in bytes no module
+owns. The temp binary is always removed; the backup under test is never
+written to.
+
 Three readings of the two numbers, kept distinct:
 
 | symptom | meaning |
@@ -313,7 +377,9 @@ re-deriving it.
 
 Both numbers above are counts, and a count cannot tell a rewrite that landed
 from a rewrite that landed *one prop-name to the left*. So the bundle is parsed,
-and any `ERROR` or `MISSING` node aborts (`src/patch_cc/js.py`).
+and any `ERROR` or `MISSING` node **outside module linkage** aborts
+(`src/patch_cc/js.py`; the linkage read-past is
+[above](#the-many-module-surface)).
 
 The parse is not a separate pass any more: locating already needs it, and an
 edit costs one incremental reparse — ~75 ms on a 25 MB bundle against ~3 s for a
@@ -493,6 +559,10 @@ that broke a patch along with every note.
    patch-cc extract ~/.local/share/claude/versions/<ver> > clean.js
    ```
 
+   Since 2.1.242 that is every JavaScript module concatenated, each behind a
+   `// ==== patch-cc module <n> ====` header, so `rg` still works over one file
+   and the header says which chunk a hit lives in.
+
 2. Run `patch-cc doctor`. Note which patch dropped to `candidates == 0`, or —
    for `live-thinking` — which sub-step.
 
@@ -552,6 +622,12 @@ that broke a patch along with every note.
    enumerated with its hashes in [corpus.md](corpus.md) — so both sides are
    recomputed from the binaries themselves.
 
+   Each build's report ends with its baked binary's own `--version` output (the
+   smoke run above), so the sweep also proves every corpus build still *bakes
+   and boots* — the half matcher counts cannot see, and the half 2.1.246 broke
+   while every count held. A moved runtime line is as much a finding as a moved
+   count.
+
 ## Patch reference
 
 Grouped by source module. The menu's three groups (Output & display, Models &
@@ -792,28 +868,37 @@ for you. Each entry: what it changes, the stable anchor, and where it lives.
     *initialised* to is deliberately not asked: `useState(null)` is every
     build's spelling and `useState(void 0)` would be the same state, while the
     setter is the identity that matters.
-  - **The state has two homes, and the handed setter names both.** Through
-    2.1.235 the scope that hands `onStreamingThinking` declared the state
-    itself, and the state is the array pattern binding the handed setter —
-    `useState`'s pair. 2.1.236 moved it into an external stream store
-    (`subscribe`/`getSnapshot`/`_publish` — the `useSyncExternalStore` shape)
-    and hands `<store>.setStreamingThinking` instead; the same scope reads the
-    store back by destructuring the hook call it hands the store to
-    (`{streamingToolUses:…}=useX(<store>)`), so the state is that pattern's own
-    `streamingThinking` binding — upstream's the day it takes one, the goal
-    achieved, and until then ours, inserted at the front of the pattern. The
-    pattern is proven the snapshot read by the store expression itself: the
-    call's *only* argument is the very expression the setter was read off, one
-    answer or none (`js.only`). Sole argument is deliberate — a second is a
-    selector whose result is no longer the snapshot, and extending a pattern of
-    unknowable provenance binds `undefined` with every count green. The
-    insertion also pays for a witness the way `thinking-summaries` does: the
-    field it binds must still be named by the bundle's own objects (the store's
-    snapshot initialiser, its publish call), so a store that renames the field
-    reads as the step reporting the store rather than threading `undefined`.
-    Two things come free with the store: its setter takes functional updaters —
-    React's own contract, which the reducer splices already speak — and it
-    hides a finished block itself after 30 s, upstream's own linger.
+  - **The state has two homes, and each is proven by the only name it has.**
+    Through 2.1.235 the scope that hands `onStreamingThinking` declared the
+    state itself, and the state is the array pattern binding the handed setter
+    — `useState`'s pair, which nothing else names. 2.1.236 moved it into an
+    external stream store (`subscribe`/`getSnapshot`/`_publish` — the
+    `useSyncExternalStore` shape) that a component reads back by destructuring
+    a hook call (`{streamingToolUses:…}=useX(<store>)`), so the state is that
+    pattern's own `streamingThinking` binding — upstream's the day it takes
+    one, the goal achieved, and until then ours, inserted at the front of the
+    pattern. The pattern names *itself*: it binds the store's own
+    `streamingToolUses` field — the name the store publishes and the
+    transcript signature already rests on — and that membership is its whole
+    identity, provided its value is a call taking exactly one argument, one
+    answer or none (`js.only`). It was once proven by the handing instead —
+    "the call's only argument is the very expression the setter was read off"
+    — and 2.1.246 moved the handing into the engine
+    (`this.stream.setStreamingThinking`), out of every component, without
+    moving the state: four renders that plainly draw the conversation read as
+    having none in scope, with `onStreamingThinking:` still twice in the
+    bundle. The handed setter was `agentDefinitions` again — a neighbour
+    standing in for the thing itself, one more fact upstream had to keep.
+    Sole argument stays deliberate — a second is a selector whose result is
+    no longer the snapshot, and extending a pattern of unknowable provenance
+    binds `undefined` with every count green. The insertion also pays for a
+    witness the way `thinking-summaries` does: the field it binds must still
+    be named by the bundle's own objects (the store's snapshot initialiser,
+    its publish call), so a store that renames the field reads as the step
+    reporting the store rather than threading `undefined`. Two things come
+    free with the store: its setter takes functional updaters — React's own
+    contract, which the reducer splices already speak — and it hides a
+    finished block itself after 30 s, upstream's own linger.
 
   A render was once selected by *position* — the observation that the real sites
   fall after the state's `useState` declaration. That is worth recording as a
@@ -856,11 +941,29 @@ for you. Each entry: what it changes, the stable anchor, and where it lives.
   than carried over from whichever renderer the first step happened to see
   last: a second component with the same four props donated its local to the
   first one's memo, spliced an identifier that component cannot see, and
-  reported both steps green. The memo itself is found by what it computes (a
-  `useMemo` over a `flatMap` that wraps each streaming block as a message),
-  which is what a claim about the *text* around the block (`.contentBlock]}`)
-  only approximated: one sibling property beside `content` read as the whole
-  computation being gone.
+  reported both steps green. The memo itself is found by what it computes — an
+  arrow whose whole body is a `flatMap` that wraps each streaming block as a
+  message, and the call that takes that arrow — never by the memo hook's name.
+  The hook is one more minified spelling: the monolith reaches it as
+  `<React>.useMemo(...)` (the property name survives a member read), but a
+  code-split module imports it under a local (`import{useMemo as te}` → `te(...)`),
+  so keying on `useMemo` read a build that memoizes exactly the same way as one
+  with no memo at all, and the rewrite reuses the memo's *own* callee rather than
+  re-spelling `.useMemo`. What a claim about the *text* around the block
+  (`.contentBlock]}`) only approximated is the computation itself: one sibling
+  property beside `content` read as the whole thing being gone. The wrapped
+  block is asked by membership among the element's *possible values*
+  (`js.values` — the same value routing the codex resolvers read), never asked
+  to be the read: 2.1.246 minted stable ids for streamed blocks
+  (`ce?{...S.contentBlock,id:V}:S.contentBlock`), and the exact-node question
+  read the same wrap one choice deeper as no wrap at all — nine required steps
+  to zero, every anchor count standing. The rewrite reuses upstream's callback
+  and dependencies verbatim — the callback invoked per entry with the same
+  three arguments `flatMap` hands it, each dependency spread rather than
+  transcribed — because a rebuilt copy is a copy free to shed whatever
+  upstream adds next: the re-spell this replaced would have silently dropped
+  the 2.1.246 minting, and with it went the uuid-stamp identity that re-spell
+  had to prove and the reuse no longer asks.
 
   **`display-mode`** defaults the request's thinking display to `"summarized"`;
   without it the API only streams summary text when the `showThinkingSummaries`
@@ -1251,6 +1354,24 @@ for you. Each entry: what it changes, the stable anchor, and where it lives.
   touched: the `/status` Organization/Email rows, the login screen, and the
   org's startup message (`"Message from <org>:"`) still show the real account.
 
+  **2.1.246 retired the surface.** Upstream deleted the welcome-banner variant
+  that composed the segment; the surviving banner draws `model · billing` with
+  no org anywhere — the hidden state an empty `--org-label` asks for, now
+  upstream's own default. That is a semantic change, not a matcher to repair
+  (the `help-title` precedent), and it is *absence*, reported apart from broken
+  (CONDUCT): the patch declares its surface (`Patch.absence`, answered by the
+  same `_org_segments` its candidates count off, so the two cannot disagree),
+  and every surface derives its answer from the bundle in hand — the menu shows
+  the row dimmed (`not on this build`, unselectable), an explicit `--org-label`
+  is refused at the front door with the same sentence, a cached replay skips it
+  with a note, and `doctor` prints a `-` row apart from ✓/✗ and stays green.
+  Nothing is keyed on a version, so a build that composes the segment again
+  un-dims the row with no code change. What absence cannot tell apart is a
+  composition respelled out of the locator's sight — that build would read as
+  absent, visibly dimmed on a screen that still draws the segment — and the
+  sweep over the corpus, where thirty-four builds carry the surface, is what
+  keeps the locator honest.
+
 ## Removed patches
 
 Kept here so nobody reintroduces them without knowing why they left: