patch-cc 0.5.2__tar.gz → 0.6.1__tar.gz

{patch_cc-0.5.2 → patch_cc-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patch-cc
-Version: 0.5.2
+Version: 0.6.1
 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
@@ -45,7 +45,7 @@ No Node, no Bun.
 uvx patch-cc                   # fullscreen menu, no install needed
 ```
 
-![patch-cc: pick tweaks, register a Codex model, pin the Plan agent to it, bake — the patched binary is 161 MB smaller](https://raw.githubusercontent.com/anfreire/patch-cc/main/docs/demo.gif)
+![patch-cc: pick tweaks, register a Codex model, pin the Plan agent to it, bake](https://raw.githubusercontent.com/anfreire/patch-cc/main/docs/demo.gif)
 
 ## Requirements
 
@@ -195,19 +195,20 @@ uvx patch-cc apply --brand --model Explore=haiku
 `uvx patch-cc status` tells you whether the current binary is patched, and the
 startup name / `--version` marker are visible tells too.
 
-## Why native-only, and why it stays small
+## Why native-only, and what the write does
 
 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 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.
+binary's `.bun` section — since 2.1.242 the app is code-split across ~1,300 of
+them, and patch-cc treats every one as a single surface. The write never moves a
+byte of the original: each edited module's source is appended and its stale
+precompiled bytecode is unlinked (editing a module's source invalidates its
+bytecode anyway), so a patched binary is a few percent larger than the original,
+and everything else the binary carries — Bun's own records, however its format
+grows — is exactly where it was. That is what keeps the container layer out of
+the way when Bun changes its format under Claude.
+[docs/INTERNALS.md](docs/INTERNALS.md#the-rule-never-move-a-pristine-byte) has
+the reasoning; `patch-cc status` has your numbers.
 
 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.2 → patch_cc-0.6.1}/README.md

@@ -14,7 +14,7 @@ No Node, no Bun.
 uvx patch-cc                   # fullscreen menu, no install needed
 ```
 
-![patch-cc: pick tweaks, register a Codex model, pin the Plan agent to it, bake — the patched binary is 161 MB smaller](https://raw.githubusercontent.com/anfreire/patch-cc/main/docs/demo.gif)
+![patch-cc: pick tweaks, register a Codex model, pin the Plan agent to it, bake](https://raw.githubusercontent.com/anfreire/patch-cc/main/docs/demo.gif)
 
 ## Requirements
 
@@ -164,19 +164,20 @@ uvx patch-cc apply --brand --model Explore=haiku
 `uvx patch-cc status` tells you whether the current binary is patched, and the
 startup name / `--version` marker are visible tells too.
 
-## Why native-only, and why it stays small
+## Why native-only, and what the write does
 
 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 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.
+binary's `.bun` section — since 2.1.242 the app is code-split across ~1,300 of
+them, and patch-cc treats every one as a single surface. The write never moves a
+byte of the original: each edited module's source is appended and its stale
+precompiled bytecode is unlinked (editing a module's source invalidates its
+bytecode anyway), so a patched binary is a few percent larger than the original,
+and everything else the binary carries — Bun's own records, however its format
+grows — is exactly where it was. That is what keeps the container layer out of
+the way when Bun changes its format under Claude.
+[docs/INTERNALS.md](docs/INTERNALS.md#the-rule-never-move-a-pristine-byte) has
+the reasoning; `patch-cc status` has your numbers.
 
 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.2 → patch_cc-0.6.1}/docs/CONDUCT.md

@@ -74,6 +74,18 @@ shape that already absorbs every case, found rather than bolted on.
   React idioms before it was cut to three insertions on the tool-use list
   ([PLAYBOOK.md](PLAYBOOK.md#live-thinking--streamingpy)).
 
+- **Never move a byte you did not write.** The container is the second worked
+  case of the rule above. Bun reads a payload through its pointer and ignores
+  what nothing points at; a rewrite that re-lays the arena has to re-aim every
+  pointer in the blob, including ones in records it has never seen, and Bun
+  adds such records whenever it likes — 2.1.246 corrupted one, 2.1.269 was
+  refused over one, and the whitelist of known records between the two could
+  never be finished. So the write appends what changed and copies everything
+  else where it was, and needs to know only what it touches
+  ([INTERNALS.md](INTERNALS.md#the-rule-never-move-a-pristine-byte)). The price
+  is a binary a few percent larger instead of smaller; the size win was the
+  claim that bought the fragility.
+
 - **Port faithfully.** When you change a patch, verify its output against a real
   bundle — byte-identical where behaviour must not change. `doctor` over the
   archived corpus is that check, and the *diff* between two sweeps is the half
@@ -84,5 +96,5 @@ shape that already absorbs every case, found rather than bolted on.
 - **The user controls commits and releases.** Don't commit, push, or publish
   unless asked.
 
-The binary format, and why the ELF write is in-place and the bytecode is
-dropped: [INTERNALS.md](INTERNALS.md).
+The binary format, and why the write appends rather than compacts:
+[INTERNALS.md](INTERNALS.md).

patch_cc-0.6.1/docs/INTERNALS.md

@@ -0,0 +1,273 @@
+# Internals
+
+How patch-cc gets from a Claude binary to a patched one.
+
+## The shape of a native Claude binary
+
+Claude Code ships as a [Bun](https://bun.sh) single-file executable. The whole
+app — 34 MB of minified JS on 2.1.269, 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]
+    └── Bun blob
+        ├── payload arena       name / contents / sourcemap / bytecode / ... bytes,
+        │                       and whatever else the builder placed there
+        ├── module table        N records × 52 bytes
+        ├── records             flag-gated, 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 Bun reads a payload *through* its pointer — bytes nothing points at are
+ignored. A module record 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 rule: never move a pristine byte
+
+The loader's contract above is the only thing the rewrite rides. How the
+builder lays the arena out, and which records follow the table, is the half of
+the format that changes with Bun — and a rewrite that re-laid the arena would
+have to find and re-aim every pointer in the blob, including pointers in records
+it had never seen. Bun owes that to nobody, and it is where this tool broke
+twice: 2.1.246 (Bun 1.4.1) chained records after the table, and a chain-blind
+compaction shipped a binary that segfaulted in Bun's graph loader while every
+module compared equal; 2.1.269 (Bun 1.4.3) chained two more, and the chain
+walker written after 2.1.246 — mirroring Bun's reader record for record, with a
+whitelist of the bits it knew — refused the build outright. Mirroring the
+reader more completely is a repair that can never be finished.
+
+So `rewrite` moves nothing. An edited module's text is appended after the
+arena (NUL-terminated, as Bun's own `count_z` payloads are); the module table
+and everything after it are copied verbatim, shifted by a multiple of 128 so
+every phase inside them holds; then the pointers that name what changed are
+re-aimed:
+
+- the edited module's `contents` pair, at its text;
+- its `bytecode` pair, at nothing ([below](#the-bytecode-and-why-we-unlink-it));
+- its source-hash word, to 0 — upstream's own "none, compute it" — because the
+  hash keys the text in JSC and the pristine text's hash must not describe ours;
+- the offsets struct's `modulesPtr` and `argvPtr`, along with the bytes they
+  name.
+
+Every other byte, and every other pointer, is exactly where it was. A record
+patch-cc has never heard of comes through the same copy and still points where
+it did, because what it points at did not move; the arena's payloads keep their
+128-byte phase — Bun deserializes bytecode in place and calls misalignment "a
+runtime assertion error or segfault" — because the arena is not shifted at all.
+
+What has to be *known* is exactly what is touched: the offsets struct, two
+pairs and the loader byte of a module record, and the one record that
+describes a module's text — its hash, first after the table when bit 5 of
+`flags` says there is one. The rest of `flags` travels verbatim, bits this code
+has never seen included, with one exception. Bit 4 declares every module's
+text to lie in one contiguous run: Bun's runtime hints the kernel to drop those
+pages after startup, and its comment forbids any other region inside the run.
+The appended text is outside it, so the bit is cleared — Bun documents the
+absent flag as an older layout it reads — rather than left asserting something
+false.
+
+## The records after the table
+
+Bun ≥ 1.4.1 chains optional records directly after the module table, each
+announced by a `flags` bit and read back in flag order. What has been seen so
+far, for orientation — patch-cc parses none of it beyond the first:
+
+| bit | record | since |
+|---|---|---|
+| 5 | `[u32; modules]` — each module's WTF hash of its source text (0 = none) | 2.1.246 |
+| 6 | `u32 count`, then `count` × `{u32 id, ptr}` — internal-module bytecode | 2.1.246 |
+| 7 | one pointer: the shared bytecode string table every chunk's bytecode indexes | 2.1.246 |
+| 8 | `u32` — how many leading modules load before the first `import()` | 2.1.248 |
+| 9 | one pointer: the string table `moduleInfo` bodies index | 2.1.248 |
+| 11 | one pointer to a pre-linked ES module graph, then `u32 count` and `count` × `u32` file index | 2.1.269 |
+| 12 | `u32 flags, u32 value` — runtime options (a JIT policy) | 2.1.269 |
+
+Three shapes across the 17 published builds from 2.1.246 to 2.1.269, and none
+of them a code change here: each is bytes in the tail and payloads in the
+arena, and both are copied where they are. The one record whose *meaning* the
+rewrite leans on is bit 11's: a module in the pre-linked graph ships no
+`moduleInfo` body, and its imports and exports are read from the graph rather
+than its text — which holds for an edited module too, because a patch never
+touches module linkage (the syntax gate reads past it,
+[PLAYBOOK.md](PLAYBOOK.md#the-many-module-surface)).
+
+## 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 unlink it
+
+Modules carry precompiled Bun **bytecode**. Before the split only the entry
+module had any (~half of the binary); the code-split builds carry it on nearly
+every chunk (78 MB of 219 on 2.1.268, across ~1,650 modules), and the records
+after the table name another 14 MB — the internal modules' bytecode and the
+shared string table — that no edit touches.
+
+Bun runs a module's bytecode in preference to its source, so an edited module's
+bytecode would run the *unpatched* code. `rewrite` therefore aims the edited
+modules' `bytecode` pair at nothing, and Bun compiles those modules from source
+at launch; every untouched module keeps its bytecode and its fast start. The
+stale bytes themselves stay in the file, unreferenced: reclaiming them would
+mean moving everything after them, which is the compaction the rule above
+forbids. A patched binary is therefore a few percent *larger* than the
+original — the edited modules' text, appended — never smaller.
+
+Measured on 2.1.268, the default patch set:
+
+| binary | size | bytecode the table names |
+|---|---|---|
+| pristine | 219 MB | 78 MB, every module |
+| patched (11 modules edited) | 228 MB | 51 MB, the untouched modules |
+
+Read the current figures off any binary with `patch-cc status` rather than off
+this table. Startup does not move: an edited module recompiles from source
+whether its bytecode is dropped or merely unlinked, and the recompile is per
+lazily-imported edited module rather than the whole app at once.
+
+Every write asserts each **edited** module names no bytecode in the binary it
+produced (`container.verify`), and `doctor`'s smoke bake writes a temp binary
+through the same `container.write` and *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
+
+`.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, larger blob over the old `.bun` bytes.
+2. Shift `e_shoff`, `e_phoff`, and the trailing non-alloc sections/segments by
+   the size delta, rounded up to the strictest alignment among them.
+3. Grow 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`): growing a
+Mach-O segment is page-aligned and bounded, with no relocation pathology, and
+growth is the only thing the rewrite ever asks of a container, so the two
+platforms behave the same way. 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 (unlinking 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, and that the
+  blob is the pristine blob plus exactly the intended edits — the arena
+  byte-identical in place; the module table and the tail verbatim one shift
+  along, except each edited module's two pairs and hash word; the flags less
+  the contiguity bit; the same entry module and the same `compileExecArgv`.
+  Nothing is enumerated, so a record this code has never parsed is covered by
+  the same comparison as the ones it has. The check exists 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.5.2 → patch_cc-0.6.1}/docs/PLAYBOOK.md

@@ -123,6 +123,20 @@ The tree removes the *mechanical* fragility. It does not decide these:
   the bundle one identity, the point where that path is fed, where a twin of
   the path owes one per step, each a claim only the patch needs.
   `live-thinking` is the worked case ([below](#live-thinking--streamingpy)).
+- **Anchor on the fact, not on a consumer of it.** When upstream keeps a fact
+  under a name of its own — a setting, a header, a store field — and every
+  site that acts on it sits downstream of one read, default or flip *that
+  read* and leave the sites alone: the sites are where upstream respells
+  things, the name is what it keeps. `display-mode` paid for the lesson on
+  2.1.277. It defaulted the request's thinking display at the site that chose
+  it, reached through the env-var read that shared the value's `let`
+  (comma-fusion, the minifier's) and identified as the consequence of a
+  ternary whose alternative was `void 0` (the branch layout, upstream's); the
+  build flipped the branches and grew a `"highlights"` mode inside the value,
+  and the step found nothing with every anchor standing — while the fact,
+  `showThinkingSummaries`, was one member read in one spelling on every build
+  in the corpus. Where a value *must* be identified at its site, ask what it
+  can *be* (`js.values`), never which branch it sits on.
 - **Match an identity by the weakest claim that still proves it; hold a rewrite
   to the exact node.** The two jobs pull in opposite directions.
   `thinking-inline`'s null-guard neutralises only a `return` that answers
@@ -215,7 +229,7 @@ Anything the binary can enumerate for us, it does:
   three entries when 2.1.229 renamed the module out from under it
   (`…/src/entrypoints/cli.js` → `…/cli`) and the tool stopped opening binaries
   at all — with the answer already parsed, already carried on the dataclass, and
-  already written back unchanged by `rebuild`. A list that only ever grows is
+  already written back unchanged by `rewrite`. A list that only ever grows is
   answering the wrong question. An id past the end of the module table is a
   corrupt blob and raises; there is deliberately no fallback to guessing by
   name, because a container that cannot say which module it runs is not one to
@@ -505,8 +519,9 @@ Most patches are one rewrite. `live-thinking` is five named sub-steps, because
 a single hit count cannot tell "all landed" from "half silently drifted", and
 each records its own `candidates`/`applied`:
 
-- **`display-mode`** — the request asks the API for summarised thinking text;
-  without it the stream carries signatures and no words.
+- **`display-mode`** — the `showThinkingSummaries` setting defaults on, so the
+  request asks the API for summarised thinking text; without it the stream
+  carries signatures and no words.
 - **`reducer`** — the stream reducer is found together with the options bag it
   is handed the live tool-use setter in, and our binding of that setter is
   added to the bag.
@@ -602,7 +617,9 @@ that broke a patch along with every note.
 
 6. Sweep the fix over the versions you still have. `doctor` takes a path, and
    every binary patch-cc has ever touched left a pristine copy in
-   `~/.local/share/patch-cc/backups/`:
+   `~/.local/share/patch-cc/backups/` — which is only the builds *this machine*
+   patched, so `uv run scripts/corpus.py sync` first to make that the published
+   set ([corpus.md](corpus.md)):
 
    ```bash
    sweep() { for b in ~/.local/share/patch-cc/backups/*.orig; do
@@ -879,15 +896,24 @@ for you. Each entry: what it changes, the stable anchor, and where it lives.
     drew beside the landed block for as long as the answer streamed. A
     tool-use entry at the same index is left exactly as the twin leaves it,
     and a list with nothing to drop is returned as it was.
-  - **`display-mode`** defaults the request's thinking display to
-    `"summarized"`; without it the API only streams summary text when the
-    `showThinkingSummaries` setting is on. Two shapes used to be spelled out —
-    the inline env check and the 2.1.216 form that hoists it behind
-    feature-helper calls. They are one edit: the display value gains a
-    default, and whatever guards reach it are untouched because they are never
-    matched. The env-var *name* is the witness; whatever reads it is never
-    described, so a hoisted `process.env` (the same migration that killed
-    `org-label` on 2.1.228) costs nothing here.
+  - **`display-mode`** defaults the `showThinkingSummaries` setting on. Upstream
+    asks the API for `"summarized"` exactly when that setting is on, and routes
+    every consequence — the request's display, the beta header it withholds
+    while summaries are on, the `updates` display the request otherwise falls
+    back to — off one read of it, so that read
+    gains a default (`(settings().showThinkingSummaries??!0)`) and the request
+    is never touched. Every member read of the name, as `spinner-tips` reads
+    its setting, and a write is skipped for the reason it gives; the read is
+    one on every build in the corpus, spelled `settings().name??!1` on all of
+    them, and none of that is claimed. An explicit `false` in the user's
+    settings still wins. Until 2.1.277 this step defaulted the request's
+    display value instead, reached through the `CLAUDE_CODE_DISABLE_THINKING`
+    read that shared its `let` and identified as the consequence of a ternary
+    whose alternative was `void 0`; that build flipped the branches
+    (`!x?void 0:…`) and grew a `"highlights"` mode inside the chosen value,
+    and the step read *found nothing* with every anchor standing. Both claims
+    were syntax between the anchors ([What still takes
+    judgement](#what-still-takes-judgement)).
 
   **What is deliberately not done.** No state of ours: upstream's store carries
   a `streamingThinking` slot with a setter and a thirty-second linger, written
@@ -934,7 +960,10 @@ for you. Each entry: what it changes, the stable anchor, and where it lives.
   slots (2.1.257 — not the compiler arriving, which had cached the
   conversation render since 2.1.247, but this component joining it). The
   reducer half, anchored on the API's event strings, has not moved since it
-  became an insertion at dispatch points. Prefer claims upstream cannot drop
+  became an insertion at dispatch points. The display default broke once
+  (2.1.277), on the branch layout of the ternary that chose the request's
+  value, and moved off the request onto the setting upstream chooses it from.
+  Prefer claims upstream cannot drop
   without paying for them — a dispatch string, a store's field name, the twin's
   own list — over claims only this patch needs, which is what CONDUCT's *ride
   what upstream ships working* asks. What was cut, and why each piece was a

{patch_cc-0.5.2 → patch_cc-0.6.1}/docs/corpus.md

@@ -10,26 +10,32 @@ claim is one command from re-verification instead of a number you have to trust.
 Before the first patch of a version, patch-cc copies the pristine binary to
 `~/.local/share/patch-cc/backups/<version>.orig` ([INTERNALS.md](INTERNALS.md#safety)).
 The corpus is exactly those copies: not a fixture checked into the repo (each is
-~300 MB), but a set that **accretes on its own** as Claude auto-updates and you
-re-patch — and that can be backfilled by saving any pristine native binary under
-the same name. `doctor <path>` reads one; the sweep below reads all of them.
+a few hundred MB), but a directory this machine fills. Left alone it fills
+**unevenly** — a build patched here leaves its `.orig`, a build that shipped while
+this machine sat idle leaves nothing — so the set samples an update cadence rather
+than a release history, and its holes are invisible from inside it.
+`scripts/corpus.py` closes that: Anthropic still serves every build it published,
+so the set is completed off the artifact, like everything else here.
 
 The binaries are the artifact, not this file — `doctor` recomputes every count
-from them, so nothing here can drift from what a matcher actually does. This
-file is a fixed point to check the binaries *against*: a hash that no longer
-matches means the file changed under you, not that a number moved.
+from them, so nothing here can drift from what a matcher actually does. Nor is
+this file where "pristine" is defined: every release manifest carries a
+per-platform sha256 and each `.orig` is checked against it. The table below is
+where that check is written down once per build, so its hashes are the offline
+record for builds Anthropic may one day stop serving — never a second authority
+to keep in step.
 
 ## On disk now
 
-The whole published span `2.1.210` → `2.1.257` — 2.1.230, 2.1.244, 2.1.249 and
-2.1.253–2.1.256 are not on the release channel — one pristine binary per
-version, 41 in all. It straddles the **2.1.242 code split** (INTERNALS.md):
-`2.1.242`/`2.1.243` are the first many-module builds, and they jump ~35 MB over
-`2.1.241` for it. Several pairs share a byte count
-(`2.1.225`/`2.1.226`, `2.1.229`/`2.1.231`, `2.1.239`–`2.1.241`, `2.1.242`/`2.1.243`,
-`2.1.248`/`2.1.250`, `2.1.251`/`2.1.252`)
-and are still distinct binaries, which is why the identity column is the hash (of
-the whole file, `sha256sum <version>.orig`) and never the size:
+One row per pristine binary held, appended as builds ship and never restated — so
+a hash that stops matching means the file changed under you, not that a number
+moved. A gap in the numbering is upstream's rather than a miss: not every version
+reached the release channel, and `corpus.py status` names which, so no list of
+them is kept here to go stale. The set straddles the **2.1.242 code split**
+(INTERNALS.md): `2.1.242`/`2.1.243` are the first many-module builds, and they
+jump ~35 MB over `2.1.241` for it. Sizes repeat across builds, which is why the
+identity column is the hash (of the whole file, `sha256sum <version>.orig`) and
+never the size:
 
 | version | size | sha256 |
 |---|---|---|
@@ -68,26 +74,63 @@ the whole file, `sha256sum <version>.orig`) and never the size:
 | `2.1.243` | 378 MB | `4b0dafeedd0b469c41988e200036fd773e7553ba960349c9f02a82c6d1f2ba27` |
 | `2.1.245` | 392 MB | `16ad2b94deaf7b29abed966d981c9991a47af0420f5be8ed4a3f83bea9f678bc` |
 | `2.1.246` | 248 MB | `1a0a662dc1bb938eaec38545abce9a4a69113d7d7f7c5e1a553ea276617b906a` |
-| `2.1.247` | 239 MB | `5fb321bf417ffc5cd4e3f36e7c9c7e029bf47aaa36d5621db979fcc5e6eabe15` |
-| `2.1.248` | 214 MB | `3edee3cb054bd6823674fd60d5c0e442825b28ee8fbf815af2d16bf0de072e16` |
-| `2.1.250` | 214 MB | `2be252a00ac56e704d7fbf7e5e9ef1243584093334a861945238a0c27e84bdac` |
-| `2.1.251` | 205 MB | `fd5f10ff0eb58daec04900466b143ea98aab50abf208a422bc008eaec13f61f7` |
-| `2.1.252` | 205 MB | `a715a45105e593fc9808d035d77781f88480b9897975a9df41837f0c591bd4b3` |
-| `2.1.257` | 206 MB | `9a64bda9d8722a1fa05bef9a5961d07e0331b99597eda9e2f6a732f3a0ff7f05` |
+| `2.1.247` | 250 MB | `5fb321bf417ffc5cd4e3f36e7c9c7e029bf47aaa36d5621db979fcc5e6eabe15` |
+| `2.1.248` | 224 MB | `3edee3cb054bd6823674fd60d5c0e442825b28ee8fbf815af2d16bf0de072e16` |
+| `2.1.250` | 224 MB | `2be252a00ac56e704d7fbf7e5e9ef1243584093334a861945238a0c27e84bdac` |
+| `2.1.251` | 214 MB | `fd5f10ff0eb58daec04900466b143ea98aab50abf208a422bc008eaec13f61f7` |
+| `2.1.252` | 214 MB | `a715a45105e593fc9808d035d77781f88480b9897975a9df41837f0c591bd4b3` |
+| `2.1.257` | 215 MB | `9a64bda9d8722a1fa05bef9a5961d07e0331b99597eda9e2f6a732f3a0ff7f05` |
+| `2.1.258` | 215 MB | `704f1334ac65d3e89e1c6c1d7663293ad786a6166afdb71b5075337df630f976` |
+| `2.1.259` | 217 MB | `f7dd62ae415378018cd21dd950eb3bac174ab085830304d3b8b098146bfd47b6` |
+| `2.1.260` | 215 MB | `7a2fdc74b6836ea3d183f665b869f0ee3baebc9713cbebffe5838da4ea7bd82e` |
+| `2.1.261` | 216 MB | `4ae40dd1784e85753e742e09f267d29ecbb82890361ad3817d27560866d364a6` |
+| `2.1.263` | 216 MB | `26d020351e8112f4006790f3cfce43b4c9df0c1bb1d0e542364d64151b81d5ba` |
+| `2.1.265` | 216 MB | `e14738e3a58d1fc6ccc23b9c919451b4846bc27074a3fb48db976a7d595bdeeb` |
+| `2.1.266` | 216 MB | `19842705e989393fce936804df6d2ab034860e24b8f8880357981d87ffd83fac` |
+| `2.1.267` | 217 MB | `0399c793ff571d5946ef923d80b4f330d05ac4b6842a6b0775468f5d389403c0` |
+| `2.1.268` | 219 MB | `9691a2b7bd796712ca8cffb8e32e54ff7fc45b662540233171a16a94a0425653` |
+| `2.1.269` | 220 MB | `25e44883f54419569a3d739f38cbbdaebe83b09895da0f343e1b003710a4775b` |
+| `2.1.270` | 224 MB | `3a624a5a7cd79bbad4d32bd7db36f1197ecf458bc5bf1e2aed81834a01ad3ef0` |
+| `2.1.271` | 227 MB | `5e7b6fc24d0e124f68e99a0641c47b662945c6d197d768d7ad7a72cbf1897f58` |
+| `2.1.272` | 227 MB | `d81396a668eb76fbddb49a2a5841f1b5d7af96b4c1f6500ced92f2c988f5bcd4` |
+| `2.1.273` | 229 MB | `6c752e2cc7c110c9df15f26d8d134d438c5ae95dbd610efc1a308bf7f9c5f6c1` |
+| `2.1.274` | 231 MB | `15e2d05148f801b5774032faad87e624ecd172e9903288bda448b892eb58fa07` |
+| `2.1.275` | 232 MB | `13586f3150a7ca1655f36e1dba759fb404e0f7cf7021d4a3dcd5e6f604e56156` |
+| `2.1.276` | 232 MB | `8a56c8a14bd3cb246e2bdb7e60aefe0f609bff78c8bbcc5ea6b1817c111c6145` |
+| `2.1.277` | 234 MB | `722210f05ba494d8f6df69423c4d4f2960900f7a007d0532851c7a36e375cab7` |
+| `2.1.278` | 234 MB | `5c4735937844e84f8a93306e841a5b0e12252909b07870f789b190468da147ab` |
 
 This set covers the span the playbook's tree-move measurements were taken over
 (`2.1.210` → `2.1.233`), the 2.1.242 split, the 2.1.246 stream-store
-migration, the 2.1.247 selector reads it was read back through, and the
+migration, the 2.1.247 selector reads it was read back through, the
 2.1.257 compiled transcript renderer that retired live thinking's render half,
-so each is re-checkable here rather than historical.
+and the 2.1.269 Bun 1.4.3 records that retired the container's record walker, so
+each is re-checkable here rather than historical.
 
-## Rebuild or extend it
+## Keep it complete
 
-The corpus grows every time patch-cc touches a new build — each first patch of
-a version leaves its `.orig` — and a version this machine never patched joins
-the same way: save its pristine native binary as
-`~/.local/share/patch-cc/backups/<version>.orig`. To read the JS a given binary
-carries without patching anything:
+```bash
+uv run scripts/corpus.py            # what upstream serves, against what is held
+uv run scripts/corpus.py sync       # fetch every published build the set lacks
+```
+
+`status` is read-only and exits non-zero when the set is short or damaged. It
+keeps five answers apart rather than counting them together ([CONDUCT.md](CONDUCT.md)):
+`ok`, `missing` (served, not held), `unpublished` (never served — a gap, not a
+miss), `unverifiable` (held, no longer served, so nothing left to check it
+against) and `corrupt` (held, and not what upstream shipped). `sync` acts on
+`missing` alone: a `corrupt` entry is evidence that something here damaged a
+binary, and replacing it silently would destroy the only sign of that — delete it
+and re-run to take a fresh copy.
+
+The span walked is the oldest build held → the channel's head, so no version
+number is written down anywhere; `--since` moves the floor, and builds already
+held are read, tabled and swept whatever the span says. A machine holding
+nothing has made no statement about how far back it cares, so the walk starts at
+the head — `--since` is how a fresh checkout asks for history. A build this machine
+never patched can still join the old way — save its pristine native binary as
+`~/.local/share/patch-cc/backups/<version>.orig` — and the next run verifies it
+like any other. To read the JS a given binary carries without patching anything:
 
 ```bash
 patch-cc extract ~/.local/share/patch-cc/backups/2.1.233.orig > 2.1.233.js