BACKLOG.md

# clode — tactical backlog

Concrete clode-under-Node divergences from native Claude Code, to triage and fix.
(Strategic feasibility risks live in `LONG-TERM.md`; in-flight designs in
`docs/superpowers/`. Done items are DELETED from here — git history is the record.)

## `checkControl` cannot prove a MULTI-DETECTOR guard per-detector (2026-09-13)

**Site:** `test/guard.cjs:96` — `checkControl`'s entire verdict is
`if (r.findings.length > 0) return OK`. Findings are an unlabelled `string[]`, so a control
that trips two detectors is indistinguishable from one that trips one, and a guard whose
scan has several independent checks can lose one of them with its control still green.

**Proven, not argued (2026-09-13):** deleting the filename branch from
`test/no-fuse-gate.test.cjs`'s `scanForFuse` outright left
`guard control: no-fuse-vocabulary can fail` PASSING — the content-control file alone
carried the verdict. The same holds for `test/clode-blobulate.test.cjs`'s
`clode-build-delegates-blobulate`: stubbing its first check to `if (false)` left its
control green too. Both guards' comments claimed the opposite in so many words; the
comments are now corrected to say what a multi-file control actually buys (both branches
exercised, both violation shapes written down as fixtures, a faithful worst-case model) and
what it does not.

**The two shapes this would need** — either is a change to `test/guard.cjs`, not to any
individual gate, which is why no gate's `control()` was worked around to fake it:

1. **Per-detector controls.** `control()` returns a LIST of named cases
   (`[{ name, inputs }]`); `checkControl` runs each and requires every one to produce at
   least one finding, reporting which case came back empty. Simple, no change to what a
   scan returns; costs every multi-case guard one run per case.
2. **A labelled-findings contract.** `scan()` returns findings tagged with the detector
   that produced them (`{ detector, text }`, or a parallel `detectors: Set`), and
   `control()` declares which detectors it expects to trip; `checkControl` compares the
   sets. Stronger (it also catches a control that trips the WRONG detector) and it makes
   findings self-describing everywhere, but it touches every existing guard's scan.

Not urgent: the current contract still catches a wholly blind scan, which is the failure it
was built for. What it cannot catch is a PARTIALLY blind one, and this repo now has several
multi-detector guards (`no-fuse-vocabulary`, `no-retired-spellings`,
`clode-build-delegates-blobulate`), so the gap is worth closing before there are more.

## Bundle scanners: FIXED, with three things still open (2026-08-29)

Two of the three failing rows this entry used to describe are retired. That entry, as
written on 2026-08-29, got the mechanism partly wrong and the prescribed fix wholly wrong,
so the corrections are recorded here rather than deleted:

- The escaping is not "doubly-escaped" and is not the same on both artifacts. Measured
  bytes for one registration: `d.command(\\\"add-from-claude-desktop\\\")` in `cli.cjs`
  (three backslashes) and `d.command(\"…\")` in `graph.json` (one).
- `require("fs")` was not escaped-and-missed, it was ABSENT. Zero occurrences in every
  escape form in BOTH artifacts: at 2.1.243 upstream went code-split ESM and stopped
  emitting CJS requires for builtins entirely (`import{constants as d}from"fs"` now).
- So "decode a graph runner, then pattern-match it" would have fixed neither row. Both
  scanners now read `graph.json`'s `sources` — real strings, no escape level to track,
  and (for the shim map) the module boundaries that scoped binding resolution needs.

**Fixed**: `test/guard-subcommands-gate.test.cjs` (also: selects the highest cached VERSION
instead of the newest mtime, learns the 2.1.243 `usage:`/`aliases:` declaration table, and
fails as a BROKEN SCANNER when it finds nothing). It immediately found real drift —
`sandbox` and `kill` are now in `SUBCOMMANDS`.

**Fixed**: `test/shim-surface.test.cjs`'s alias-scanner canary — and behind it, THE WHOLE OF
LAYER 2 WAS BLIND since 2.1.243 (zero bindings resolved for every builtin but
`worker_threads`, so the gap loop `continue`d past all of them and the stale 2.1.218 list
survived only because the golden test asserts layer 1 first and died on `Bun.ant`).

Still open:

1. **These gates still do not run in CI.** `shim-surface` skips without a provider and
   `guard-subcommands-gate` skips with an empty `~/.cache/clode`; the `test` job has
   neither, so neither has actually run in CI since 2.1.243. This is the worse half of the
   original entry and it is untouched. Give the jobs the inputs that make them run.
2. **Six of the eight newly-visible layer-2 gaps are still unreviewed**: `os.devNull`,
   `fs.fchmod`, `fs.ftruncateSync`, `fs.writev`, `crypto.generateKeyPairSync`,
   `crypto.verify`. Each is a single import site. They are in `golden.json` with a note
   saying they are unreviewed; they need the reachability question the `crypto.*` cluster
   got. **Two are now closed** (2026-08-29): `util.getSystemErrorName` is IMPLEMENTED from
   the engine's own libuv (`uv_err_name` via `tjs.Error`; inverting `os.constants.errno`
   would have been wrong on 18 of 79 names) and differential-locked against host node by
   `test/node-shim-system-error-name.test.cjs`; `zlib.createZstdDecompress` is an
   INTENTIONAL gap — upstream's native `.zst` release downloader — pinned by
   `test/zlib-zstd-stream-gap.test.cjs`, which goes red if the installer neutralizations
   stop applying or if `Bun.isStandaloneExecutable` ever reads true.
   Reachability correction worth keeping: the `getSystemErrorName` call site is the
   dirSync `bun:ffi` anchor (behind bun-shim's throwing `dlopen`), NOT the credentials
   store — it was implemented because nothing feature-detects it, not because it is
   reachable.
3. **`test/node-shim-wall-tripwires.test.cjs` is the third instrument of this family and
   was NOT audited here.** It matches the direct `require("fs").watch(` shape, which
   upstream no longer emits anywhere — so it is green by construction, which is exactly
   the failure mode the other two just had. It is green, so nothing forced the question;
   ask it anyway.

## `Bun.zstdDecompress` / `Bun.zstdDecompressSync` are new golden-map drift, unreviewed (2026-09-02)

`test/shim-surface.test.cjs`'s golden map went red the day it could run against a real
2.1.251 provider again (observed under a central UPSTREAM_PIN provider pin that was tried and then REVERTED in Task 5 round 3 — see the next section; nothing in the tree sets it today):
`layer1_bun_props_missing` grew two entries this repo has never triaged, `Bun.zstdDecompress`
and `Bun.zstdDecompressSync`, absent from `golden.json` and not implemented anywhere in
`libexec/bun-shim.cjs` (grepped: zero hits).

**Not the same gap as `zlib.createZstdDecompress`** (golden.json's own note, right above this
one in the same `_notes` object) even though both are zstd-shaped and both are new since
upstream started embedding zstd-compressed assets at 2.1.251. That one is the NATIVE release
downloader — a single, doubly-walled, build-time-only import site, INTENTIONALLY absent and
pinned by `test/zlib-zstd-stream-gap.test.cjs`. This one is a RUNTIME function pair for
reading upstream's own embedded text assets, found (2.1.251, `~/.cache/clode/2.1.251/graph.json`
module `/$bunfs/root/chunk-t0k3nmf2.js`, carved via clode's own extractor — the same layout
`clode build` produces):

```js
var u=[40,181,47,253];function s(t){return t.length>=4&&u.every((e,r)=>t[r]===e)}
function Z2t(t,e){return d(t)?t:c(e,t)}
async function RX(t,e){let r=await i(Z2t(t,e));return(s(r)?await Bun.zstdDecompress(r):r).toString("utf8")}
function nt(t,e){let r=Z2t(t,e);try{let n=o(r);return(s(n)?Bun.zstdDecompressSync(n):n).toString("utf8")}
  catch(n){throw Object.assign(Error("embedded text asset is missing or corrupt",{cause:n}),{path:r})}}
export{Z2t,RX,nt};
```

`u` is the zstd magic number (`28 b5 2f fd`); `RX`/`nt` read a file (asset-aware via
`__clodeAsset`/`__quaudeRequire`, clode's own patch layer, falling back to a real
`fs.readFileSync`/`readFile`), sniff the magic, and only call `Bun.zstdDecompress[Sync]`
when the bytes are actually zstd-framed — else pass the buffer through untouched. **Not a
single unreachable import**: 43 OTHER modules in the same bundle reference this chunk
(`chunk-t0k3nmf2` appears in 43 module sources besides its own), so this is upstream's
general-purpose embedded-text-asset reader, not a narrow one-off — the reachability
question here is closer to the `crypto.*` cluster's ("the largest cluster... unarmed across
every corpus that ran" — i.e. genuinely open, not yet answered) than to `Bun.ant`'s (answered
and closed).

**MUST NOT be stubbed or added to golden.json without doing that reachability work first**:
same reasoning as `zlib.createZstdDecompress`'s note — a wrong stub here (return the raw
compressed bytes, or throw) would silently corrupt or crash on any embedded asset that
actually IS zstd-compressed, on whatever code path calls `nt`/`RX`. Whether any code path
clode's tested routes (mock `-p` round-trip, agentic corpus, interactive) actually reaches
a zstd-compressed asset through this reader is unmeasured — the two-layer gap inventory
(`test/shim-surface.test.cjs`'s own header) answers "does upstream reach for this API" here,
not "does OUR tested traffic reach it", the same limit its `_notes` already document for the
`crypto.*`/`v8.*`/`net.createServer` gaps.

**Reproduce**: `~/.local/share/clode/providers/2.1.251/claude` (this box's pinned provider,
`UPSTREAM_PIN`) reproduces it —

```
CLODE_PROVIDER_BIN=~/.local/share/clode/providers/2.1.251/claude \
  node --test test/shim-surface.test.cjs
```

stages that provider, measures the two-layer surface, and diffs against `golden.json`; the
diff names exactly these two new `layer1_bun_props_missing` entries. `CLODE_PROVIDER_BIN`
must be set explicitly by hand — see the next section for why `node test/run.mjs` alone will
not find it, on this box or on CI.

### This gate — and every `stageProviderCli`-dependent test — is DARK in CI, not just locally (2026-09-02)

Restates and sharpens item 1 of this file's "Bundle scanners: FIXED, with three things still
open" entry above ("These gates still do not run in CI... Give the jobs the inputs that make
them run") with the specific mechanism, verified while deciding whether to pin
`CLODE_PROVIDER_BIN` centrally in `test/run.mjs` (Task 5 round 3 — the central pin was tried,
found to wake far more than intended, per the failure map below, and was reverted; this
finding is what carries forward instead).

`.github/workflows/suite.yml` is, by its own header comment, "the ONE place `npm test` is
defined for CI" (called by both `ci.yml` on every push/PR and `release.yml` on every tag).
It installs no Claude provider and sets no `CLODE_PROVIDER_BIN` anywhere in the file (grepped:
zero hits for either string). So `node test/run.mjs` — the actual command `npm test` runs, the
same one a `git push` triggers — never has a provider, on ANY CI leg, ever. Every test gated
on `stageProviderCli`/`resolveProviderBin` (test/oracle-models.cjs) silently skips there,
`shim-surface.test.cjs` included: it is not even matched by `ci.yml`'s own separate
`node-shim-oracle` job's `ls test/node-shim-*.test.cjs` glob (line ~428/661) — the file is
named `shim-surface.test.cjs`, not `node-shim-*`, so it is invisible to that job too. Grepped
`shim-surface` across every workflow file: zero hits, anywhere. This golden map has not run in
CI since the scanner was rebuilt on 2026-08-29 (per this file's "Bundle scanners" entry above),
and structurally cannot, in its current shape, in either workflow.

**Same disease, already paid for once**: `ci.yml:483-487`'s own comment records the identical
failure mode costing a 100%-broken `clode-native` binary under fully-green CI ("clode-native's
acceptances 2+3... skip silently without CLODE_PROVIDER_BIN. No workflow named the file, so
they ran ONLY under `npm test`... The binary that is the entire point of the Q1 split was 100%
broken and nothing said a word."). That specific case got a standing guard (a dedicated step in
`ci.yml` that installs the pinned provider and exports `CLODE_PROVIDER_BIN` before driving
`clode-native.test.cjs` directly). `shim-surface.test.cjs` has never gotten the equivalent — it
has no `ci.yml` step naming it at all, named or globbed.

**Not fixed here** (per the coordinator's instruction: map it, do not fix it) — the fix is
either giving `shim-surface.test.cjs` the same kind of dedicated `ci.yml` step
`clode-native.test.cjs` got, or widening `node-shim-oracle`'s glob/`EXCLUDE` handling to also
catch it, or (the `suite.yml`-level fix that would close the gap for EVERY `stageProviderCli`
test, not just this one) installing a provider and exporting `CLODE_PROVIDER_BIN` in
`suite.yml` itself — which is exactly what a centrally-set `CLODE_PROVIDER_BIN` in
`test/run.mjs` would have done locally too, and is why that approach was tried; see the next
section for why it was reverted rather than merely narrowed.

### The three-cause failure map from actually pinning it (2026-09-02, reverted — read before re-attempting)

Task 5 round 3 tried centrally setting `process.env.CLODE_PROVIDER_BIN` in `test/run.mjs` to
the `UPSTREAM_PIN`-pinned provider (mirroring the file's existing central `CLODE_STATE_ROOT`
and `security`-stub pattern) specifically so this gate would stop being dark. It worked — full
suite went from `1667 pass / 5 fail / 87 skip` to `1697 pass / 19 fail / 43 skip` on this box,
a swing of exactly 13 tests (5 known-baseline `naude-shim-boundary.test.cjs` failures, unchanged,
plus 14 new: this file's own gate, correctly, and 13 more). **Only one of the 14 new failures is
the signal this entry is about** — `not ok 1460`, `shim-surface.test.cjs`, red on exactly
`["Bun.zstdDecompress","Bun.zstdDecompressSync"]`, as documented above. The other 13 are three
unrelated, genuine environment/prerequisite gaps this box has, previously invisible only
because the tests that would reveal them have never run for real locally (they all gate on
`CLODE_PROVIDER_BIN`, which nothing ever set before this attempt). Recorded here as the map for
whoever next tries to close the CI-dark gap above, so the same three surprises don't have to be
re-discovered:

1. **zstd unreachable on a deliberately minimal PATH** — `test/clode-native.test.cjs`
   acceptance 2 (`not ok 357`, "the native builder BUILDS THE PRODUCT... node-free AND
   template-free") and acceptance 4 (`not ok 359`, "BUILDS A NAUDE... node absent from PATH").
   Both construct `env.PATH = '/usr/bin:/bin'` on purpose, to prove the fused builder needs no
   node — but on this box `zstd` lives at neither location (homebrew/pkgsrc prefix instead), and
   2.1.251's embedded assets are zstd-compressed, so extraction fails loud and correctly:
   `clode: no zstd tool found on PATH — install zstd...`. Not a bug in clode or in the test's
   intent; whether it also fails this way on a CI runner depends on where THAT runner's package
   manager puts `zstd` (Debian/Ubuntu `apt` typically lands it in `/usr/bin`, which would make
   this pass in CI while failing here — unverified, not run there).
2. **`build/bundle/naude-entry.bundle.cjs` was never pre-built on this box** —
   `test/quaude-naude-updateguard.test.cjs`'s naude precondition (`not ok 1351`, "naude: `clode
   build --naude` builds it") and its dependent deny-turn acceptance (`not ok 1352`). Fails with
   `build-naude: --bundle not found:.../build/bundle/naude-entry.bundle.cjs — Pre-build it with
   'node scripts/build-clode-main.mjs'` — a real, one-time local prerequisite this box's checkout
   has simply never had run against it, unrelated to the provider pin itself.

   **A separate observation from the same run, corrected after a first wrong read**: this
   test's naude build, running for real for the first time, populates
   `build/clode-<version>-<platform>/` in the checkout before failing — traced (NODE_OPTIONS=
   --require against a small stack-logging `fs` shim) to `scripts/build-naude.mjs:590`'s
   `fs.mkdirSync(OUT, {recursive:true})`, where `OUT = artifactDir(REPO)` — REPO-anchored via
   `import.meta.url`, with no cwd or env override, staged UNCONDITIONALLY before the script even
   checks `--bundle` exists. First read this as the tree-immutability violation and "fixed" it
   by having the test `rmSync` that directory in `after()` — **wrong, and reverted**: `build/
   clode-*` is itself a `TREE_ALLOW` entry in `test/run.mjs` ("the sanctioned copy-back target
   for a FINISHED, shippable artifact" — `scripts/platform-tag.cjs`'s header), so it was never
   the thing tripping the guard, and deleting a directory a developer's OWN prior real build may
   have populated is destructive: a test must not delete a shippable artifact just to make a
   guard quiet, and this one would have on any box with a real `build/clode-*` already present.
   The actual violation in that run was `created ._build` and `created build/._clode-…` —
   macOS AppleDouble xattr sidecar files this repo already knows this NFS-mounted checkout
   generates on its own (see the `git gc`/AppleDouble note elsewhere in this project's working
   notes); nothing under this task's control creates or removes those, and no code change here
   attempts to. The `scripts/build-naude.mjs` staging behavior itself (real, and worth knowing:
   it writes into the checkout regardless of `--out`, by design) is recorded here as prose only —
   no test code was kept to act on it.
3. **Residual `/$bunfs/root/chunk-…` edges reaching the quaude-model under tjs** — 9 tests in
   `test/fidelity/*.test.cjs`: `agentic-mcp-ws.test.cjs` (`not ok 685`),
   `agentic-subagent-diff.test.cjs` (`686`), `agentic-tools.test.cjs` ×5 (`687`-`691`),
   `agentic-workflow-complete.test.cjs` (`692`), `slash-command-diff.test.cjs` (`710`). Directly
   confirmed for `685` only — its stderr names the exact residual edge: `im: cannot resolve
   '/$bunfs/root/chunk-1jh2yzqz.js'` from `libexec/node-shim/loader.cjs:269`, the same class of
   break `libexec/clode-extract.cjs`'s own header describes staging as existing to merge away
   (`test/oracle-models.cjs`'s header: "residual cyclic `import.meta.require(...)` edges"). The
   other 8 were NOT individually re-traced to the same root cause — they share the same file
   family, the same quaude-model-under-tjs mechanism, and the same staged 2.1.251 bundle as
   `685`, which is why they are grouped here, but each fails with a different downstream
   symptom (a tool_result POST never arriving, `--continue` not replaying context, a bare
   non-zero exit) consistent with — but not independently proven to be — the same unresolved
   chunk. Whoever picks this up should re-verify each one's actual stderr before assuming they
   are all one bug.

**Not fixed, per instruction.** Do not stub, patch, or pre-build any of the above to make these
numbers go away — each is either a genuine local-box prerequisite gap (1, 2) or an unresolved,
only-partially-traced upstream-bundle-staging question (3), and none of the three is what
`shim-surface.test.cjs`'s own gate (the one signal this whole entry is actually about) needs
fixed. The central-pin approach itself was reverted (`test/run.mjs` is back to byte-identical
with its pre-Task-5-round-3 state on this point) specifically so touching it again doesn't
silently re-wake all 13 at once; the CI-dark gap above should be closed narrowly (per-file or
per-job), not by flipping this switch back on suite-wide.

## Staging a code-split provider now REQUIRES a tjs engine (2026-08-29)

The residual-cyclic-require merge moved out of `libexec/quaude-fuse.js` into staging
(`libexec/clode-extract.cjs`), so the staged graph both targets consume is merged once. That
is the fix for the graph runner — what naude embeds and every node-shim oracle stages — which
was emitted from the UNMERGED doc and died on the first residual require under both of its
hosts (`node-shim: cannot resolve '/$bunfs/root/chunk-….js'` under tjs,
`ERR_REQUIRE_CYCLE_MODULE` under node). Five CI jobs, one cause.

The merge needs the engine's own report of each module's top-level bindings
(`tjs.engine.moduleMeta`; guessing them from minified text stays refused). Staging therefore
resolves an engine — in-process when clode IS tjs, else `CLODE_TJS`, else the checkout's
`build/tjs/<tag>/tjs` — and REFUSES by name when it finds none. What that leaves:

1. **`naude-cross.yml` has no engine.** It cross-builds a naude on a bare ubuntu runner with
   `node bin/clode build --naude`, so it will now fail with the refusal above instead of
   silently producing a naude that dies on its first turn (which is what it has been shipping
   since 2.1.243 — its only assertion is `--version`, which passed throughout). It is
   `workflow_dispatch`-only, so no push matrix is affected. The fix is to give those jobs a
   tjs artifact, or to teach the naude branch to fetch a host engine the way `clode build`
   fetches a template. Until then a hand-dispatched run is red for a stated reason.
2. **The refusal is the only thing standing between a tjs-less host and a broken target.**
   A user with `bin/clode` under plain node and no engine cannot stage a 2.1.248+ provider at
   all now. That is honest but it is a capability regression, and whether the answer is a
   fetched host engine, a bundled one, or leaving the message as it is has not been decided.
3. **Cold staging costs ~1 minute more.** Measured on darwin-arm64 2.1.251 (1836 modules,
   groups of 99/7/5): ~5s of engine CPU for the metadata pass, ~11s for the merge under node.
   Cached with the rest of the stage and keyed on the merger's file signature, so it is once
   per provider per machine — but every CI job that stages a provider pays it once.

## netbsd-sparc's in-guest bake: FIXED here, NOT yet confirmed by CI (2026-08-29)

The bake shipped an engine carrying the C half of `txiki-engine-module-meta.patch` and not
the JS half, because it was the one build path in the matrix that did not run
`scripts/build-tjs.cjs` and so never regenerated `src/bundles/c/**`. The fix does not teach
the guest to regenerate; it stops the guest generating anything at all. The runner now runs
`node scripts/build-tjs.cjs --regen-only` over the same patched tree it already builds, using
the SAME `regenBytecodeArrays`/`assertBytecodeFresh` every other leg uses (a host-native tjsc,
whose canonical-LE output is target-independent by construction), and tars the regenerated
tree. `ci-guest-bake.sh` refuses a tree with no `clode:bytecode-regen` trailer, and its ENGINE
SANITY step is now the shared engine-API floor (`scripts/engine-api-floor.cjs`) instead of a
third hand-written `typeof __tjs_fs_sync` copy — so a missing binding is named in the first
minutes rather than 927 seconds into a fuse.

**Reproduced and fixed locally, end to end, on darwin/arm64** (a `--source-only` tree's
`core.c` has no `moduleMeta` atom; after `--regen-only` it does; a plain guest-style `cmake`
build of the non-regenerated tree yields an engine that fails the floor check with
`MISSING-ENGINE-API: tjs.engine.moduleMeta` and passes the OLD sanity check). **What is NOT
proven: the sparc leg itself.** Nobody has run the 512MB sun4m bake with these changes. Open
questions a CI run answers and nothing here can: whether `tjs run` behaves on the sparc engine
as it does on darwin, whether the extra host-native tjsc build on the runner costs anything
that matters, and whether the leg then gets past the fuse to a green smoke.

**Also still unaccounted for:** the leg's 2026-08-28 reds (upstream 2.1.250) had a 16m33s
smoke and predate BOTH `62cb4e4` (the cyclic-group merge) and `712a0f1` (the moduleMeta
probe), so they were neither of the two causes above. Their console was never captured and
never will be. If sparc goes red again with a shape neither explains, that is where to look.

## The Windows-path ratchet is blind on ~1335 lines of real code (2026-08-29) — RESOLVED 2026-09-04

`test/windows-path-ratchet.test.cjs`'s `stripComments()` blanked `/* ... */` with a
non-greedy regex over the whole file. build-tjs.cjs, clode-fuse.cjs, the node-shim loader and
others embed C and JS *in string and template literals* that contain `/*` and `*/`, so the
pairing ran away and blanked real code, an unknown number of lines across an unknown number
of files (estimated ~1335 across 14, 2026-08-29 — that estimate was never actually measured).

It surfaced by accident: reordering two `const` declarations in build-tjs.cjs changed the
pairing and revealed two pre-existing `process.env.PATH` sites (the cosmocc bin-dir prepend)
that the scan had never seen. They were allowlisted with a reason at the time; the blindness
itself was not fixed until now.

RESOLVED (phase 5, task 9): `stripComments()` is now a real tokenizer that tracks
string/template-literal/regex-literal state (`libexec/scc-merge.cjs`'s `lexicalCodeMask`
already carries the same regex-vs-division heuristic, reviewed and shipped, for a related
purpose). MEASURED, not estimated: the old regex blanked 24,937 lines across 421 scanned
files in total (almost all of that correct — real comments); comparing every one of those
files against the tokenizer isolates the actual bug at 1,950 lines across 45 files that were
real code, not comment. Re-scanning every RULE against the newly-visible text surfaced exactly
ONE previously-invisible match: `test/run.mjs`'s own `npmCliPath()`, the fourth instance of
the same already-known "POSIX half of a correctly-branched pair" shape as the three existing
`npm-global-layout` ALLOWED entries — reviewed, not a bug, allowlisted the same way. The gate
is migrated onto `test/guard.cjs`'s `defineGuard`, with `floor` set to the measured
lines-examined count (50,892 non-blank lines) so a future regression back to the old regex
reports BROKEN rather than quietly passing. Full commands and output: see
`.superpowers/sdd/2026-09-04-phase5-gates-that-can-fail/task-9-report.md`.

## No CI leg carves a zstd row in a guest any more (2026-08-29)

RESOLVED, and this is the residue. `netbsd-sparc` was red because its guest — our own pinned
`wd0` image — has NO zstd, unzstd or zstdcat anywhere (verified by booting that exact image
under `qemu-system-sparc`: `which zstd` -> not found, sets base/comp/etc/gpufw/misc/modules/
rescue/tests), and no `guest-packages` to add one. From 2.1.251 upstream embeds its assets as
zstd frames, so the in-guest carve threw. `scripts/make-min-provider.cjs` now decompresses
those rows on the runner, and `stage-provider.mjs` minimises for EVERY leg — so as of this
change **no CI leg carves a compressed row inside a guest at all**. What that leaves:

1. **The shipped `zstd`-spawn path (libexec/host-provision.cjs + bun-graph's `zstdViaCli`) has
   no end-to-end coverage.** It is exercised by unit tests (`opts.forceCli` exists precisely to
   pin the two decoders to byte-identical output) but nothing now runs it inside a real guest
   against a real provider. `ZSTD_SOURCE` in `test/tjs-legs.test.cjs` still records where each
   guest's decoder comes from, which keeps the question visible, but those rows are no longer
   load-bearing for any green run. A leg that carves a REAL provider in-guest would restore it.
2. **A real user on a host without zstd still cannot `clode build` from a real provider.** The
   failure is honest and actionable ("Install `zstd` (or point CLODE_ZSTD at it)"), and pkgsrc
   has zstd — but NetBSD base does not, so this is the shape a NetBSD user meets. Whether the
   answer is a bundled decoder, a fetched host applet, or leaving the message as it is has not
   been decided.

## RELEASE GATE for 0.20260827.1 (user, 2026-08-25) — BOTH must hold

**Re-dated 2026-08-27**: the cut was staged on the 25th and took two more days of
upstream absorption (2.1.246, 2.1.247) plus the Renovate merges. Date versioning
means the tag names the day it ships, not the day it was drafted.

    1. CI is GREEN
    2. ALL Renovate PRs are MERGED

Neither is "mostly". Nine PRs are open as of 2026-08-25:

    #38 wrap-ansi 10.0.1        #37 docker/setup-buildx-action   #36 esbuild 0.28.2
    #35 ws 8.21.3               #34 cross-platform-actions       #33 attest-build-provenance
    #32 debian:bookworm-slim    #31 node.js 26.7.0               #30 node.js 24.19.0

**THE ORDERING MATTERS, and it is not the obvious one.** These interact:

1. Get main green. Renovate PRs cannot merge while the base is red — `automerge: true`
   with no `ignoreTests` means they wait for a green base.
2. **STOP CANCELLING THE PR RUNS.** The user gave standing permission to cancel them
   "until we get to the green end of this problem", and they have been cancelled
   repeatedly today to free runners. That permission EXPIRES at green: the PRs need their
   own green runs to auto-merge, so cancelling past that point actively prevents gate (2).
3. Let them merge. Each merge moves main.
4. **Re-verify green AFTER the merges** — node 24.19.0 / 26.7.0 and esbuild 0.28.2 are
   not cosmetic; they touch the toolchain that builds the engine and the JS bundles. A
   green run from BEFORE the merges does not satisfy gate (1) for the commit being tagged.
5. Only then tag.

**EXPLICITLY NOT IN THIS RELEASE (2026-08-26):** vm.SourceTextModule /
vm.SyntheticModule, and therefore plugins that register tools by running JavaScript. It
needs an engine change (see its own section), it would invalidate the matrix green this
gate is about, and it regresses nothing — 2.1.245 has the same gap. First item next cycle.

So the honest reading is that gate (1) must hold TWICE: once to unblock the merges, and
again on the merged result that actually ships. Tagging a commit whose CI predates the
dependency bumps would satisfy the letter of both gates and the spirit of neither.

## ★★ CONTINGENCY — what we do if upstream ships `bun build --bytecode` (2026-08-28)

**The risk.** Everything clode does rests on the Bun container holding real JavaScript that
`libexec/extract-claude-js.cjs` can lift out. Bun can instead embed **JSC bytecode**
(`bun build --bytecode`), which skips parse at startup. Cold start and install size are
demonstrably what upstream is tuning right now — the binary went 345 → 197 MB over five
releases while the chunking strategy flip-flopped (test/fixtures/bundle-shapes.tsv) — so this knob is
plausibly one release away, and nobody upstream would think of it as a breaking change.

If it is flipped, extraction does not get harder. **It stops being possible.** There is no JS
to carry, and JSC bytecode is a JavaScriptCore artifact: QuickJS cannot load it, and it is
neither documented nor stable across Bun versions. `test/bundle-shape.test.cjs` is the
tripwire; this entry is what to read when it goes red.

**Options, roughly best to worst.**

1. **Get the JS from npm instead of the binary.** The `@anthropic-ai/claude-code` package is a
   thin wrapper today, but the per-platform payload is still built from JS upstream must
   produce. If any published artifact (a sourcemap, an unminified build, a `--no-bytecode`
   variant for some platform) still carries JS, the extractor's input changes and nothing else
   does. CHECK THIS FIRST — it is the difference between a bad week and a new project.
2. **Ask upstream for a JS-bearing artifact.** Not a technical fix, and not to be dismissed on
   that account: a documented "sources" tarball would make this whole class of breakage go
   away permanently. Worth asking BEFORE the emergency, not during.
3. **Run JSC.** Bytecode is only loadable by the JavaScriptCore version that produced it, so
   this means shipping JSC — which does not build for Tiger PPC, sparc, m68k, or most of the
   fleet. It would save the mainstream legs and kill the interesting ones, which inverts the
   point of the project.
4. **Decompile the bytecode.** JSC bytecode is undocumented, unstable release to release, and
   optimised. A decompiler is a research project with no upper bound, and it would need
   redoing on Bun bumps. Not credible as a plan.
5. **Freeze on the last JS-bearing release.** Directly against
   [[keeping-up-is-the-job]]: a quaude that lags is the failure mode, not the safe option. Only
   defensible as an explicit, dated, written-down stopgap while 1 or 2 is pursued.

**The honest summary: option 1 is the plan and options 3-5 are what "no plan" looks like.**
That is worth knowing NOW, because it means the useful preparation is not engineering — it is
(a) the tripwire, so we learn on day zero, and (b) finding out whether any JS-bearing artifact
exists, which can be answered today, cheaply, while nothing is on fire.

**ARTIFACT SURVEY 2026-08-28 — is there a JS-bearing artifact besides the binary? NO. But the
survey paid for itself twice.** Run because the JSC-bytecode contingency's only credible option
is "get the JS from somewhere else", and that is worth answering while nothing is on fire.

**What upstream publishes.** `@anthropic-ai/claude-code` is a wrapper (`cli-wrapper.cjs`,
`install.cjs`, `bin/claude.exe`, type declarations) whose real payload is a per-platform package
(`@anthropic-ai/claude-code-darwin-arm64` etc.) containing exactly one thing: the binary. No
`cli.js`, no sources. NB this packaging is NOT new — it predates 2.1.238, so it is not one of
the recent structural changes.

**`@anthropic-ai/claude-agent-sdk` (0.3.250 — its trailing number tracks Claude Code's 2.1.250)
ships real unbundled JS**: `sdk.mjs` 1.4MB, `bridge.mjs` 1.4MB, `browser-sdk.js` 1.3MB, and
`extractFromBunfs.js` shipped deliberately verbatim as the `./extract` export. **It is a CLIENT,
not the core**: 55 `spawn` references, and it drives the binary rather than implementing the
agent loop. 1.4MB against the binary's ~32MB of module sources settles it by size alone. So it
does NOT rescue us from bytecode.

**CONCLUSION FOR THE CONTINGENCY: option 1 currently has no answer.** No published artifact
carries the core as JavaScript. That does not make the contingency worse, it makes option 2
(ask upstream for a JS-bearing artifact, BEFORE we need it) the live one, and it is now backed
by a concrete observation: `manifest.json` publishes a source `commit` hash, so the build is
reproducible from a tree they hold.

**Two things worth having ANYWAY, independent of bytecode:**

1. **`manifest.json` is an official integrity source, and it is correct.** It carries
   `version`, `commit`, `buildDate`, and per-platform `{binary, checksum, size}`. VERIFIED: its
   `darwin-arm64` checksum `506d7362a9c625306044879a9d91d8f33bd2eef963681b56be3295db5fe3e34b`
   matches the binary we downloaded, byte for byte.
   **CORRECTION (same day): `clode fetch` ALREADY does this.** `libexec/clode-update.cjs`
   downloads `<releases>/<ver>/manifest.json`, pulls the platform checksum, and calls verifying
   against it mandatory — "upstream's integrity gate", in its own header — provisioning the
   digest tool BEFORE the ~200MB transfer so a toolless host fails instantly. I claimed
   otherwise here by inferring from the survey instead of reading the code. Nothing to build.
2. **`manifest.zst.json` describes a zstd channel: 63.7MB instead of 206MB**, a 3.2x smaller
   download for the same content — and THIS one is a real, unexploited gap: `clode-update.cjs`
   mentions zst exactly zero times. It would pay on slow links and on every CI leg that pulls a
   provider. The cost is a zstd decompressor on the host, which is the host-applet pattern
   again (see `provision('sha256')` in the same file for the shape) plus a fallback to the
   plain binary when none is available — so it is additive, not a rewrite.

**Also worth reading properly: `extractFromBunfs.js`.** It is upstream's own supported way to
lift a file out of `$bunfs`, shipped unbundled and Node-importable on purpose. It documents
container behaviour we reverse-engineered, and its existence says upstream treats extracting
from `$bunfs` as a legitimate thing to do — useful context if we ever do ask them for sources.

## ★★ P0 — upstream 2.1.248+ CYCLICALLY require()s graph modules; every tjs leg is red (2026-08-28)

**Status: quaude (tjs) BLOCKED. naude (node) is FINE — verified, unpatched.** We released
0.20260827.1 against 2.1.247. CI installs the provider at `latest`, so when 2.1.248 landed
every tjs leg started failing at once, 22 of 38 jobs. npm `latest` is 2.1.250 as of writing.

**The symptom.**
    node-shim: cannot resolve '/$bunfs/root/chunk-wvte6g1r.js' from /quaude

**What actually changed.** 2.1.248 began emitting CJS `require()` of graph modules INSIDE the
graph. Measured on the extracted graphs, same extractor, two versions:

| | 2.1.247 | 2.1.250 |
|---|---|---|
| `require()` of a chunk | **0** | **358** (across 65 modules) |
| dynamic `import()` of a chunk | 1075 | 1095 |
| modules in graph | 1464 | 1814 |
| `@bun-cjs` blocks | 95 / 18 | 665 / 588 |

e.g. `require("/$bunfs/root/chunk-8ry2mchg.js").udsInboxShape`

**Why node survives and tjs does not.** The graph runner's node path installs
`module.registerHooks()`, which intercepts `require` as well as `import`, so a graph
specifier resolves there for free — 2.1.250 runs under node with NO patch (`--version` and
`--help` both fine). The tjs path has no hook: the call sits inside a `@bun-cjs` wrapper whose
`require` is the SHIM's, so it reaches `moduleLoad`, takes the absolute-path branch, and
throws for a module the graph is holding in memory.

**THE CONSTRAINT THAT KILLS THE OBVIOUS FIXES: these requires are CYCLIC.** That is *why*
upstream uses `require` and not `import` — CJS require returns partial exports mid-cycle, and
upstream depends on that.

**Four designs tried and measured, all rejected. Do not re-try these blind:**

1. *One bridge module static-importing every require()d chunk, imported by the entry.*
   Resolves the specifiers and also EAGERLY evaluates 193 chunks upstream loads lazily.
   Measured: node went from `2.1.250 (Claude Code)` exit 0 to **exit 1**, because one of them
   reaches the ws path and exits when `ws` is absent. Eager evaluation is not a neutral way to
   obtain a namespace.
2. *Rewrite the call sites to `__quaudeRequire` / `globalThis.__quaudeRequire` /
   `import.meta.require`.* All three throw inside these chunks under tjs — "not a function",
   "cannot read property '__quaudeRequire' of undefined", "cannot read property 'meta' of
   undefined". The call site is in a CJS wrapper: no `import.meta`, and the bundle's own
   scopes shadow those globals. The `require` in scope is a function PARAMETER from the shim.
3. *Rewrite the call sites to ordinary static imports* (the path the other ~14,800 edges take).
   `planGraph` rejects the graph outright: `import cycle chunk-2yxpncxe -> chunk-ghnc2x4f`.
   This is the experiment that proved the cyclic premise.
4. *Runtime resolver: each require()d module publishes its namespace, shim asks the runner to
   evaluate on demand.* Gets furthest and is where the real wall is. Publishing at the END of
   the body is too late for a cycle; publishing at the TOP (live namespace object, partial
   bindings — the ESM analogue of what CJS gives) gets past resolution and then hits the
   engine itself:
       SyntaxError: circular reference when looking for export
         'AGENT_VIEW_RELAUNCH_ENV_KEY' in module '/$bunfs/root/chunk-rjzfxnpd.js'
   QuickJS will not build a namespace for a module mid-cycle. `tjs.engine` exposes only
   compile/serialize/deserialize/evalBytecode/gc/features/versions — no way to drain pending
   module jobs, and `evalBytecode` on a module whose deps have not run does not run its body
   synchronously. Evaluating the dependency CLOSURE instead is not a smaller hammer: measured
   mean 375 and max 908 modules of 1814, i.e. design 1 wearing a different hat.

**EXPERIMENT 3 (2026-08-28): pre-evaluate the closure. FAILED, and it settles the fork.** The
idea was to evaluate the require()d modules UP FRONT so nothing is evaluated re-entrantly, since
re-entrant evaluation is what SIGSEGVs. Three variants, each measured:

- *Each required module publishes its own namespace* (prepend `import * as self from "<self>"`).
  **93 of 193 modules then failed to evaluate at all**, every one with `circular reference when
  looking for export ...`. A self-import makes export resolution circular. This is the same
  wall probe 1 hit, now quantified: the trick corrupts half the set.
- *Publish from separate one-line modules instead* (`import * as ns from "<spec>"; __CLODE_NS[spec] = ns`),
  which keeps upstream's sources VERBATIM and the export graph acyclic. All 193 publishers
  reported success — **and only 29 namespaces appeared.** `evalBytecode` returned without the
  body having run for 164 of them.
- *Await what evalBytecode returns.* It does return promises (`pending=193 thenable=193`), so
  the deferral is real and visible. **They never settle**: evaluating a publisher triggers
  upstream's own `require()` of another chunk, that require fails, and the failure rejects the
  evaluation. The dependency must be evaluated to answer a require that is needed to evaluate
  the dependency.

**THE ENGINE PROPERTY, stated once so it is not rediscovered a fourth time: module evaluation
here is DEFERRED, and cannot be driven to completion synchronously from inside a require.**
`tjs.engine` exposes compile/serialize/deserialize/evalBytecode/gc/features/versions — nothing
that drains pending module jobs. Every JS-side design founders on this, not on cleverness:
- on-demand evaluation — SIGSEGV (re-entrant `js_evaluate_module`)
- self-published namespaces — circular export resolution, 93/193 dead
- externally-published namespaces — bodies do not run, 29/193 land
- awaiting the evaluation promises — deadlock against upstream's own requires

**VERDICT: the extraction route wins, by elimination and on evidence rather than taste.** Emit
each cyclic require group as ONE module so the cycle never crosses a module boundary; the
engine then never has to answer a require for a module it is mid-way through evaluating. It
costs the verbatim property and a mini-bundler's worth of care (top-level name collisions,
export rewriting, per-module `import.meta`), and those costs are real — but they are ordinary
engineering in our own JS, against an engine change that three experiments say is not small and
lives in the module evaluator every leg depends on.

**Do it narrowly.** Per the shape record, 2.1.250's cyclic shape may not outlive the week —
2.1.243's did not. Merge only the modules that are actually in a cycle WITH a CJS require,
leave the other ~1600 untouched, and keep the merge behind a check so a bundle without cyclic
requires takes exactly the path it takes today.

**PROBE 2 (2026-08-28): can a namespace be built after INSTANTIATE without EVALUATE? YES — and
the engine route still does not close.** This is the probe the previous entry asked for, run.

`JS_EvalFunction`'s module branch does three things at once and consumes its argument:
`js_create_module_function` → `js_link_module` → `js_evaluate_module`. Both linking functions
are static, so separating the ESM phases needs a quickjs.c patch, not just a txiki binding.
Added `JS_InstantiateModule` (create+link, no evaluate, no free) and `JS_EvaluateModuleOnly`
(evaluate an already-linked module, no re-link, no free), exposed as
`tjs.engine.instantiate/evaluateOnly/namespaceOf`.

MEASURED, in order:
- `instantiate()` on a compiled module: **works**.
- `namespaceOf()` after instantiate, module NOT evaluated: **works, returns a real namespace
  object, clean exit 0.** Reading an uninitialised binding throws `x is not initialized` —
  TDZ, which is CORRECT ESM semantics for a cycle. This directly refutes probe 1's reading:
  the earlier crash was calling `namespaceOf` on a NON-instantiated module, not a limit on
  namespaces for unevaluated ones.
- Wired into the graph runner + shim, `require("/$bunfs/root/chunk-*.js")` **stops failing to
  resolve** — the "cannot resolve" error is gone. Upstream then hits
  `TypeError: Cannot convert undefined or null to object` in `Object.entries`, because a
  linked-but-unevaluated namespace hands back uninitialised bindings as undefined.
- So the module must also be EVALUATED on demand. `evalBytecode` there **SIGSEGVs** (its
  module branch re-creates, re-links and FREES a module we still hold — the "refcount should
  be >= 2" comment in quickjs.c is about exactly this). `evaluateOnly`, which avoids all three,
  **also SIGSEGVs**: `js_evaluate_module` is being re-entered while another module is
  mid-evaluation, which is the cyclic case by definition.

**Conclusion. The wall is re-entrant module evaluation, not namespace construction.** Making
that safe is real QuickJS work in the module evaluator — the riskiest part of the engine, and
the part every leg depends on. Two probes have now each shown the engine route to be larger
than it looks from the outside, so treat "it is only a small binding" as a claim already
refuted twice.

**Still-open engine idea, cheaper than fixing re-entrancy:** evaluate the required module's
dependency closure BEFORE the entry runs, so nothing needs evaluating mid-cycle and
`instantiate` + `namespaceOf` alone suffice. Measured closure sizes are mean 375 / max 908 of
1814, so this is eager-ish and has the ws-exit hazard of design 1 — but it is bounded, it is
JS-side, and it needs no evaluator change.

**ENGINE EXPERIMENT RUN 2026-08-28 — `engine.namespaceOf` is NOT the cheap fix.** The reasoning
that motivated it was: `JS_GetModuleNamespace` is a public QuickJS API (`quickjs.h:1191`) that
`qjs.c` itself calls, so exposing it should be a binding onto an existing function — tens of
lines of C — rather than new module semantics. That reasoning was sound and the conclusion was
still wrong. Measured, so nobody re-runs it:

- Added `tjs_namespaceOf` to `src/mod_engine.c` (`JS_ResolveModule` then `JS_GetModuleNamespace`)
  plus the `src/js/core/engine.js` wrapper, as a real patch in `spike/quickjs/patches/`. NB the
  build RESETS the vendor tree and replays the patch list, so editing
  `~/.cache/clode/tjs-vendor/txiki.js` directly is silently discarded — it must be a patch file
  registered in `scripts/build-tjs.cjs`, and `git diff` there needs `a/`+`b/` prefixes or
  `git apply` rejects it.
- Engine rebuilt; `namespaceOf` appears in `Object.keys(tjs.engine)`.
- **After evaluation it works**: `ns after eval: object x=42`.
- **Before evaluation it kills the engine** — no exception, no output, process gone. And even
  the success path exits **134 (SIGABRT)**, so the binding also mismanages a reference.

**Why that matters for the decision.** The whole point was to answer a require for a module that
has NOT run (cyclic, mid-evaluation). A namespace that only exists post-evaluation answers the
easy case we did not have. `JS_ResolveModule` links but does not put the module in a state where
a namespace can be built, so the engine route is NOT a small binding: it needs the instantiate
phase handled properly, cycle semantics thought through, and the refcounting right — in the
module linker, which every leg depends on.

Revised lean: the two options are closer than they looked, and the engine's advantage (small,
general) was mostly imaginary. Before committing to either, the cheap next probe is whether
QuickJS can build a namespace after an explicit INSTANTIATE without evaluate; if it cannot, the
extraction route (emit each cyclic group as one module) becomes the pragmatic answer despite
losing the verbatim property.

**Where that leaves it — the fork is real and needs a decision:**
- **Engine.** Teach the engine to answer a synchronous require of a mid-cycle module (a
  namespace with TDZ bindings rather than a hard error). Matches Bun's semantics; a txiki/
  quickjs patch, and the kind of thing canonical-LE and the atomic shim already precedent.
- **Extraction.** Detect each cyclic require group and emit it as ONE module, so the cycle
  never crosses a module boundary. No engine change; a real change to planning.

**Reproduce (local, ~2 min/iteration, no CI needed):**
    npm i --ignore-scripts @anthropic-ai/claude-code-darwin-arm64@2.1.250   # binary is per-platform now
    node libexec/extract-claude-js.cjs <that>/claude /tmp/run/x.js
    cp -R libexec/bun-shim.cjs libexec/node-shim /tmp/run/
    ./build/tjs/macos-26-arm64/tjs run libexec/node-shim/loader.cjs /tmp/run/x.js --help
`--version` passes on a broken graph — it never reaches these modules. `--help` is the cheap
trigger. NB `build/tjs/tjs` is stale and the shim rightly refuses it; use the per-platform one.

### THE GRAPH IS PER-PLATFORM, AND A DARWIN REPRO IS NOT A LINUX REPRO (2026-08-28)

The merger's first shipped build passed its own smoke against the darwin-arm64 provider and
failed 16 CI legs against the linux-x64 one, **same upstream version**. Bun constant-folds
`process.platform` at build time (see `carve-platform-constant-folding`), so each platform's
binary carves to a DIFFERENT module graph: 2.1.250 is 1777 modules on darwin-arm64 and 1773 on
linux-x64 (2.1.251: 1799 / 1795). Same three SCCs, 7/95/5 — but different collision sets, so a
name that is only a property key on one platform is a colliding top-level binding on the other.

**When a CI leg fails and the local build passes, match the PLATFORM of the provider, not just
the version.** The carve never executes the binary, so a linux provider carves and fuses fine on
a Mac and reproduces the leg exactly. `make-min-provider`'s own "N modules + M text assets" line
is the fingerprint to match against the CI log:

    node -e 'fetch("https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64")...'  # tarball
    node scripts/make-min-provider.cjs <that>/claude /tmp/provider-min-lx
    CLODE_CLAUDE_BIN=/tmp/provider-min-lx CLODE_CACHE=... ./bin/clode build --out /tmp/q

Left open: nothing in CI or the local suite builds against more than one platform's graph, so
this class of divergence is still found by a red leg rather than by us.

### (SUPERSEDED by the codeMask memo below) The merge is ~45% slower than Task 3 measured

`propertyNames` adds a second full scan to `codeMask`, which every `maskedReplace` calls: the
95-module group went 14.0s -> 19.5s under node, so expect ~380s -> ~550s under tjs, per leg,
cold. Still inside the 1800s fuse budget on the boxes measured, and unmeasured on the emulated
ones. The three levers are unchanged and are all better than shaving this scan: cache the merge
under `~/.cache/clode` keyed on the provider, do the string work where it is 31x faster, or stop
recomputing `codeMask` from scratch inside every `maskedReplace`.

### CONTEXTUAL KEYWORDS: `of` is not reserved, and neither are the member modifiers (2026-08-28)

Round two of the same class as the property-key bug, one position over. `of` is a CONTEXTUAL
keyword, so a member may legitimately declare a top-level binding named `of` — darwin-arm64
2.1.251 has one doing `import{of}from"<chunk>"` — and when another member of its cyclic group
declares `of` too, the collision rename rewrites the KEYWORD in every for-of header in the merged
module. 2137 of them, and the group stops parsing:

    Error: quaude-fuse: compiling /$bunfs/root/__clode-scc-1.js failed:
      expected 'of' or 'in' in for control expression

`in` cannot do this — it IS reserved — so `of` is the only for-header case. The same hazard sits
one position over in `{ get x(){} }`, `{ async y(){} }`, `class C { static m(){} }` and
`async function f(){}`: all four modify a member/declaration and all four are ordinary
identifiers a member may declare. Fixed positionally (never by excluding the word — a real
binding named `of` still has to rename), and `assertNoRenamedFixedNames` now covers it with a
rule that needs no header parsing: **two identifiers never sit side by side in JS**, except after
`in`/`instanceof`/`of`/`as`/`from`/`extends`.

**Still unguarded, same class, not yet seen in a real graph:** `async x => y` and `async (x) => y`
(genuinely ambiguous with a call to a function named `async`), and `let`/`static` in the handful
of positions where they are not reserved.

### THE PLATFORM CACHE KEY DOES NOT SURVIVE MINIMISATION — d5da54c is a no-op on every CI leg

`providerPlatformOf` reads the container magic, and `scripts/make-min-provider.cjs` emits a
SYNTHETIC container that has none. Measured:

    darwin   REAL darwin-arm64 2.1.250          null   MIN darwin-arm64 2.1.250
    linux    REAL linux-x64 2.1.250             null   MIN linux-x64 2.1.250

Every leg that builds goes through `stage-provider.mjs`, which minimises unconditionally — so the
platform half of the new cache key is `null` for exactly the providers CI builds from, and a
linux carve and a darwin carve of the same version still share a key there. The keychain P0 is
fixed only for un-minimised providers. The fix belongs in `make-min-provider.cjs` (carry the
source container's platform forward, or record it beside the output and have
`providerPlatformOf` read it) — not in the cache key, which is right.

### THE MERGE IS NOW FASTER THAN BEFORE ANY OF THIS — the lever was memoising codeMask

`maskedReplace` recomputed `codeMask(src)` from scratch on every call, and `mergeGroup` routes
~20 passes per member through it. Measured on the real 99-module group: **5124 codeMask calls,
1115MB scanned, 3955 of them (77%) handed the same text as the previous call** — a pass whose
regex matches nothing returns an equal string. A one-entry memo took the group from 28.0s to
5.9s under node. For scale, the same group took 14.0s before the property-key work and 19.5s
after it, so the merge is now ~2.5x faster than the code that shipped before any of this.
The remaining levers are unchanged: cache the merge under `~/.cache/clode` keyed on the provider,
and do the string work where it is 31x faster than tjs.

## IN-FLIGHT HANDOFF (2026-07-31) — what's being juggled

Driver = the at-desk release-readiness plan (`docs/superpowers/plans/2026-07-28-at-desk-release-readiness.md`).

1. **Cosmo APE leg (Task 4b) — CLOSEST TO SHIPPABLE.** ✅ MCP-ws sha-1/endian bug fixed
   (`patches/libwebsockets-cosmo.patch`, wired into build-tjs.cjs); ✅ FULL agentic fidelity suite
   GREEN on the cosmo APE at parity with native (mcp-ws, tools 5/5, node-shim-agentic, workflow,
   subagent-diff) via the now-APE-aware harness; ✅ interactive + tty fixes landed earlier. REMAINING
   before ship: (a) a clean-from-scratch `build-tjs.cjs --target cosmo` + `agentic-mcp-ws` green in CI
   (gold-standard; the committed patch is byte-identical to the verified scratch build); (b) the
   multi-OS CI fan-out (run the SAME `.com` on Linux/mac/Windows/BSD runners); (c) flip the `cosmo`
   leg `publish:true` in `scripts/tjs-legs.mjs` + ship UNSIGNED with a documented Gatekeeper/quarantine
   note (decided: ships as `clode-<ver>-cosmo.com`). See memory `cosmo-libc-additive-leg`.

2. **Tiger / darwin-ppc agentic-turn deadlock — FIX IMPLEMENTED, arm64-PROVEN, ppc pending (2026-07-31).**
   The poll(2) event backend for old Darwin is IN (`fixupLibuvPollBackendOldDarwin`, knob
   `CLODE_TJS_DARWIN_POLL=1` → cmake `CLODE_DARWIN_POLL`, leg field `darwin-poll:true` on
   darwin-ppc + darwin-x86). It swaps `kqueue.c`→`posix-poll.c` + `no-fsevents.c` and drops
   `UV_HAVE_KQUEUE`, which also moves child-exit to SIGCHLD and async wakeups to pipes — so
   sockets, pipes, child exit, DNS/threadpool wakeups and signals ALL leave kqueue in one
   change. TTYs keep the proven select()-thread path. Accepted loss: `uv_fs_event`→ENOSYS
   (the shim's fs.watch is already a non-firing stub, and cosmo ships this way). PHASE 1
   GREEN on arm64: a poll-backend engine passes the full agentic gate (11/11, no skipped
   oracles) + the node-shim suite (166 pass/0 fail). Spec:
   `docs/superpowers/specs/2026-07-31-old-darwin-poll-backend-design.md`.
   **PHASE 2/3 ON REAL TIGER HARDWARE (2026-07-31): the kqueue deadlock is GONE; a SECOND,
   DISTINCT live-API stall remains.** With a hand-cross-built ppc poll engine (Mach-O ppc,
   `uv__kqueue_init` absent) cross-fused into a quaude and run on the Tiger VM against the
   deterministic mock: `-p` turn **exit 0, "Paris", first byte 337ms** (was: parked in
   `kevent` forever, mock received NOTHING); **Bash `outcome=ok`**; **Write actually wrote**
   `NEEDLE-TIGER-WRITE` to disk; Read closed its two-turn loop; the **TUI renders** (welcome
   box, animated spinner, theme picker, syntax-highlighted diff) **and accepts keystrokes**
   (advanced theme -> API-key -> OAuth screens). The bare poll engine also does **real
   HTTPS/TLS**: `fetch(api.anthropic.com/api/hello)` -> 200 in 275ms. So sockets, pipes,
   child-exit, async wakeups, signals, tty input and TLS all work under `poll(2)` on Darwin 8.
   **STILL RED — the fused quaude against the REAL api.anthropic.com stalls** during
   "Starting background startup prefetches", BEFORE any `/api/hello`. Signature: main thread
   parked in `poll`, all 4 threadpool workers idle in `uv_cond_wait`, **zero external
   sockets**, no child processes — i.e. awaiting something that never posts, the same CLASS
   as the original bug at a LATER phase. Reproduced with the real HOME *and* with a clean
   HOME holding only `.credentials.json`, so it is NOT plugin/session state. NOT a
   regression (the original bug hung the live path too, and hung the mock path, which is now
   fixed) — but it is what stands between Tiger and daily-drive fidelity. NEXT: instrument
   the prefetch path (the shim's `CLODE_SHIM_TRACE=1` fetch wrapper is baked into the fused
   loader, no re-fuse needed) to find which await never resolves.
   ALSO PENDING: the `darwin-ppc` CI leg has never built with `darwin-poll:true` — the
   engine proven here is a hand cross-build, so nothing shipped carries the fix yet.

   **THE RESIDUAL STALL IS ISOLATED (2026-07-31, REPEATABLE MATRIX, n=2 per row).** It is NOT
   the event loop, NOT DNS, NOT TLS, NOT the keychain. Harness: `/tmp/matrix.sh` on the Tiger
   VM — each row a fresh HOME, 420s hard limit, records exit code + elapsed + whether
   `API REQUEST` appears (so a fast wrong-reason exit can't pass as a round-trip):
     A mock via IP  (http://10.0.2.2:8790)        PASS x2  40-50s  "Paris"
     B mock via HOSTNAME (10.0.2.2.nip.io:8790)   PASS x2  40-50s  "Paris"   <- DNS exonerated
     C real api.anthropic.com + INVALID key       PASS x2  50s     "Invalid API key" <- TLS exonerated
     F real api + NO key, NO creds file           PASS x2  50s     "Not logged in"
     D real api + creds file, no key              HANG x2  >420s   apiReq=0
     E real api + creds file + invalid key        HANG x2  >420s   apiReq=0
   => **the mere PRESENCE of `~/.claude/.credentials.json` is necessary and sufficient**;
   both key states pass without it, both hang with it, and the hang is BEFORE any API request.
   RULED OUT with evidence: DNS (row B; plus NXDOMAIN/bogus hosts reject in ~343ms on the
   engine); TLS to the real endpoint (row C reaches a real API request); async-DNS UDP sockets
   (idle resolver sockets, not pending queries); `probeInternalNetworkAccess` (it is literally
   `async function vzm(){return null}`); the keychain/GUI-modal theory (the shim's `security`
   probe runs at lines 1-3 of 219, fails over -X to -p, concludes unusable, falls back to its
   file store — no modal, no SecurityAgent, no hung child, and the run continues past it).
   ALSO NOTE the `[timer]` trace is NOT trustworthy for "timers stopped": loader.cjs traces
   setTimeout creation+fire but NOT clearTimeout and NOT interval ticks, so "N scheduled /
   M fired" says nothing about pending timers. The libuv handle dump (new: CLODE_SHIM_HANDLE_DUMP=1
   + SIGUSR2, commit ab4f783) shows ACTIVE timers and 3 active io watchers at the hang.
   NEXT: the shim's `http`/`https` modules have NO tracing, so any request not made through
   `globalThis.fetch` has been invisible (the `[fetch]` trace saw exactly ONE request all run:
   `/api/hello` -> 200). The bundle carries a full token-refresh path (`refresh_token` x32,
   `oauth/token` x9) that only engages when credentials exist. Add a `[http]` trace to the
   shim's http/https modules, re-fuse, and re-run row E — that names the request that never
   settles.
   **DONE, NEGATIVE (2026-07-31, cc2ac10):** with the `[http]` trace live on a re-fused ppc
   quaude, row E still hangs (>450s) and logs **ZERO `[http]` lines** — the bundle never calls
   `http.request`/`https.request` here. One `[fetch]` for the whole run (`/api/hello` -> 200).
   So the hang involves NO http request of any kind, and the (separately notable) discovery that
   `http.request` was never implemented in the shim is NOT this bug. Building that tracer
   required implementing a minimal fetch-backed `http.request` client (cc2ac10, 193 lines in
   http.cjs) — UNREVIEWED and UNRELATED to this bug; decide whether to keep, review, or revert.
   STILL UNEXPLAINED: with a creds file present the process waits, before any API request, with
   no socket, no child, no busy worker, and no http/fetch in flight; the handle dump shows 3
   active timers and 3 active io watchers (one pipe, two UDP resolver sockets). Candidate next
   probes: (a) instrument the fs/crypto surface the credential path touches; (b) check whether
   the two UDP watchers hold a REAL outstanding query at the hang (the bare engine resolves and
   rejects correctly under LIGHT load — that needs re-testing under the fused runtime's load);
   (c) diff row C's debug log (passes, no creds) against row E's (hangs, creds) line by line
   from `attribution header` onward — the first divergent bundle step names the code path.
   **(c) DONE — the divergence is named.** Row C (passes): `attribution header` -> Fast mode x2 ->
   `Remote settings: Retry 1/5 after 541ms` -> `dispatching to firstParty` -> `API REQUEST`.
   Row E (hangs): `attribution header` -> Fast mode x2 -> `Remote settings: Loading promise timed
   out, resolving anyway` -> `Git remote URL: null` -> `No git remote URL found` -> SILENCE. So on
   the credentialed path the remote-settings load TIMES OUT (its timer fires — "resolving anyway"),
   then git-remote detection runs, and its CALLER never continues.
   **HANG RE-VERIFIED ON AN IDLE BOX (2026-07-31):** >420s, apiReq=0, same last line, with `ps`
   confirming ZERO other quaude processes. This matters because the original matrix ran while
   ELEVEN stale quaude processes were alive on the 1-CPU VM (see the process-hygiene note below),
   which could have explained the hangs as starvation. It does not — the hang is real.
   **PROCESS HYGIENE (cost real credibility today):** `pkill -9 -f` silently does nothing on
   Darwin 8, AND naive `for p in $(ps|grep|awk); do kill -9 $p; done` loops were ALSO failing
   silently — 11 orphans from six separate test rounds were still running hours later. ALWAYS
   re-check the survivor count after killing, and treat any timing measurement taken without that
   check as suspect.
   Original diagnosis below (still the WHY):

   **(root cause, unchanged)** The PPC
   quaude boots + authenticates + full startup + (bare) HTTPS/TLS, but an agentic turn deadlocks: **Darwin 8
   kqueue drops socket/pipe/SIGCHLD/async event delivery under the fused runtime's fd load** (ktrace-confirmed).
   Fix = a poll()/select() event-loop backend for old Darwin (NOT per-mechanism `osx_select` patches — see
   the kqueue-usage audit) = the same paleo-POSIX backend roadmapped for cosmo/retro. Needs a PPC engine
   rebuild to test. The VM's DNS was separately broken and is now FIXED. Full detail + audit in memory
   `tiger-ppc-agentic-turn-deadlock`. (Task 3's double-Ctrl-C wedge is a SEPARATE, already-TRIAGED
   node-faithful non-bug.)

3. **Windows fidelity differential (Task 1) — user-gated on an SSH-able Windows box.** Windows `.exe`
   asset naming already FIXED (`f061843`). Remaining: build both targets on Windows, run the
   mock-anthropic differential, triage divergences (shim gaps vs deliberate).

4. **Release-atomic naming ship (Task 4) — PARTIAL.** Done: Windows `.exe` + cosmo `.com` asset names
   (`f061843`, `3898be0`). Pending: CI bash-mirror of `canonical-name.cjs` + tripwire + the no-`v` pin in
   an atomic release commit. See memory `canonical-artifact-names`.

5. **Release cut (Task 5) — endgame, user-driven.** Bump surface = `VERSION` + `package.json` +
   `package-lock.json` ×2 ONLY (date versioning, `date-versioning-next-release`); notes from `CHANGELOG.md`
   via `--notes-file`; watch the full matrix (all tjs legs + win SEA + darwin universal + the cosmo `.com`)
   green. RESOLVED and off the list: NetBSD/arm64 fullscreen crash (doesn't repro on main); Tiger
   double-Ctrl-C wedge (node-faithful).

## Cosmo APE fidelity gaps — posix-poll fd-event delivery (2026-07-29)

Full fidelity run of a FRESH cosmo quaude (fused from the committed Phase-E leg) on the dev host
surfaced two real cosmo-only divergences (native tjs passes both). Cosmo's args-driven/`-p` agentic
path is SOLID (8/9 offline agentic rows pass; real-creds `-p` returns a live "PONG"; TLS/spawn/fs/render
all fine) — the gaps are input/socket-event-delivery:

1. **TTY (interactive) stdin reads never fire — ROOT-CAUSED + FIXED (2026-07-29).** ✅ Cosmo quaude
   is now interactively driveable on macOS (trust prompt advances to the main prompt; `ttyread3.js`
   RED→GREEN: keystroke read len=1 b0=65; end-to-end fused quaude.com verified). **REAL fix (tiny):**
   in `deps/libuv/src/unix/tty.c` `uv_tty_init`, SKIP the tty reopen under `__COSMOPOLITAN__` — force
   `r = -1` so libuv's existing "reopen failed → use the original fd" fallback kicks in. Why: cosmo's
   `ttyname_r(0)` returns the generic `/dev/tty` alias, and reopening it yields a fd that `poll()`
   immediately POLLNVALs (busy-spin, 1.8M polls, keystrokes never delivered). The ORIGINAL tty fd
   `poll()`s correctly in raw mode (proven by a standalone cosmo C test: `poll` on raw fd0 → POLLIN;
   `select` does NOT work, so osx_select was the WRONG approach and is abandoned). After the fix,
   strace shows ttyname_r=0, POLLNVAL=0, and the keystroke reads. **The multi-hour red herring:**
   cosmoar's incremental archive NEVER replaced `tty.c.o` inside `libuv.a` — every rebuild compiled a
   fresh object but LINKED the stale archive, so runtime always ran old code (nm on the object said
   "fixed", disasm of the final elf said "still reopens"). FIX FOR THE BUILD LOOP: force-clean
   `deps/libuv/libuv.a` (+ `.aarch64/libuv.a`) before `gmake tjs-cli`, or do a clean build — never
   trust the incremental archive under cosmocc. PRODUCTIZED ✅: reopen-skip landed in
   `patches/libuv-cosmo.patch` (commit b4f7b41, applies clean to pristine); a from-scratch `build-tjs`
   cosmo run (pristine vendor reset → committed patch, NO osx_select cruft) built a working engine and
   the clean engine passes the TTY read (`TTY-READ len=1`, strace ttyname_r=0/POLLNVAL=0). INTERACTIVE FIDELITY VERIFIED ✅
   (2026-07-29, manual PTY differential): F6 render (welcome box + prompt paint clean, no corruption),
   D6 resize (reflows narrower, no stale frame), and **G2 live-creds turn (real API streamed "Paris"
   in the interactive TUI)** all PASS on cosmo — the rows that were blocked by this bug. Driven via the
   /bin/sh trampoline in tmux (the "human differential oracle") because the automated node-pty harness
   can't drive the cosmo APE: node `execve` returns ENOEXEC on the MZ APE (the shell only runs it via
   its ENOEXEC→/bin/sh fallback, and `assimilate -m` does NOT produce a real arm64 Mach-O — it warns and
   leaves an APE). AUTOMATED HARNESS NOW APE-AWARE ✅ (2026-07-29,
   72bdcc5): `test/e2e-pty.cjs` gained `apeCmd()` (detects MZ magic → wraps `/bin/sh -c '"$@"' sh <ape> …`);
   `capture()` applies it centrally and the `version()` checks in interactive-render/-resize/-live-turn use
   it. Cosmo APE subjects now gate automatically: **F6 render 2/2, D6 resize 2/2, G2 live-turn (real creds)
   2/2, I1 update-notify 3/3.** Non-APE subjects unchanged (native-tjs F6 still 2/2). RUN RECIPE: build-based
   rows want `CLODE_TJS=<cosmo APE engine>` (e.g. a from-`build-tjs` cosmo `tjs`) + `CLODE_LIVE_RENDER=1`
   (+`CLODE_LIVE_ONLINE=1` for G2); update-notify wants `CLODE_QUAUDE=<a fused cosmo quaude.com>`. F3
   stale-frames still skips — unrelated env precondition (needs a logged-in `/doctor`), not cosmo-specific.
   (Superseded osx_select notes below.)

   ~~TTY (interactive) stdin reads never fire — ROOT-CAUSED (macOS-host-specific).~~ The interactive
   TUI can't be driven (trust prompt won't advance on any key). Engine-level differential nails it:
   bare cosmo `tjs` reads a **PIPE** stdin fine (`READ len=6`, identical to native) but a **TTY**
   keystroke times out (`setRawMode` succeeds, `uv_read_start` on the tty never fires) — native reads
   it. Cause: libuv's macOS tty workaround `uv__stream_osx_select` (a per-tty `select()` thread feeding
   a socketpair the main loop can watch; `deps/libuv/src/unix/stream.c:145-405`, chosen at
   `tty.c:219`) is ALL `#if defined(__APPLE__)`. macOS's kqueue/poll can't reliably watch tty fds —
   that's WHY the workaround exists (there's even a CLODE Tiger fixup at stream.c:315 forcing select
   for ttys). **Cosmo doesn't define `__APPLE__`**, so it isn't compiled → cosmo reads ttys via generic
   `poll()`, which on a macOS host doesn't deliver tty read events. **macOS-HOST-SPECIFIC**: cosmo on
   Linux/BSD uses poll on ttys (works there), so cosmo interactive likely works off-mac. FIX = port the
   osx_select select()-thread path to `__COSMOPOLITAN__` (force it for ttys, skip the kqueue probe like
   the Tiger fixup). Multi-site `#if __APPLE__ → || __COSMOPOLITAN__` patch + cross-host care; feasible
   via fast incremental rebuild (cosmo build tree persists). RED test: the `ttyread3.js` engine-level
   tty differential (cosmo TIMEOUT vs native READ).
   ROOT CAUSE PROVEN (2026-07-29) via cosmo `--strace`: `ppoll({...,{9,POLLIN,[POLLNVAL]}},...)→1` on
   EVERY poll — **cosmo's poll()/ppoll() returns POLLNVAL for the macOS tty fd** (the classic macOS
   "ttys/char-devices aren't pollable via poll()" limitation — the exact reason libuv uses kqueue+select
   on Apple). So the poll-based io loop never sees the tty readable → keystrokes never delivered. strace
   also shows the tty reopen `openat("/dev/tty",O_RDWR|O_NOCTTY)→9 ENOTTY` and `socketpair`=0, so the
   osx_select select()-thread (the CORRECT fix — select() DOES work on macOS ttys) never engaged.
   TOOLING (reusable, KEY): cosmo APEs support `--strace` (syscalls+returns) and `--ftrace` (function
   calls), symbolized via the `tjs.com.dbg`/`tjs.*.elf` sidecars next to the engine. This is THE way to
   debug the cosmo APE — C `fprintf`/`write(2)`/`open()`-probes all produce NO output (tjs redirects fd2;
   probe writes vanish), so DON'T instrument with prints; use --strace/--ftrace. `__COSMOPOLITAN__` IS a
   predefined macro (`cosmocc -dM -E`), confirmed effective (a `#error` inside the tty.c cosmo `#if`
   fired). Fast incremental rebuild: rm the target .o + `gmake tjs-cli` in the persisted build tree.
   REMAINING FIX WORK: make the osx_select select()-thread actually ENGAGE for the cosmo tty —
   `uv__stream_try_select` isn't wiring up the socketpair/thread (fd 9 is polled directly, POLLNVAL).
   Likely the `/dev/tty` reopen→ENOTTY makes the reopened fd's `isatty` gate fail (my cosmo branch bails
   `if(!isatty(*fd)) return 0`), OR skip the reopen under cosmo. Also verify select() works on the fd
   that poll POLLNVALs (it should on macOS — that's osx_select's premise). WIP osx_select port
   (compiles, doesn't yet engage) lives in the scratchpad cosmo-vendor working copy; repo untouched.

   FIX ATTEMPT 1 (2026-07-29, INCONCLUSIVE — observability wall): ported the osx_select select()-thread
   path to `__COSMOPOLITAN__` (guards in stream.c/tty.c/internal.h + `select` field via
   `UV_STREAM_PRIVATE_PLATFORM_FIELDS` in cosmo.h + kqueue-probe bypass since cosmo's sys/event.h is a
   stub). COMPILES + links (fast incremental: edit `$SP/cosmo-vendor` libuv → `gmake tjs-cli` in
   `$SP/cosmo-out/build`, cosmocc on PATH). Read STILL times out, and I could NOT verify why: stdin is
   `type=tty`/`isTerminal=true`, yet NO C probe fires — not fprintf(stderr), not write(2), not even an
   absolute-path open()+write at a GUARANTEED-hit point (`uv_guess_handle`). JS console.error + tjs
   writeFileSync reach disk; ALL C-level output vanishes on the stripped mac cosmo APE. So EITHER tjs's
   stdin bypasses `uv_tty_init` (osx_select port = wrong layer) OR C observability is broken on the mac
   APE. NEXT: use real tooling (lldb on a debug-symbol cosmo build, or a NON-APE mac cosmo-libuv build) —
   blind file-probes don't work here; a Linux cosmo build won't reproduce (mac-host-only bug). Repo is
   UNTOUCHED (all WIP in the ephemeral scratchpad working copy).
2. **MCP-over-WebSocket client never connects — FIXED (2026-07-30).** ✅ Cosmo `new WebSocket()` now
   connects (WS-OPEN against a local node ws echo server). ROOT CAUSE: libwebsockets' bundled
   `lib/misc/sha-1.c` gates byte-swapping on `BYTE_ORDER`/`LITTLE_ENDIAN`/`BIG_ENDIAN`; cosmo defines
   those as aliases to `__BYTE_ORDER`/`__LITTLE_ENDIAN`/`__BIG_ENDIAN` which it never defines → in `#if`
   arithmetic all read 0, so BOTH `==LITTLE_ENDIAN` and `==BIG_ENDIAN` are true (0==0) → sha-1.c compiles
   an inconsistent LE+BE byte mix → every lws SHA-1 is wrong → the ws client's `Sec-WebSocket-Accept`
   (=`base64(SHA1(key+GUID))`) check fails on every valid 101 (`HS: Accept hash wrong`). HTTPS was fine
   because TLS uses mbedtls SHA, not lws's builtin. FIX: **patches/libwebsockets-cosmo.patch** (new;
   applied `git -C deps/libwebsockets apply` in build-tjs.cjs `applyCosmoPatches`) re-derives the macros
   from the compiler's `__BYTE_ORDER__`/`__ORDER_*_ENDIAN__` builtins, gated on `__COSMOPOLITAN__`
   (behavior-neutral for other legs). Verified: applies clean to pristine lws; scratch rebuild → accept
   hashes match → WS-OPEN. FOLLOW-UP: a full clean `build-tjs.cjs --target cosmo` end-to-end + the
   `agentic-mcp-ws.test.cjs` row green on a fresh cosmo quaude (high-confidence; the productized patch is
   byte-identical to the verified scratch edit).

Cosmo's args-driven/`-p` agentic path is SOLID (8/9 offline rows; real-creds `-p` returns live PONG;
TLS/spawn/fs/render fine) — these gaps bound cosmo to non-interactive/agentic on macOS. Additive
soft-fail leg, so NOT a leg blocker. See memory `cosmo-libc-additive-leg`.

**FULL AGENTIC FIDELITY SUITE GREEN ON COSMO (2026-07-30).** With both fixes (tty + ws) on a clean
rebuilt engine, the entire `node --test` agentic fidelity suite passes on the cosmo APE at parity with
native tjs: agentic-mcp-ws (connect+handshake+tool-call over ws), agentic-tools 5/5 (Write/Grep/
multi-turn/--continue/PreToolUse-hook), node-shim-agentic 2/2 (Bash inline stdout, Edit/FileHandle.chmod),
agentic-workflow-complete 1/1, agentic-subagent-diff 1/1 (Task dispatch identical node-vs-cosmo-quaude).
The harness is now APE-aware end-to-end (node-shim-helper `engineSpawn`/`isApeFile`), so `CLODE_TJS=<cosmo
.com> node --test test/fidelity/agentic-*.test.cjs test/node-shim-agentic.test.cjs` is the standing gate.
No cosmo-specific divergences remain on the agentic surface.

## TRIAGED — Tiger/PPC double-Ctrl-C "wedge" is FAITHFUL, not a bug (2026-07-29)

Filed here so it is NOT re-chased. On slow-DNS boxes (Tiger/PPC VM), the TUI's double-Ctrl-C
appears to hang but actually exits cleanly (RC=0) after a ~65s teardown. Cause: `tjs.exit`→
`mod_os.c:38 exit()`→ C atexit → libuv `uv__threadpool_cleanup`→`pthread_join` blocks on a pending
`getaddrinfo` worker whose DNS lookup takes ~65s on that box. **Plain Node hangs identically** in a
dev-host differential (dispatch a blocking libuv threadpool op, then `process.exit` → both Node and
quaude wait for the join) — so it's libuv-inherent, shared with real Claude Code. The pending lookup
is bundle-driven (api.anthropic.com warmup + status.claude.com + Datadog, captured from naude). A
`_exit()` speedup was REJECTED (would diverge from Node; violates the fidelity doctrine). Mitigation
for slow-network boxes: `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` (drops the status/telemetry
resolves; api.anthropic.com stays). Maintainer decision (2026-07-29): accept faithful + document;
removed from release blockers. Full method + repro in memory `tiger-ctrlc-teardown-threadpool-join`.

## Arch / artifact-name rationalization — release-atomic remainder (2026-07-27)

The canonical-name refactor SHIPPED (single `scripts/canonical-name.cjs` source of truth;
download name == `--list-targets` tag == fetched engine; pin drops the `v`; the build-leg
bash asset name now comes from the canonical-name CLI). What's LEFT is release-coupled:
- **Shipping the pin-format change is release-atomic** — an old clode's baked pin
  (`v26.6.0-…`) vs a new manifest (`26.6.0-…`) mismatches → obtainEngine refuses. Land it
  WITH a release, not before. See the at-desk release-readiness plan (Task 4).
- CI **engine-upload names** must be the canonical `tjs-<os>-<arch>-<pin>` a fetching clode
  expects (verify on the release pass).
- Optional leg-token rename (plan path B) — internal-token uniformity, bigger blast radius;
  follow-up only.

## Spec sweep 2026-08-01 — the threads that had a spec but no backlog entry

Swept `docs/superpowers/` from 145 files to 16 by verifying each cluster against the
tree (windows/SEA/bats/hermetic/universal-binaries/phases and ~25 single workstreams all
shipped; deleted). The survivors are genuinely unfinished. These had NO backlog entry at
all, which is how they went quiet — recorded here so the remaining specs are the only
place work hides, not the last place anyone looks:

- **Target-matched assembly — PAUSED BY DECISION, not forgotten.** `providerFor` by-OS
  shipped; template-by-arch fixed (21127a5). Held per the 2026-07-19 call that cross-build
  waits on trusted daily-drive fidelity plus a durable naude-vs-quaude gate. Un-pause
  condition is the fidelity tier ledger above, so these two are coupled.
  Spec: `2026-07-19-target-matched-assembly-design.md`.
- **Universal cross-build Layer 1 — engine production, deferred half.** Layer 2 (clode
  cross-fuses from prebuilt engines) shipped and now range-fetches its slice. Layer 1 —
  one clang/zig + pinned sysroots replacing the per-target toolchain zoo, plus the target
  descriptor and `build-tjs.cjs --target Y` — is untouched. Depends on build-working-dir
  isolation (already tracked above).
  Spec: `2026-07-25-universal-cross-build-compiler-free-quaude-design.md`.
- **Feature parity #2 image (sharp/libvips) and #3 TypeScript (Bun.Transpiler).** Both
  DRAFT since 2026-07-15, both unimplemented, both sequenced after the runtime-retirement
  decision in the user's original order (SQLite ✓ → image → TypeScript → MCP computer-use).
  Neither is reachable from any current test, so quaude silently lacks them.
  Plans: `2026-07-15-image-sharp-spec.md`, `2026-07-15-typescript-transpiler-spec.md`.
- **Comparative performance fixtures.** A hermetic benchmark harness running the SAME
  bundle under quaude/naude/claude against fixtures, so QuickJS interpreter-tax shows up
  as wall-clock/RSS ratios instead of guesses. Directly serves the Tiger perf work
  ([[tiger-ppc-quaude-perf]]: sys-time is the tractable lever, and we are guessing today).
  Plan: `2026-07-24-comparative-performance-fixtures.md`.

Three more were closed out on 2026-08-02 by checking the tree rather than the spec, and
their plans deleted — recorded here so nobody re-derives them:

- **Retire the host-Node runtime (tjs-primary) — ACHIEVED.** clode ships as tjs binaries
  for 22 OSes and carries no Node ever; the pinned Node is fetched on demand only for a
  naude. Proven and CI-gated by `test/clode-native.test.cjs` "acceptance 4: the native
  builder BUILDS A NAUDE (fetch node + assemble + PONG), node absent from PATH". The
  older "clode-native builds quaude only / `--naude` refuses" note was stale.
- **quaude daily-driver hardening — ABSORBED into RECIPE.** BUG1 (0-byte `~/.claude.json`)
  is row A1, a `→` row citing a live test; BUG4 (in-TUI update unhooked) shipped as
  notify-only; BUG2 and BUG3 are the open probes E4 (`detached` / login opener) and F3
  (stale frames). Nothing was lost by deleting the plan.
- **At-desk release readiness — SPENT.** Tasks 4/4b/5 shipped (canonical naming, the cosmo
  leg, two releases). Task 3 was TRIAGED as node-faithful. Task 2 (NetBSD/arm64 fullscreen)
  is recorded above as not reproducing on main. Task 1 (Windows fidelity differential) is
  the only live remainder and already sits in the IN-FLIGHT HANDOFF.

## Engine-recipe identity — the two deferred halves (2026-08-22)

`scripts/engine-recipe.mjs` (the sha256 of the engine-source set) and
`scripts/templates-drift.mjs` (published-templates-vs-this-tree, its own ci.yml job)
shipped. Two deliberate follow-ups, in this order:

- **Stamp `recipe` into the published manifest — OPEN, and the cheap one.** Today
  `templates-drift.mjs` derives the PUBLISHED recipe by computing it at the release
  TAG (`git show <tag>:<path>`). That is sound — the engines in a release were built
  from that tag's tree by definition — but it is inference, and it needs full history
  in the checkout. Have `scripts/build-templates-manifest.mjs` write
  `recipe: <sha256>` into the manifest; `templates-drift.mjs` ALREADY prefers that
  field when present (`derivedFrom: manifest.recipe`), so this is one line plus a
  test, and it turns an inference into an assertion. It also makes the answer
  available to a `clode` that has no git checkout at all.
- **A recipe marker inside the engine binary — OPEN, and it needs care.** The
  strongest version of this check is a `tjs` that can state the recipe it was built
  from, so `obtainEngine` could refuse a stale engine at fetch time instead of CI
  catching it a push later. The marker must be injected as a build-time `-D`
  (build-tjs.cjs → cmake), NOT written into a patch: the recipe hashes
  `spike/quickjs/patches/*.patch`, so a patch containing the recipe is a fixed-point
  problem. Note also that this would make the pin gate meaningfully strict for the
  first time — an old clode meeting a new pack must still fail *readably*, not
  cryptically.

Also unresolved: the ci.yml job is RED on main until the next release cut, by
design (14 engine-source commits sit between v0.20260801.2 and main, none of which
the tjsPin gate can see). It is actionable red with exactly one remedy — republish
the pack — but it IS ambient red while it lasts, which is the thing
[[silently-gated-tests-hide-p0s]] warns about. If it is still red weeks from now,
that is the signal to cut the release, not to soften the job.

## Release follow-ups 2 + 3 — the unbuilt half of the 2026-07-27 spec

Spec `docs/superpowers/specs/2026-07-27-release-followups-design.md` carries five
follow-ups. Audited 2026-08-01 against the tree, not against memory:

- **FU1 one canonical version source — DONE** (`test/version-single-source.test.cjs`
  asserts VERSION == package.json == package-lock ×2 + a matching CHANGELOG section).
- **FU4 naming consistency — DONE** (`scripts/canonical-name.cjs`, b63233b). Remainder
  is the release-atomic pin work in the section above.
- **FU5 one range-fetchable templates blob — DONE** (6bd9088). Two assets
  (`templates-<pin>` + `.json`), Range-fetch a slice or `CLODE_TEMPLATES_BLOB` for
  fully-offline cross-build. Verified 206 through the real GitHub→CDN redirect.
- **FU2 fold the darwin legs into the one matrix — OPEN.** `release.yml` still runs
  `leg (only: notdarwin)` + `darwin-slices (only: darwin)`. The spec's keep/remove split
  stands: KEEP the universal `lipo`, Mach-O ad-hoc signing, and osxcross (real Apple
  constraints); REMOVE the `only:` bifurcation and the bespoke `pack: true` flag. Cousin
  to the `ciOnly` release-vs-ci discrepancy that already bit us.
- **FU3 gate BE correctness on the real netbsd-sparc guest — OPEN.** `be-oracle` is
  still `continue-on-error` against s390x under qemu-**user**, excluding five I/O test
  files, while `netbsd-sparc` already boots a REAL full-system guest and only runs a
  PONG smoke. Blocker named in the spec: the oracle diffs tjs against LIVE host node,
  which qemu-user permits in-process and a full-system guest does not — so it needs a
  goldenized oracle (record expectations from host node, replay in the guest) before the
  gate can move. Doing this retires a known-flaky non-gating signal, which is squarely
  [[ci-job-is-to-tell-the-truth]].

## tjs must be BUILT + REQUIRED by the suite, not skipped (2026-07-25)

On netbsd11-arm64, 200 of 240 suite skips are "no tjs binary (CLODE_TJS or
build/tjs/…)". tjs builds on EVERY target platform (the whole cross-build matrix
— a solved problem), so skipping on its absence is the same silent-coverage-loss
anti-pattern as the old node-pty skip (now fixed: node-pty is built + required,
7d1763f). The suite should ensure tjs is built (like the PTY harness) and tests
should REQUIRE it, converting ~200 skips into runs. Wire a build-or-require step into
test/run.mjs (mirror the node-pty harness path) and drop skipUnlessTjs's silent-skip in
favor of a loud requirement. User framing (2026-07-25): "Isn't tjs known to build on every
platform we target?" — yes; don't skip on a buildable artifact's absence. (Unblocked now
that the build-dir isolation lands.)

## NetBSD 64-bit time_t: write-side utimes truncation in the pkgsrc host node (2026-07-25)

`fs.utimesSync(f, new Date('2076-...'))` under the pkgsrc host node writes a mtime
of 1940 — a signed-32-bit time_t wrap (2076 ≈ 2^32 s). Disambiguated: the OS `stat`
(and `ls`) read back the SAME 1940, so libuv WROTE the truncated value; the kernel
stored it faithfully (not a read bug). NetBSD/arm64 has had 64-bit time_t forever;
this is the NetBSD symbol-versioning trap — 64-bit time is exposed via renamed libc
symbols (`__utimes50`/`__stat50`/…), and a binary built without the correct NetBSD libc
headers links the OLD 32-bit `utimes`. So the pkgsrc node 24 (or its bundled libuv) was
compiled to call 32-bit `utimes`, not `__utimes50` — an upstream pkgsrc/node BUILD defect,
not clode code. THE ONE WE OWN: clode's tjs build vendors libuv (spike/quickjs/vendor/
txiki.js/deps/libuv); it MUST compile with NetBSD 64-bit-time_t symbols or quaude will
truncate timestamps the same way. Verify (and patch the tjs build if needed) once the
native tjs build is unblocked. Report the pkgsrc node build bug upstream.

## Native tjs on NetBSD needs CLODE_TJS_WASM=off (WAMR uses Linux mremap) (2026-07-25)

Building native tjs on netbsd11-arm64 fails in WAMR: `deps/wamr/core/shared/platform/
common/posix/posix_memmap.c` uses Linux-only `mremap(..., MREMAP_MAYMOVE)` (NetBSD has
no such mremap). Same class as the documented MAP_32BIT breakage on s390x/ppc64le/
riscv64. STOPGAP for green: build with `CLODE_TJS_WASM=off` (build-tjs.cjs supports it —
drops WASM/WAMR; "nothing shipped imports it", bun:ffi is a throw-on-use stub). TODO: decide
whether NetBSD (and other non-Linux BSDs) should ship WASM at all; if yes, patch WAMR's
posix_memmap.c with a non-Linux mremap fallback (munmap+mmap or guard the MREMAP path) and
upstream it. For now WASM-off is the shipping posture on platforms where WAMR won't build —
record it in the per-target build config, not as an ad-hoc env flag a human must remember.

## canonical-LE: the regexp wall is REAL, MEASURED, and BENIGN — now gated (2026-08-23)

**The question ("can we compare bytecode from LE and BE being identical or not?") is
answerable, the tool already exists, it is wired into NOTHING, and when run it FAILS.**

`spike/quickjs/bc-le-oracle.mjs` serializes a fixed corpus under a given tjs and prints
one sha256 per item. Its own header states the contract: *"On BE hosts the hashes are
EXPECTED to equal the LE baseline after the patch — that is the point."* Nothing in
`.github/` or `scripts/` ever invokes it.

### Measurement

Both engines from the SAME release run (30730368429, v0.20260801.2) so build date and
patch stack are identical. BE run under `qemu-s390x-static` 7.2.22 in a
`node:24-bookworm` container on ultimate-hat's docker.

| corpus item | length | LE x86-64 | LE darwin-arm64 | BE s390x |
|---|---|---|---|---|
| `libexec/node-shim/loader.cjs` | 26467 | `d6a7026f…` | `d6a7026f…` | **`2295d1a0…`** |
| `build/bundle/clode-main.bundle.cjs` | 119816 | `3c538d33…` | `3c538d33…` | **`ae428b69…`** |
| `stress(inline)` | 524 | `a37cca5a…` | `a37cca5a…` | `a37cca5a…` ✓ |

Controls, all clean: source bytes byte-identical on both sides; LE deterministic across
runs; BE deterministic across runs; two different LE architectures and two different
build dates agree EXACTLY, which rules out an engine-version confound.

Byte-level: `stress` has zero differing bytes. The two real files first differ at
**offset 1** — a 4-byte value (`b3da1d09` vs `2d7abcfc`; NOT a byte-swap of each other,
so a value computed differently rather than merely stored differently) — then re-sync,
with 2826/26467 (10.7%) and 2034/119816 (1.7%) bytes differing overall.

So canonical-LE holds for the synthetic stress corpus (wide strings, doubles, bigints,
atoms, branchy labels) and FAILS on real CommonJS files. Whatever differs is present in
those and absent from the stress source.

### RESOLVED: it is regexp literals, and the read path is fine

Probed construct by construct on both engines. Ints, doubles, wide strings, typed
arrays and functions-with-control-flow are all BYTE-IDENTICAL LE vs BE. Only a regexp
literal diverges. That is the wall already recorded in [[canonical-le-bytecode]] as
"regexp-literal wall (OP_regexp recompile)" — libregexp's compiled program is stored in
host order.

And the direction that matters is FINE, measured end to end: a regexp compiled and
serialized on LE, then deserialized and EXECUTED on the BE engine, matches correctly
(`REGEX-OK`, with the LE run as control). The header divergence at offset 1 is just
`bc_put_u32(s, 0) // checksum` (quickjs.c:38521) reflecting the differing payload — an
effect, not a cause.

**So my first framing of this entry was too strong.** "canonical-LE is INCOMPLETE" reads
as a defect; the accurate statement is that regexp bytecode is emitted in host order and
re-derived on load, which is a known and benign asymmetry. The 2826 differing bytes in
loader.cjs are regexp programs (note the 35 runs of exactly 42 bytes, and that 709 of 770
runs are non-ASCII).

### What this does and does not mean

**It is the WRITE side.** Our pipeline serializes bytecode on the BUILD host (LE in
practice) and the target engine READS it. A BE engine reading LE bytecode is the
property quaude actually depends on today, and this measurement does not test it — the
s390x leg's level-2 self-load does, and passes.

It matters for: a quaude BUILT ON a BE host (the level-2.5 path, currently
"NOT achieved" under qemu-user), reproducibility of artifacts across build hosts, and
the plain truth of the canonical-LE claim — which is load-bearing in
[[canonical-le-bytecode]] and was the justification for the sparc/s390x work.

### Why this is the BE gate we should have

`be-oracle` replays shim tests on a BE engine, has never caught a big-endian bug in 30
runs, and its one endianness assertion is `assert.ok(x === 'LE' || x === 'BE')`. THIS
compares the actual artifact for the actual property, in ~10 seconds, with no provider,
no exclude list, and no libc mismatch. Wiring `bc-le-oracle.mjs` into the s390x leg —
LE baseline committed, BE run in-leg, diff — would be a real gate. It is currently red,
which is the strongest argument for having it.

### Reproduce

    gh run download 30730368429 -n tjs-linux-s390x-musl -D be
    gh run download 30730368429 -n tjs-linux-x64-musl   -D le
    # ship repo skeleton (spike/quickjs/bc-le-oracle.mjs + corpus files) + both engines
    ssh ultimate-hat 'zsh -lc "docker ..."'   # see [[ultimate-hat-build-host]]
    apt-get install -y qemu-user-static
    node spike/quickjs/bc-le-oracle.mjs ./tjs-le     # baseline
    node spike/quickjs/bc-le-oracle.mjs ./tjs-be     # wrapper: qemu-s390x-static ./tjs-s390x "$@"

Next step is to narrow WHICH field diverges — dump hex both sides (a `BC_DUMP` variant
of the oracle) and walk the quickjs writer from offset 1.

## /heapdump is broken on BOTH targets — and the API-surface gate cannot see it (2026-08-23)

Found by INSTRUMENTING and driving real flows, not by reading the bundle — the
method this repo's doctrine demands, and it earned its keep: ten flows driven
(`--version`, `-p`, an agentic Bash turn, a six-tool Bash→Grep→Glob→Read→Edit→Write
chain, TUI boot under a real PTY, a slash command with YAML frontmatter,
`--output-format stream-json`, `/heapdump`), under both the naude and quaude models.

`/heapdump` is a shipped, non-hidden slash command (`supportsNonInteractive:!0`).
It fails on both targets, and WORSE on ours:

- **naude (node):** `Failed to create heap dump: The "data" argument must be of type
  string or an instance of Buffer... Received an instance of HeapSnapshotStream`.
  The bundle does `writeFileSync(e, Bun.generateHeapSnapshot("v8","arraybuffer"), …)`;
  `libexec/bun-shim.cjs:942` returns `v8.getHeapSnapshot()`, a Readable, not an
  ArrayBuffer.
- **quaude (tjs):** fails EARLIER and NAMELESSLY — `Failed to create heap dump: not a
  function` — never reaching `Bun.generateHeapSnapshot` at all. Probed directly: under
  the shim, `v8` exports only `getHeapSnapshot`; `v8.getHeapStatistics` and
  `getHeapSpaceStatistics` are undefined, as are `process.resourceUsage`,
  `process._getActiveHandles` and `_getActiveRequests`. `captureMemoryDiagnostics`
  calls `getHeapStatistics()` on its second line. (Nameless quickjs TypeErrors are a
  known trap — see [[shim-filehandle-chmod-gap]].)

**Why no gate caught it.** `test/node-shim-api-surface-gate.test.cjs` asks whether the
Bun surface is PRESENT. `Bun.generateHeapSnapshot` is present, so the gate calls it
implemented and always will. The defect is in the node APIs underneath, which is the
BEHAVIOURAL axis — `scripts/apicheck.mjs` territory ([[clode-api-surface-gate]]), not
this gate's. Presence gates cannot see wrong answers; that is the whole reason the
behavioural axis exists, and this is a concrete row for it.

**Adjacent findings from the same investigation, not yet acted on:**

1. **`bun:*` interception is require-only.** `libexec/bun-shim.cjs` hooks `Module._load`,
   so nothing it declares in `PROVIDES` survives an `import()`. Measured:
   `require('bun:ffi')` OK / `import('bun:ffi')` REJECTED
   (`ERR_UNSUPPORTED_ESM_URL_SCHEME`), same for `bun:sqlite`. Costs nothing today; one
   upstream `require("bun:ffi")` → `await import("bun:ffi")` and interception silently
   stops working.
2. **`bun:sqlite` is stale in `PROVIDES`** — it no longer appears in 2.1.241 at all.
3. **The gate measures the shim in the WRONG ENVIRONMENT.** `probeShim`
   (`inspect-claude-bundle.cjs:350ff`) spawns `node -e` and calls `require.resolve`
   with no `NODE_PATH` at `deps/claude/node_modules`, so it reports the world as if the
   ext-dep closure did not exist. Consequence: it lists `Bun.semver`, `stringWidth`,
   `stripANSI`, `wrapAnsi` and `YAML` as "stubbed — throws when used" when driving
   proves all five are REACHED AND WORKING on every flow, and lists `ws`/`node-fetch`
   under "MISSING → SILENT TUI HANG risk" when both are in `deps/claude/package.json`.
   A gate that overstates risk on exactly the surfaces that matter trains people to
   discount it.

**Worth banking from the same run:** `Bun.isStandaloneExecutable: false` is
load-bearing, not a cosmetic honesty fix. The bundle gates its `argv0`-based
`Bun.spawn` ripgrep probe on it; because our shim answers false, quaude and naude take
the `child_process` path instead. Anyone "fixing" it to `true` would silently reroute
rg through a Bun API we do not implement.

## Untracked-until-now findings from 2026-08-23/24 (three of them)

These lived only in commit messages. Git preserves that; nobody browses it when
deciding what to do next, which is how they went missing from planning. Recorded
here so the next session can see them.

### 1. `net.createServer` is ABSENT — UDS peer messaging is silently off under quaude

Every quaude startup logs `[ERROR] [uds-messaging] Failed to create server: TypeError:
not a function`. That is `net.createServer`: `libexec/node-shim/modules/net.cjs` exports
`isIP, isIPv4, isIPv6, BlockList, Socket, Server, Stream, connect, createConnection` —
no `createServer`. Reproduced under the local engine; byte-identical message. Nameless
TypeError = an ABSENT function, the signature this repo keeps paying for
([[shim-filehandle-chmod-gap]]).

Bundle side (2.1.241): `o = Aos.createServer({allowHalfOpen:!0}, a => {…})`, caught and
logged, then it bails. Full chain a real implementation needs, in order:
`createServer({allowHalfOpen}, listener)` → `server.on('error')` →
`server.listen(<unix socket path>, cb)` → `server.unref()` → per-connection `Socket`
with `.on('close')` → `fs.promises.chmod(sockPath, 0o600)`.

**Do NOT "fix" it with a walled stub.** `net.createServer` is already tracked in
`test/shim-surface/golden.json`, and `layer2Gaps` decides by `prop in shim.surface`
(collect.cjs:88) — so a wall would silently DELETE a tracked gap. That is exactly what
the v8 walls did on 2026-08-23 before being reverted. Either implement it, or land the
wall-aware inventory first (see the /heapdump entry).

### 2. Does MCP-over-SSE actually work on Windows? STILL UNKNOWN

Not to be confused with the 2026-08-06 `/[object Object]` SSE entry, which is fixed. The
Windows legs failed at the SSE probe, and d8a4f75 established that was NOT SSE: the
quaude never launched (0.2s elapsed vs the 45s timeout on legs that really run it;
extensionless `--out` + host node, which lacks
`UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME`). So that run produced ZERO information about
the transport. With the launch fixed, expect the probe to take ~45s on Windows and say
something genuinely new — possibly another failure. **Nobody has ever seen MCP work or
fail on Windows.**

### 3. One unexplained test flake

`spawn: numeric fd in stdio redirects child output to a file (Bash-tool pattern)` failed
once in a full suite run, then passed in 2 further full runs and 6 isolated runs of that
file; a clean tree gave 0 in 2 full runs. Two clean runs is too small a sample to call it
pre-existing, and the changes in flight touched templates/fuse/build — nothing
child_process uses. Recorded as SEEN AND UNATTRIBUTED rather than dismissed. If it
recurs, it is load-sensitive (full suite only), which points at the harness rather than
the assertion.

## RESOLVED 2026-08-27 — haiku-x64 ships again, via a different provider

**The blocker is gone, and it was never about this leg being flaky.** HaikuPorts deleted
the r1beta5 ports tree while cross-platform-actions shipped only a beta5 image, so no
image-plus-repo combination could work. vmactions/haiku-vm v1.1.5 (2026-08-27) added
r1beta6 and dropped r1beta5 — the first moment both exist. The leg moved backends, kept
its package list unchanged (`cmd:` is pkgman provides-syntax; beta6 has all of them:
gcc 13.3, make 4.4, cmake 4.1, git 2.54, bash 5.3, nodejs20 20.15), and went back to
`publish: true` with `ci: true` and NO soft-fail.

**The watcher is RETIRED (2026-08-31), which is the better answer than the "teach it both
providers" this entry used to propose.** scripts/haiku-image-watch.mjs compared the cpa
catalog against a hardcoded `/r1beta5/i`, so once the leg was pinned to r1beta6 it reported
our OWN adopted image as news and failed upstream-drift every day from 08-28 to 08-31 — a
to-do trigger whose to-do was done, telling us in its failure text to "restore publish:true"
on a leg that already published. Measured on 2026-08-31: cpa haiku-builder v0.2.0 now ships
BOTH `haiku-r1beta5-x86-64.qcow2` and `haiku-r1beta6-x86-64.qcow2`, and vmactions/haiku-vm
lists r1beta5.conf + r1beta6.conf — so both providers agree, and the narrow-provider blind
spot this entry described is moot. scripts/check-guest-versions.mjs already asks the same
question of the same catalog for EVERY VM leg (haiku included — `isVmLeg`, now exported and
asserted in test/check-guest-versions.test.cjs), comparing against the PIN rather than a
literal, which is why it was green on the day the bespoke one was red. One watcher, derived,
not two, one of them hand-maintained.

**Fidelity is 0/6, honestly.** The demotion withdrew haiku's RESULTS.md rows and nothing has
re-driven them on the new backend. The golden ledger says 0, which means "shipping, not yet
measured" rather than a claim we have not earned.

## (historical) haiku-x64 — the GUEST IMAGE is a superseded release; upstream is tracking it (2026-08-24)

**CORRECTED 2026-08-24.** An earlier version of this entry said "HaikuPorts deleted
the r1beta5 repo… deliberate, they cannot staff two releases' ports". That framing was
wrong and was passed along without checking. What is actually observable:

| probed URL | result |
|---|---|
| `haikuports/r1beta5/` | `[]` — an EMPTY directory, not a missing one |
| `haikuports/r1beta6/…/repo` | 200, 2,441,965 bytes |
| `haikuports/master/…/repo` | 200, 2,441,965 bytes |
| `haiku/r1beta5/…/repo` (base OS) | 200, alive |

`r1beta6` and `master` both redirect to the SAME CDN object
(`haikuports-repository.cdn.haiku-os.org/master/…`). So this is the ordinary
lifecycle of a live project: **ports follow the current release**. beta6 shipped, its
ports are master's, and the superseded beta5 ports directory was emptied. The base OS
repo for beta5 is still healthy — which is exactly why only "HaikuPorts" fails in our
logs and the `haiku` repo does not.

METHOD NOTE, because it is the reusable part: my first probe returned 0 bytes for BOTH
beta5 and master, which should have said "my URL is wrong", not "beta5 is empty". Follow
redirects (`curl -sL`) — the real content is on a CDN.

**The problem is OURS, not upstream's: our guest image is a superseded release.**
`cross-platform-actions/haiku-builder` has published exactly one asset in every release
to date — `haiku-r1beta5-x86-64.qcow2` (v0.0.1 2025-05-19, v0.0.2 2025-12-12, v0.1.0
2026-04-29).

**Upstream IS tracking the need. Do not file a duplicate:**
- **haiku-builder#2** (open) — "Haiku seems releasing the R1 Beta 6, package manager is
  nuked on R1 Beta 5". Another user hit exactly our failure. Their workaround:
  *"I manually updated repos with the `r1beta6` tag, and I successfully updated my local
  OS to the R1 Beta 6 hrev59866+60."*
- **haiku-builder#3** (open, updated 2026-08-16) — "Add support for Haiku R1/beta6",
  proposing a beta6 image built from the official test build `hrev59866_53`.

**DEMOTED 2026-08-24 (temporary) so the release can go out.** `publish: false` — the
doctrine-sanctioned demotion, not a softened gate. It was a HARD gate blocking the
release that fixes the ★★ cross-fuse DOA. The leg still BUILDS, so we keep the signal;
it just ships no artifact. `test/tjs-legs.test.cjs` now derives the demoted set from the
legs themselves, so re-promoting needs no test edit.

**RESTORE IT when either becomes true** — this is the follow-up work, not a closed item:
- cross-platform-actions publishes a beta6 guest image (**haiku-builder#3**, open), or
- master/beta6 ports install on the beta5 guest.

**Exactly where the last attempt got to**, so nobody restarts from zero. Three walls,
each found by one CI run:
1. `pkgman add-repo -y …` → `Usage: pkgman add-repo <repo-URL>` — there is no `-y`.
2. Without `-y`, add-repo is **INTERACTIVE**: it printed `overwrite? [yes/no] (no) :`
   twenty-one times and defaulted to no, because there is no TTY.
3. So the next attempt must remove the stale entry first (`pkgman drop-repo HaikuPorts`)
   or feed it confirmation, and only then `add-repo` the master URL. Whether the
   packages then RESOLVE against a beta5 system is still the open question —
   haiku-builder#2 suggests yes, but that user also upgraded their OS to beta6.

**Where we are.** `.github/actions/guest/action.yml` now points pkgman at the master
ports repo before installing (81dd641; the `-y` typo that made the first attempt a
no-op is fixed). Whether master/beta6 packages RESOLVE against a beta5 system is the
open question — #2 suggests they do, but that user also upgraded the OS. If they do not,
the honest options are (a) `pkgman full-sync` the guest to beta6 in-leg, which is what #2
effectively did, or (b) demote the leg.

**If it must be demoted: drop `publish`, never soften the gate.** `'soft-fail': true` on
this leg is INERT — both tiers delete soft-fail from publishers ("if we publish it, CI
gates it": scripts/tjs-legs.mjs:860 and :889) — so haiku-x64 is a HARD gate that reddens
main AND blocks releases. Dropping `publish` restores soft-fail and needs matching edits
to the golden lists in `test/tjs-legs.test.cjs` and `test/asset-name-parity.test.cjs`.
Explicitly NOT a retry: 14 consecutive identical failures is not a transient.

**The fidelity half is FIXED** (c5f6143): a dated withdrawal row makes floorCoverage()
derive haiku-x64 0/6 automatically, and two new checks keep a `how: 'ci'` claim honest.

## ★ `spike/quickjs/` is not a spike — separate the components (2026-08-23)

**Noted, not planned.** User: *"spike/quickjs/ smells funny and suggests that QuickJS
should be in our build graph some other way than 'source code in this tree directly'.
And I bet there are several more separable components that should be separated."*

**The smell, concretely.** A directory named `spike/` — the universal signal for
throwaway exploration — is load-bearing production infrastructure. `PINS.md` is the pin
of record, read by `scripts/build-clode-main.mjs`, `scripts/build-templates-manifest.mjs`
and `release.yml`. `patches/` holds 23 engine patches. `atomic-shim.c` is compiled into
every engine. `qemu/` is consumed by two CI actions. Four of the six engine-recipe inputs
(`scripts/engine-recipe.mjs`) live under `spike/`. Nothing about that is exploratory.

**QuickJS itself is already NOT in the tree** — `spike/quickjs/vendor/` is 753M and
gitignored, so what we actually keep is a *pin plus a patch stack*. That is a coherent
thing; it is just not named or shaped like one, and it is the shape the user is asking
about: whether the engine should enter the build graph as a declared, versioned
dependency rather than as directory-shaped convention.

**Candidate seams, in the order the evidence supports them:**

1. **Engine recipe** — `PINS.md` + patch stack + `atomic-shim.c` + `scripts/*.toolchain.cmake`.
   The patch stack is ALREADY SPLIT ACROSS TWO DIRECTORIES: `spike/quickjs/patches/`
   (txiki/quickjs-ng) and repo-root `patches/` (the three cosmo ones). That split has
   already cost real money — the cosmo patches were not in the engine recipe at all, so
   `libtjs-cosmo.patch` rotted for 13 commits with no cache invalidation and no drift
   signal (fixed in a6fc3e8 by widening `FILES`, which is a patch over the smell, not a
   fix for it). One patch directory, or one manifest naming both.
2. **VM / emulation rigs** — `spike/quickjs/qemu/` is test infrastructure used by
   `build-leg` and `guest` actions. Unrelated to engine source.
3. **Genuine spike residue** — `results/`, `boot/`, `syntax/`, `probe.js`,
   `inventory.cjs`, `measure-mem.sh`, `bc-le-oracle.mjs`. Some is live documentation
   (design memos are cited by comments in `libexec/clode-fuse.cjs` and
   `libexec/bun-shim.cjs`) and some is dead. Worth separating "notes we still cite" from
   "notes about a decision already made".
4. **Provenance data** — `tls-cacert-provenance.json` is neither engine source nor spike.

**Why it is worth doing rather than tolerating.** The recipe is the identity of an
engine, and it is now load-bearing in three places (tjs cache key, `templates-drift`, the
manifest `recipe` stamp added in 4f86738). An identity assembled from globs over
directories that mean different things is one rename away from silently covering the
wrong set — the exact failure `test/engine-recipe.test.cjs` exists to catch, and the
exact one that already happened with the cosmo patches.

**Do not start this without a plan.** It touches the engine recipe, so a careless move
changes every engine hash and rebuilds every leg. See [[clode-backlog-plan-first]].

## ★ Move the engine build to cmake — the last hard Node dependency (2026-08-05)

Direction (user, 2026-08-05): "we need to move toward cmake when we move away from node."
Sequenced AFTER the Node-retirement work, but it is the piece that actually completes it.

**The asymmetry.** clode RUNS without Node — that shipped. clode cannot BUILD ITS OWN ENGINE
without Node, because `scripts/build-tjs.cjs` (3,270 lines) is the orchestration. So
"move away from node" is not done while the engine build needs it.

**The motivating evidence — a build that silently discarded a patch.** Patching any txiki JS
source under `src/js/**` had NO EFFECT: cmake compiles `src/bundles/c/**` (pre-compiled
quickjs bytecode arrays txiki git-tracks), and build-tjs.cjs regenerated those only behind an
opt-in `CLODE_TJS_REGEN=1`. A correct `AbortSignal.timeout` patch (+ its C binding) built
clean and changed nothing; the esbuilt `.js` HAD the change while the `.c` that compiled was
pristine upstream, three minutes older. No failure signal anywhere. Full detail in memory
`polyfill-patches-dropped-on-le`.

**Why that argues for cmake specifically.** txiki's own Makefile already declares the rule we
needed — `src/bundles/c/core/polyfills.c: $(TJSC) src/bundles/js/core/polyfills.js`. We bypass
it by driving cmake directly and shipping pre-built `.c`, then re-derive the ordering by hand
in imperative JS, and got it wrong. A declarative OUTPUT/DEPENDS rule regenerates when its
input changes, full stop: no flag, no fingerprint trailer, no staleness tripwire — because
staleness stops being expressible. We are currently building a tripwire to catch a class of
bug a real build graph makes unrepresentable.

**Split the work by what actually fits.**
- NATURAL for cmake: bytecode regen as custom commands with real deps; host-vs-target `tjsc`;
  the source fixups; per-target compile config; the cross-files we already hand it.
- AWKWARD for cmake: cosmocc toolchain provisioning (fetch + sha-pin a 441MB zip); vendor
  reconstruction (pinned clone + 16 patch applications); post-build hermeticity verification
  of the shipped binary; artifact naming/placement. cmake can shell out for these, but that
  just relocates the imperative code.
- So the likely shape is: **cmake owns the build graph; something small owns provisioning and
  verification** — and that something must run WITHOUT Node, i.e. quaude itself or shell.

**Constraints any replacement must keep.** 36 published run-targets including cross-builds,
cosmo APEs, and Tiger PPC; `scripts/tjs-legs.mjs` stays the single source of truth for leg
definitions ([[tjs-legs-manifest]]); the build hermeticity check on the shipped binary; and
the out-of-tree/local-disk build requirement below (this tree is NFS).

### ccache rides along with this (deferred 2026-08-06, user's call)

ccache was measured and the case is good, but it belongs HERE, not before: the
compiler-launcher wiring is a cmake concern, so doing it now would mean wiring it
twice. Numbers from a quiet box, so they do not have to be re-derived:

* cold build 308s; incremental on unchanged sources 56s; with regen skipped 50s —
  so regeneration itself costs only ~7s.
* The recurring cost is NOT regen: the source phase resets the vendor checkout
  every build, which forces recompiles even when nothing changed.
* `tjsc` is DETERMINISTIC — two runs produced byte-identical output
  (`e5b091ea...`), so those recompiles are of identical bytes. That is exactly
  what ccache converts into hits, and it is why the case is good.

Not installed on this box; installing it there and in CI is part of the cmake
work, not a prerequisite for it.

## ★ Build-working-dir isolation — no shared-tree tromping (2026-07-25)

Principle (user, 2026-07-25): "cross-build a zillion clodes and quaudes and they
can't be tromping on each other." On a shared NFS tree, EVERY build output AND
every build WORKING dir must be platform-unique (or per-invocation isolated), so
concurrent/cross builds never corrupt each other. Existence-only gates then can't
mistake a foreign-platform artifact for a local one. (DONE: `build/tjs/tjs` output → per-target
`build/tjs/<osToken>-<arch>/tjs`; the cmake build dir → out-of-tree per-target `<outDir>/build`;
and build-tjs is now REENTRANT — ensureCheckout resets the vendored source to a pristine pin
before applyPatches, so a killed/failed build can't poison the next, via
`scripts/tjs-source-reset.cjs` + `test/tjs-source-reset.test.cjs`. That reset also sweeps the
NFS AppleDouble `._*` turds that were making `git clean` exit non-zero mid-sweep.)

STILL OPEN — true CONCURRENT-build isolation of the shared txiki SOURCE:
- Reentrancy (sequential self-heal) is shipped, but the reset-before-patch still mutates the
  ONE shared `spike/quickjs/vendor/txiki.js` checkout, so two builds running AT THE SAME TIME
  on this box still race on it. `applyPatches` is one unconditional, platform-independent patch
  list, so per-target source copies are needed ONLY for concurrent patching, not for the build
  itself. When concurrent local builds are actually exercised, give each build its own source
  via `git worktree`/`git clone --local` at the pin under `<outDir>`, keyed like the build dir.
  (CI legs already each run on a fresh checkout, so CI isn't exposed; this is a local-dev axis.)
- **Build-system rethink goal (user):** take the next step toward FULL CROSS BUILDS — build
  any target from any host. Generalize the host≠target split (CLODE_TJS_OUT/cross-file/
  CLODE_TARGET_*): platform keys become TARGET keys (token/arch injectable; tjsDir/tjsBin
  already accept them), the shared patched source feeds N per-target out-of-tree builds, and
  the tag vocabulary (platform-tag.cjs) is the single axis for output + build dirs across the
  whole matrix. Make the mechanism target-parametric, not just NetBSD-specific.

Sweep needed: audit ALL of build/ and any in-tree scratch (spike/, .matrix/) for un-keyed
working dirs and apply the principle. platform-tag.cjs is the single source of truth for the keys.

AppleDouble `._*` root cause + the mount fix (2026-07-28): the turds are NOT files that need
xattrs — recent macOS (13+) auto-stamps `com.apple.provenance` on every file it writes (git
checkout, build copies, even `touch`), and the tree's NFSv3 mount (`ap-juicer:/export/code/trees`)
has nowhere to store an xattr inline, so each stamped file spawns a `._<file>` sidecar. PROVEN the
copy-tool levers can't stop it: `cp -X` AND `ditto --noextattr --norsrc` STILL made sidecars —
the kernel re-stamps provenance at create time, so it isn't copied, it's re-added (COPYFILE_DISABLE
is likewise futile). The only durable "never happens" fix is STORAGE-side: give the volume native
xattr storage. Plan: keep Mavericks/NetBSD/Linux on **NFSv3** (none of them generate AppleDouble —
provenance is macOS-13+, and non-macOS clients never write `._*`), mount ONLY the recent-macOS box
**NFSv4 with named attributes** — recent macOS is the sole generator, so stopping it there stops the
whole shared tree. CONTINGENT on verifying macOS-over-NFSv4 actually maps xattrs to native named
attributes rather than STILL writing AppleDouble (its NFSv4 support is historically partial): 30-sec
test on a v4 mount — `touch probe.c; ls ._probe.c` (sidecar present = v4 didn't help; absent with
`xattr -l probe.c` showing provenance = native storage, win). Server prereqs: NFSv4 named-attr
export + xattr-capable backing FS. One-time `find <tree> -name '._*' -delete` clears the residue.
User's read (2026-07-28): this NFS friction is probably a nudge to **replace NFS with Syncthing** —
peer-to-peer sync per host, no shared-mount xattr-fallback problem at all (each box has a real local
FS). If Syncthing lands, this whole AppleDouble class evaporates and the reset's `._*` sweep becomes
vestigial. Meanwhile the build is already robust to the turds (the reset sweeps them), so this is an
infra-hygiene task, not a correctness one.

## ★ ACTIVE FRONTIER — the general-purpose cross-build matrix (2026-07-14)

North star (user, 2026-07-14): a cross-build matrix "as **reproducible, large,
well-tested, and reasonably fast** as we can possibly make it."

- **NEXT: the four quality bars for the WHOLE matrix** (native + cpa/vmactions VM +
  Debian-cross + NetBSD build.sh + darwin cross):
  - *reproducible* — immutable pins everywhere: SHA-pin `netbsd-src` (needs fetch-by-SHA in
    the composite) + a Renovate annotation; digest-pinned images; honest-floor SDKs.
  - *large* — the NetBSD fleet, then the same treatment for other build.sh-class and
    Debian-cross-class targets.
  - *well-tested* — push verify coverage up: qemu-user where it exists, qemu-system (NetBSD
    level-3) as the upgrade, arch gate everywhere, attest.
  - *reasonably fast* — cross-build over in-guest TCG where possible (cross = minutes vs TCG
    = ~hour); cache toolchains (machine+src-rev) + tjs (source-hash); tmpfs for disk-bound loops.

- **RESOLVED 2026-08-27 — netbsd-m68k was the last leg with a bespoke cross-file; now gated.**
  Found by a uniformity audit of all 15 NetBSD legs, prompted by the user asking whether any
  variation besides the recently-squelched one survived. The 12 cross legs agreed on EVERY
  field except two: `atomic-shim` (legitimate, documented at `scripts/tjs-legs.mjs:228` — the
  `__atomic_*_8` link wall, off where the arch has native 64-bit atomics) and `cross-file`,
  where m68k alone still named `scripts/netbsd-m68k.toolchain.cmake`. Comments stripped, that
  file differed from the generic one in exactly one substantive way: it hardcoded
  `set(_triple m68k--netbsdelf)` where the generic file discovers the triple by globbing
  `${_tooldir}/bin/*--netbsd*-gcc` — and that regex's own worked example is `m68k--netbsdelf`.
  It was written to be subsumed and the deletion never landed.
  FIXED: the leg now names `scripts/netbsd.toolchain.cmake` (it could NOT simply drop the
  field — `.github/actions/build-leg/action.yml:62` defaults `cross-file` to the darwin-ppc
  file for back-compat, so an omitted field would have silently cross-built m68k with a darwin
  toolchain). `scripts/netbsd-m68k.toolchain.cmake` deleted; `test/tjs-darwin-poll-fixup.test.cjs`
  repointed at the generic file (it only needs SOME non-darwin cross-file to prove the
  darwin-poll guard trips).
  RATCHET: `test/tjs-legs.test.cjs` now asserts every NetBSD cross leg shares the one generic
  file, so the next bespoke file fails a test instead of surviving until someone hand-audits.
  Proven to fail when violated (it names the offending leg), not merely observed to pass.
  Not a variation, by design: `netbsd-sparc` is not a cross leg at all but the own-qemu TCG
  guest (`guest-platform: qemu-netbsd-sparc`, timeout 3600, no guest-packages) — a third family
  beside the cpa VM legs (amd64, arm64).
- **`cross-file` is a required input wearing an optional's clothes — drop the darwin-ppc default
  (queued 2026-08-27, user: "sounds pretty nutty from over here").** `.github/actions/build-leg/
  action.yml:62` declares `cross-file` with `default: "scripts/darwin-ppc.toolchain.cmake"`, so
  an `exec=cross` leg that forgets the field silently inherits a PowerPC-Darwin toolchain.
  Surfaced while repointing netbsd-m68k: dropping the field there — the obvious way to "use the
  default" — would have cross-built m68k against darwin-ppc's toolchain.
  CORRECTION to that commit message (3d0f53f/710c7c9), which called it "a silent wrong answer,
  not an error": it is NOT silent. The file hardcodes `CMAKE_C_COMPILER powerpc-apple-darwin8-gcc`,
  which is absent on a NetBSD cross leg, so cmake fails its compiler check. The failure is LOUD
  but baffling — a NetBSD leg reporting a missing PowerPC Darwin compiler, three layers from the
  cause. Confusing, not dangerous. The entry is worth doing on clarity grounds, not safety.
  MEASURED blast radius: 17 legs set `cross-file` explicitly, 27 omit it — but the value is only
  read on the `exec=cross` path, and every omitting leg is native/guest/qemu EXCEPT `darwin-ppc`
  itself. So the default serves exactly ONE leg, at the cost of making the input look optional to
  every cross leg written from here on.
  FIX: `default: ""`; `darwin-ppc` names `scripts/darwin-ppc.toolchain.cmake` explicitly like the
  other 17; the `exec=cross` step fails early with a real message ("leg <x> is exec=cross and
  declares no cross-file") when it is empty. Same ratchet shape as the m68k gate above: make the
  invariant fail where the mistake is made, not where it surfaces.


- **16 legs declare a `timeout` in SECONDS into a minutes field, defeating the guard it was added
  to be (found 2026-08-27).** `.github/workflows/tjs-legs.yml:78` is
  `timeout-minutes: ${{ matrix.timeout || 90 }}`, and the comment right above it states the
  intent: size each leg to its MEASURED runtime "rather than relying on this ceiling to notice
  trouble", citing the 2026-08-25 incident where a stuck leg held the run and the oracle/Windows
  jobs had not been created after 68 minutes.
  The declared values do not all speak minutes. 20 (6 VM legs), 120 (solaris, openindiana) and
  300 (8 musl-cross + arm64 VM legs) are plausible minutes. `1800` (linux-riscv64, linux-s390x)
  and `3600` (the 14-leg NetBSD cross fleet) are plainly SECONDS — 30 and 60 minutes, which match
  those legs' real runtimes — authored into a field that reads minutes. As written they mean 30
  and 60 HOURS, i.e. 16 of 44 legs carry a "timeout" LOOSER than the 90-minute default it was
  supposed to tighten. GitHub's 6-hour hosted-runner ceiling catches them first, so the practical
  effect is a hung NetBSD leg burning ~6h and holding every `needs:` job behind it, instead of
  failing at the intended 60m.
  FIX: 3600 -> 60, 1800 -> 30, then a test asserting every declared timeout is within a sane band
  (say 5..360) so a seconds value can never be authored again — the band is the ratchet, the
  renumbering alone would just wait to be redone.
  MEASURE FIRST: 60m may be too tight for the NetBSD cross legs. Observed on run 33106606966
  (2026-08-27) they ran 67-71 min; the release run 33094982145 an hour earlier had them at ~50-55
  min. Take the max over a few runs and add headroom rather than pinning to the seconds-value
  someone happened to write.
  MY ERROR, recorded so the next reader does not repeat it: I read `3600` as seconds and told the
  user three legs were "5 minutes from timing out" during the release build. They had ~59 hours of
  headroom. The instrument (my assumed unit) was wrong, not the legs — check how a field is
  CONSUMED before reasoning about its value.

- **The templates cache key omits the RECIPE, so a recipe bump hard-errors instead of missing
  (found 2026-08-27, from a real user cross-build).** `libexec/clode-templates.cjs:87` files the
  engine at `path.join(cacheDir, entry.engine)` — i.e. `tjs-<target>-<tjsPin>` — and line 92 does
  `if (fs.existsSync(dest)) { verify(fs.readFileSync(dest)); return dest; }`. But the manifest
  carries TWO identities: `tjsPin: 26.6.0-1a230d3` AND `recipe: 8048ccbe7039`. Only the pin is in
  the filename. So when the recipe changes and the pin does not, freshly published bytes collide
  with a cached file of the same name and the cache hit fails `verify()`.
  OBSERVED: `clode build --target windows-amd64 / netbsd-arm64` against v0.20260827.1 died with
  `engine tjs-windows-amd64-26.6.0-1a230d3: sha256 277d0a47… != manifest 9dd94841…`. The cached
  files were from Aug 9 and hashed to exactly the reported `got`; macos-arm64/macos-ppc in the
  same sweep were cached the same day as the release, matched, and built fine. The release was
  self-consistent — this is purely the cache.
  SEVERITY: low for correctness (it fails CLOSED — no wrong engine is ever fused, which is the
  gate working), high for confusion. The user cannot tell a stale cache from a broken release,
  and the message does not say "stale cache, delete it". This is a cache MISS wearing a hard
  error's clothes.
  FIX: put the recipe in the cache path — `cacheDir/<recipe>/<engine>` or
  `tjs-<target>-<tjsPin>-<recipe12>` — so a recipe bump simply misses and re-downloads. Then the
  `verify()` failure means what it should: genuine corruption or a bad publish. Keep the verify.
  WHILE IN THERE: the cache also accumulates dead entries under the pre-rationalization vocabulary
  (`tjs-windows-x64-v26.6.0-…`, `tjs-darwin-arm64-v…`) that nothing will ever read again — see the
  canonical-name work. A prune or a cache-version directory would collect both problems.
  SAME SPECIES as the two entries above it: a name that does not capture what it identifies.

- **PACKAGE-CLOSURE MEASUREMENT — first real numbers (run 33125646280, 2026-08-27).** Run 1
  (33121243887) measured nothing: see the probe-rewrite commit. These are from the fixed probe,
  and every figure below is parsed from the manager's own summary — no leg reports a total it
  did not compute.

  | leg | packages | download | note |
  |---|---|---|---|
  | freebsd-amd64 | 44 | 115 MiB | measured |
  | freebsd-arm64 | 44 | 113 MiB | measured |
  | dragonflybsd-amd64 | 43 | 169 MiB | measured |
  | netbsd-amd64 | 15 | unknown | count only |
  | netbsd-arm64 | 6 | unknown | count only |
  | solaris-amd64 | 3 | unknown | count only |
  | openindiana-amd64 | 1 | unknown | count only |
  | openbsd-amd64/arm64 | - | - | VM never booted (`Permission denied (publickey…)`) — INFRA, not the probe |
  | omnios-amd64 | - | - | manager produced NO output, exit 1 (suspect `sudo -n` refused) |
  | midnightbsd-amd64 | - | - | `mport: illegal option -- n` — mport has no dry-run flag |
  | haiku-x64 | - | - | `Usage: pkgman install <package>` — our `-n -y` flags are wrong |

  **READING IT, CAREFULLY.** The pkg-family BSDs are HEAVY: 43-44 packages and 113-169 MiB of
  download each. If that generalised, a pin store means hosting >100 MiB per leg per bump, which
  argues for a cache or pre-baked images. But it does NOT yet generalise: byte data exists for
  only 3 of 12 legs, all in the SAME package-manager family, so the sample is one manager wide.
  The count-only legs are small in COUNT (1-15) but 15 packages could still be 100 MiB — count
  is not a proxy for size, and treating it as one is how you would talk yourself into the wrong
  architecture. DO NOT decide pin-vs-bake on this table yet.

  **TO FINISH THE MEASUREMENT** (each now has a precise, log-backed cause rather than a guess):
  1. netbsd + IPS byte extraction — the counts parse, the sizes do not. Needs the real summary
     line shape from a guest, not another guess at a regex.
  2. `mport` has no dry-run: measuring midnightbsd needs a different mechanism (index query, or
     a throwaway guest where a real install is acceptable).
  3. haiku: find pkgman's actual dry-run flag — its own usage message is in the log.
  4. omnios: why the manager printed nothing at all; check whether `sudo -n` is permitted there.
  5. openbsd: nothing to fix in the probe — its VM failed to boot. Re-run and see.

### Known shipped-artifact bugs

- **`dragonflybsd-amd64` leg red — UPSTREAM VM-IMAGE infra, NOT our code (2026-07-18,
  track-only per user).** The leg fails at guest SETUP, before any tjs build:
  `Error updating repositories!` + `mount_hammer2: cluster_connect(...) failed` — the
  DragonFlyBSD 6.4.2 guest can't update pkg repos / mount its FS. Persistent; the ONLY
  non-green job while everything ours is green. We use `cross-platform-actions/action@v1.3.0`
  (`.github/actions/guest`). Can't route around it: **6.4.2 is the ONLY DragonFlyBSD version
  cpa supports.** vmactions/dragonflybsd-vm has CLOSED prior art that IS our symptom (#12
  "low disk space only on DragonflyBSD", #5 "Installing packages is broken") — a recurring
  DFly-VM-image class problem. The leg is `publish: true` hard-gating with NO `soft-fail`.
  When ready to act: demote to soft-fail (a leg whose guest won't boot ships nothing anyway)
  and/or file a cpa issue. For now: watch upstream.

- **darwin-universal i386/ppc slices are `no-exec` — clode by construction, unverified.**
  The universal artifact lipo's four bare tjs engines (arm64, x64, i386, ppc) then fuses ONE
  canonical-LE trailer spanning all slices, so running the i386 or ppc slice carves the same
  payload and *is* full clode. But i386/ppc are cross-built and never smoked (no such macOS in
  CI), so an arch-specific boot bug would only surface on real hardware. **User will smoke the
  shipped binary on Tiger/PowerPC** — fold the result back here. (CLEANUP, not a bug: the
  builder embeds an all-four-slice fat template but only arm64+x64 are real build hosts —
  embedding arm64+x64 instead of the full fat one trims builder bloat with no capability loss;
  doesn't remove the codesign thin-on-failure fix.)

- **Local builds on the dev mac compile txiki against PKGSRC's `uv.h`, not the vendored one
  (2026-07-31). Latent, currently harmless, sharp.** txiki's FFI lookup sets
  `FFI_INCLUDE_DIR=/opt/pkg/include`, which lands `-I/opt/pkg/include` SECOND in the `tjs`
  target's include path — ahead of every vendored path. pkgsrc also ships libuv, so
  `vm.c` and friends `#include "uv.h"` from pkgsrc while `uv_a` compiles the vendored
  sources against `deps/libuv/include`. Two `uv_loop_t` definitions in one binary. It works
  today ONLY because both are 1.52.x with an identical layout: a pkgsrc libuv bump (or any
  vendored-side field addition) silently corrupts the loop struct with NO compile error.
  FOUND THE HARD WAY: the darwin-poll backend adds 4 fields to `UV_PLATFORM_LOOP_FIELDS`, so
  the local poll build got `uv_loop_t` 1104 (libuv) vs 1072 (txiki) → `poll_fds_used` read a
  pointer → `poll()` EINVAL → SIGABRT before the first JS line. CI and the cross containers
  are UNAFFECTED (no `/opt/pkg` there), and the lean profile the floor legs use
  (`ffi:'off'`) never adds the include. Fix candidates: force the vendored libuv include
  ahead of `FFI_INCLUDE_DIR`, or narrow the ffi include to the specific header. Until then,
  local engine builds that must match CI should pass `CLODE_TJS_FFI=off`. Same family as
  [[dev-box-state-hides-bugs]]: warm/foreign host state hiding — here, *creating* — defects.

- **Try `darwin-x86` WITHOUT the poll backend, sometime.** The old-Darwin poll-backend fix
  (spec `2026-07-31-old-darwin-poll-backend-design`) sets `darwin-poll: true` on BOTH 10.4-floor
  legs — darwin-ppc (where Tiger's kqueue event-drop is ktrace-confirmed) and darwin-x86 (where
  it is ASSUMED by the "on old Darwin, route nothing through kqueue unless we've PROVEN kqueue
  handles it" principle). i386 was never observed failing: there is no Tiger/i386 box, and the
  leg is `no-exec`. So the x86 knob is an unfalsified precaution, and it costs the leg its
  `uv_fs_event` (ENOSYS) plus a divergence from the x64 slice. WHEN a 10.4/10.5 i386 target is
  reachable (a qemu Tiger-x86 guest, or real hardware), build the leg BOTH ways and run the
  agentic differential: if kqueue delivers correctly on Darwin/i386 under the fused runtime's
  fd load, drop `darwin-poll` from that leg and keep it ppc-only. Either result is worth
  knowing — it tells us whether the Darwin 8 defect is kernel-wide or ppc-specific, which is
  direct evidence for the paleo-POSIX floor walk (`panther-floor-next-rung`).

- **~~`http.request`/`https.request` are a WALL in the node-shim (2026-07-31)~~ — CLOSED
  2026-08-22.** Implemented for real over `tjs.connect('tcp'|'tls', ...)`: request/get/
  ClientRequest for both modules, sharing ONE message parser with the server half, and
  characterized differentially against host node (`test/node-shim-http-client.test.cjs`, 22
  plaintext rows + 5 TLS rows, both engines driving the same origin). The 2026-07-31 entry's
  "today's evidence says nothing needs it" was RE-MEASURED before implementing, and was only
  half right:
    - **default Anthropic backend: genuinely latent, confirmed.** A `-p` turn, an interactive
      TUI boot, MCP over HTTP *and* SSE, and a run with `HTTP(S)_PROXY` set reach the client
      ZERO times. axios — the bundle's only heavy `node:http` user under real Node (bootstrap,
      event_logging, mcp-registry, metrics_enabled, datadog) — picks its **XHR** adapter under
      tjs, because txiki defines a global `XMLHttpRequest` and axios prefers
      `['xhr','http','fetch']`. Those requests all complete today (200/202/401 observed).
    - **Bedrock: NOT latent.** `CLAUDE_CODE_USE_BEDROCK=1` with no static credentials drove 10
      `http.request` calls at the EC2 instance metadata service (169.254.169.254) from the AWS
      SDK credential chain; with static credentials it drove an `https.request` at
      `bedrock.<region>.amazonaws.com/inference-profiles` from `@smithy/node-http-handler`.
      Host node, same bundle/env, degrades cleanly to "Could not load credentials from any
      providers"; quaude printed `API Error: <nameless> is not a function` (QuickJS TypeErrors
      carry no symbol name), and on a real EC2 instance role Bedrock could not work at all.
  Deliberately NOT covered, each throwing a named error rather than approximating: `socketPath`,
  `createConnection`, `lookup`, `localAddress`, `family`
  (`ERR_SHIM_HTTP_UNSUPPORTED_OPTION`); TLS options with no `tjs.connect` equivalent — pfx,
  passphrase, secureContext, ciphers, minVersion, maxVersion, checkServerIdentity,
  secureProtocol (`ERR_SHIM_HTTPS_UNSUPPORTED_TLS_OPTION`); non-`chunked` Transfer-Encoding.
  Documented divergences: no connection pooling (always `Connection: close`), `setKeepAlive`/
  `cork`/`uncork` no-ops, `socket.end()` full-closes rather than half-closes.

- **npm `ws` still cannot connect under the shim, and now says so by name (2026-08-22).**
  Implementing `http.request` did NOT unblock `ws`, as had been hoped. Reason, measured:
  `ws/lib/websocket.js` unconditionally sets `opts.createConnection = opts.createConnection ||
  (isSecure ? tlsConnect : netConnect)` before calling `request(opts)` — so `ws` never uses the
  client's own socket; it demands `net.connect`/`tls.connect`, which remain walls. The shim's
  client refuses `createConnection` by name (`ERR_SHIM_HTTP_UNSUPPORTED_OPTION`) instead of
  ignoring it and connecting somewhere the caller did not ask for. Unblocking `ws` therefore
  means implementing a real `net.Socket` (it also reads `socket._writableState.length` for
  `bufferedAmount`), not more HTTP. Not needed today: quaude's WebSocket transport is the
  engine's own header-capable native `WebSocket` (see `libexec/bun-shim.cjs`), and that wiring
  was deliberately left untouched.

- **~~HTTP(S)_PROXY is silently ignored under quaude~~ — HALF WRONG, and the true half is
  FIXED (2026-08-22).** The earlier entry claimed "the engine's `fetch` and `XMLHttpRequest` do
  not consult the proxy environment at all". RE-MEASURED against a local recording proxy, that
  is FALSE: the engine honours `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` for both (txiki's lws
  client vhost — `tjs__parse_proxy_url`/`no_proxy` matching in `src/lws-utils.c`), it tunnels
  even plain http through `CONNECT`, and a *dead* proxy makes the request FAIL rather than fall
  back to direct. A real `-p` turn through a local proxy shows every request arriving there,
  Messages POST included. **The lesson is about the instrument, not the engine:** the original
  measurement was taken with a harness whose mock server lived in the same process as a
  `spawnSync`, so the mock could never accept a connection — everything "went direct" because
  nothing could arrive anywhere. A client-side observation cannot tell "proxied" from "direct";
  only the proxy's own log can.
  The true half: the node-shim's own http/https CLIENT (ours, over `tjs.connect`) ignored the
  proxy environment completely, and ignored a proxy AGENT the caller passed. That is a
  naude-vs-quaude divergence — clode sets `NODE_USE_ENV_PROXY=1` for every target it builds
  (`libexec/target-env.cjs`) and node >= 24 honours the proxy env in its http/https clients
  under that flag — and it was REACHABLE: `CLAUDE_CODE_USE_BEDROCK=1` with a proxy set sent the
  AWS credential chain's IMDS requests (169.254.169.254) straight past the proxy, nothing
  arriving there at all. Now fixed: node's semantics ported (absolute-form request line,
  `proxy-authorization`, `proxy-connection`, global-agent-only, `NODE_USE_ENV_PROXY` strictly
  `"1"`, node's exact `no_proxy` matcher), proved by
  `test/node-shim-http-proxy.test.cjs` against a recording proxy and end-to-end on a fused
  quaude (the IMDS requests now arrive AT the proxy, in absolute form).
  **STILL OPEN, and now loud instead of silent: an https ORIGIN through a proxy.** The CONNECT
  tunnel is trivial; starting TLS on the socket it returns is not — `tjs.connect('tls', ...)`
  always makes its own connection and the engine exposes no adopt-fd/startTls entry point
  (`src/js/core/sockets.js`). So that case throws `ERR_SHIM_HTTPS_PROXY_UNSUPPORTED` rather
  than connecting directly (a direct connection *is* the silent bypass). Closing it means an
  engine patch: either TLS-over-an-existing-socket, or a `proxy:` option on the TLS connect that
  does the CONNECT preamble in C. Same for a socks proxy: node ignores non-http(s) proxy URLs
  and so do we, but we now say so once on stderr instead of bypassing quietly.
  Two smaller residues, both named where they bite: (1) `ALL_PROXY` is honoured here even though
  node ignores it — a DELIBERATE divergence, because the engine honours it for fetch/XHR and a
  client that did not would be the same bypass one env var over; (2) an `https://` PROXY URL
  works, but its certificate can only be trusted via a caller-supplied `ca` — measured, neither
  `SSL_CERT_FILE` nor `TJS_CA_BUNDLE` reaches `tjs.connect('tls', ...)`, so there is no
  environment knob for a private CA on a client socket (node has `NODE_EXTRA_CA_CERTS`). An
  untrusted proxy cert fails visibly; it never falls back to a direct connection.

  **Shape of the fix, and two rejected alternatives (2026-08-27).** The knob to build is
  `NODE_EXTRA_CA_CERTS`, which **appends** to the bundled store rather than replacing it —
  that is exactly what node does (it bundles Mozilla's store AND honours the env var), so
  it is the match-upstream answer, and it needs no platform branches. The wall is unchanged:
  it has to reach `tjs.connect('tls', ...)`, so it is the same engine-patch surface as the
  https-through-proxy case above.
  REJECTED — *shell out to `openssl` instead of bundling certs.* The host-applet pattern
  (rg → ugrep/bfs) transfers to work that is batch, stateless, text-in/text-out and one-shot.
  TLS is stateful, binary-framed, and inseparable from the socket the HTTP client owns;
  `s_client` is a debugging tool, not a proxy. The disqualifier is the failure mode, not the
  effort: a wrong `grep` on `PATH` yields visibly wrong search results, while a wrong
  `openssl` on `PATH` yields a SILENT false "verified". Shelling out would move PATH
  resolution inside the trust boundary. Functionality we can honestly translate; trust
  anchors we cannot.
  REJECTED — *read the system trust store instead of bundling.* Correct advice on a normal
  distro (revocations arrive without a rebuild, corporate MITM roots are picked up for free),
  and it inverts on our matrix. Tiger PPC's Keychain roots are from 2005 and cannot validate
  today's TLS; NetBSD needs `mozilla-rootcerts` from pkgsrc and often has none; macOS and
  Windows expose no file at all (Keychain / `CertOpenSystemStore`); FreeBSD, Debian and Alpine
  each put the PEM somewhere different. That is a six-way per-platform branch whose failures
  land precisely on the legs that justify this project — so here **bundling IS the portable
  solution** and system-store is the special-casing the doctrine warns about. The real cost of
  bundling is staleness on revocation, which our rebuild cadence and the `tls-cacert.pem`
  drift test bound. Upstream's `--use-system-ca` is the eventual fidelity endgame; treat it as
  a separate, expensive, per-platform project, well after the append knob exists.

### Known quaude runtime bugs

- **quaude does not persist config across invocations — CREDS half open (NetBSD/arm64 at
  least).** The 0-byte `~/.claude.json` config-write half was ROOT-CAUSED + FIXED (2026-07-15):
  the node-shim `fs.writeFileSync` didn't support the fd-as-first-arg form, so CC's atomic
  writer (`ED6`: openSync temp → writeFileSync(fd) → fsync → close → rename) wrote to a bogus
  file named "8" and rename-clobbered the config to empty. Fixed + guarded by
  `node-shim-fs.test.cjs`. **STILL OPEN — the credentials half:** native CC stores login in the
  OS keychain (macOS) or a credentials file; under tjs there may be no keychain-equivalent, so
  the token isn't saved. Confirm `~/.claude/.credentials.json` now persists under quaude (it may
  be a co-fix of the fd-writeFileSync bug); if creds use a different path, re-check keychain vs
  file store. Repro platform: NetBSD/arm64.

- **quaude login browser-launcher does not open the browser (macOS/arm64 at least).** The
  "spawn detached/ignore gap" lead was DISPROVEN (2026-07-15): CC's opener
  (`spawn("open",[url],{stdio:"ignore",detached:true})`) LAUNCHES under real tjs, `open`
  PATH-resolves, and returns its exit code — the mechanism works at every testable layer. NOTE
  `spawn` silently DROPS `opts.detached` (never threaded to `tjs.spawn`, child_process.cjs
  ~L189) — harmless for `open` but a latent gap worth closing. NEXT: needs an INTERACTIVE
  real-quaude login (real browser/OAuth) to repro — likely env/onboarding state poisoned by the
  now-fixed 0-byte config, or a timing/exec-option nuance. Re-test on a fresh quaude now that
  config persists. Workaround: the login URL is printed — open it manually.

- **quaude TUI leaves stale frames on screen (daily-driver, 2026-07-15).** Finished commands
  persist after they should clear (a done `/login` still shows; `/doctor` shows "queued" after
  it ran). The repaint isn't ERASING prior lines — either the cursor-up + clear-to-EOL sequence
  isn't emitted/honored under the tjs tty shim, or the Ink diff-render redundantly repaints
  without clearing (cf. M3 render-parity: tjs interactive render ~1.2MB vs node ~8KB/turn).
  Likely a node-shim `tty`/write or ANSI-erase gap. Part of the M3 render-parity frontier.

- **quaude's fullscreen renderer crashes before it can draw a frame (NetBSD/arm64). FIX
  BEFORE NEXT RELEASE.** PROVEN this session to be NetBSD-SPECIFIC (fullscreen works cleanly on
  macOS; repro lever `CLAUDE_CODE_NO_FLICKER=1`). Whatever enters the alt-screen path takes
  quaude down before a fullscreen frame paints. NEXT: capture the crash on NetBSD/arm64
  (`--debug-to-stderr` / handle+unhandledRejection dump) to get the failing call; suspect a
  node-shim tty/altscreen gap on that platform. See the at-desk release-readiness plan (Task 2).

- **quaude TUI won't exit on double-Ctrl-C (Tiger/PPC Darwin 8). Likely FIX BEFORE NEXT
  RELEASE.** The FIRST Ctrl-C shows "Press Ctrl-C again to exit" (input is fine); the SECOND
  doesn't tear down — the process stays alive, only `kill -TERM` escapes. The fault is the EXIT
  path, not input. Suspect a blocking SYNC tty op during raw-mode restore / alt-screen leave on
  Darwin 8 — the same class as the fixed `/quit` O_NONBLOCK wedge. NEXT: trace the second-Ctrl-C
  shutdown on Tiger (which sync call blocks) and confirm whether the `/quit` O_NONBLOCK fix
  reaches it. See the at-desk release-readiness plan (Task 3). (Secondary, same box: couldn't
  copy the printed OAuth URL out of the frozen login screen — a selection/scrollback issue.)

### Platform wishlist (reachable-frontier tracker)

- **vmactions platforms we do NOT run (surveyed 2026-08-27).** vmactions publishes 27 VM
  actions; we already use eleven of them (alpine, dragonflybsd, freebsd, haiku, midnightbsd,
  netbsd, omnios, openbsd, openindiana, solaris, plus debian/ubuntu via runners). Of the
  fourteen we do not run, these are the ones worth wanting, in order. The rest —
  `almalinux`, `rockylinux`, `openeuler` (same glibc and arch as legs we already have),
  `ghostbsd`, `nextbsd`, `opnsense` (FreeBSD userlands over a kernel we already test) — are
  recorded here as DELIBERATELY DECLINED: distro branding is not an axis, and every leg is a
  standing tax. On 2026-08-27 the legs we already run cost three package-repo outages and
  five dragonfly failures in a day.

  - **hardenedbsd — the one that would teach us something.** FreeBSD with aggressive
    exploit mitigations (W^X, PaX-style). quaude JITs nothing, but it DOES materialise and
    exec a template from a mkdtemp, and build-leg already carries a note that cpa's OpenBSD
    image mounts `/tmp` noexec. So this asks a real question — does a target survive a
    genuinely hostile memory/exec policy? — rather than adding a logo. Highest value of the
    fourteen.
  - **reactos — Win32 without Windows.** Our windows-amd64 binary either runs on a
    reimplemented kernel or names exactly which Win32 surface we depend on. Cheap to try, and
    squarely on the "runs where Claude Code does not ship" thesis.
  - **tribblix — a second illumos distro.** Mostly redundant with omnios/openindiana, but we
    have already been bitten by illumos package NAMING (IPS paths, `developer/gcc14` vs
    `gcc`), and a different distro of the same kernel is where that bites again.
  - **hurd — glibc, plausibly buildable.** The only one of the fourteen with an existing
    toehold in this repo: cosmocc's `hurd.c`-class misc funcs are already discussed at the
    Cosmo APE leg. Unknown whether libuv has a usable backend there; that is the first
    question, not the port.

  **Probably unreachable, wanted only as knowledge:** `plan9` (not POSIX — no libc our
  engine could target), `redox` (Rust OS, no C libc surface), `riscos`, `blissos` (Android
  x86). Recorded so nobody re-derives why they are absent.

  **SEQUENCING, which is the point of putting this here rather than acting on it:** none of
  these before the package-pinning work lands. The existing matrix already fails on other
  people's mirrors several times a day; adding legs before fixing that multiplies a known
  tax. `hardenedbsd` first when the time comes.

- **NetBSD hard-arch remainder:**
  - **vax** (32-bit LE) — dropped from the fleet: toolchain builds, but quickjs assumes IEEE
    floats and VAX has **non-IEEE** F/D/G format. Real fix = a soft-float IEEE mode for GCC's
    VAX backend (a GCC-backend project, not a leg tweak). (Expect ia64, or1k, m68000/sun2 as the
    sweep reaches them.)
  - **DEFERRED PROJECT — `build.sh` light sysroot / "sysroot without userland".** Compose a
    lighter DESTDIR from `distrib-dirs` + `make includes` + runtime libs instead of a full
    `distribution`, so no leg builds userland it throws away (and userland bugs like sbmips
    `crash` never fire). Prototype scaffolding EXISTS, dormant, in netbsd-crossbuild
    (`sysroot-mode: light`). METALOG + `includes` work; the open wall is `lib/csu` not building
    `crt0.o` standalone. Worth finishing — it speeds EVERY NetBSD leg, and there's no blessed
    `build.sh sysroot` op, so a working recipe is a plausible upstream feature. Finish csu, then
    converge the other NetBSD legs onto light.
- **Paleo-POSIX host (macOS floor-walk) — HELD until Tiger is solid (user, 2026-07-28).**
  Walk the darwin floor older (Tiger 10.4 proven → Jaguar 10.2; kqueue is the 10.3 cliff) so the
  event loop runs on pre-kqueue systems. KEYSTONE — the same backend later unlocks A/UX, IRIX,
  and old-everything from one mechanism. Decision (user): do NOT reach down to Jaguar until the
  current floor (Tiger) is trustworthy — reaching below a shaky floor multiplies risk. **Scoping
  insight (2026-07-28):** it is NOT "write a select backend from scratch" — our vendored libuv
  already ships `deps/libuv/src/unix/posix-poll.c` (a `poll(2)`-based `uv__io_poll`, used by
  AIX/generic-POSIX). So the real work is: compile libuv against `posix-poll.c` instead of
  `kqueue.c` for the pre-kqueue Darwin target, and determine whether old-Darwin `poll(2)` is
  reliable (it was historically buggy on pipes/ttys — the reason libuv prefers kqueue on Apple);
  if poll can't drive the loop, fall back to `select()` under it. Resume once Tiger is solid.
- **MorphOS** (PowerPC AmigaOS-family) — tier-3, needs a libuv port (non-POSIX Amiga exec API,
  no epoll/kqueue). The hardware is already reachable via NetBSD/macppc (PPC) + NetBSD/m68k, so
  the fleet covers the boxes without porting the OS. Revisit only if a libuv backend appears.

## Cosmopolitan APE leg — ADDITIVE "one .com everywhere" (spike, 2026-07-28)

One `quaude.com` running native on Linux/macOS/Windows/BSD, x86-64 AND arm64, from one build.
Upside beyond portability: Cosmopolitan gives `fork()`/`exec()` on Windows → agentic-Bash/
child_process could match POSIX fidelity where the win32 SEA can't. ADDITIVE beside the tjs legs,
never a replacement.

Toolchain: cosmocc **4.0.2** (github.com/jart/cosmopolitan), single self-contained zip, produces
fat x86-64+aarch64 APEs. Pin sha256 `85b8c37a406d862e656ad4ec14be9f6ce474c1b436b9615e91a55208aced3f44`
(cosmocc-4.0.2.zip, 441MB). Slots into the existing `CLODE_TJS_CROSS_FILE` seam (a cosmo CMake
toolchain file), a `cosmo` target token, the lean profile (wasm/mimalloc/ffi off).

FEASIBILITY: PROVEN. The two scary unknowns (engine core, errno model) are both resolved; the rest
is a bounded, well-understood port. Spike (this box, arm64 macOS, cosmocc 4.0.2):
- ✓ Step 1: cosmocc builds + a `hello.com` APE runs native.
- ✓ Step 2: **bare QuickJS-ng compiles under cosmocc with ZERO source changes** → a 2.7MB `qjs.com`
  APE that ran and evaluated real JS. The ENGINE CORE is not a blocker.
- ✓ THE CRUX (errno) — CRACKED. libuv maps its error enum to system errno (`UV_E2BIG=(-E2BIG)`),
  but cosmo's errno macros are NOT compile-time constants: they're linker/runtime symbols resolving
  to the HOST OS's native value (probed: `EAGAIN=35` on macOS = the BSD value, would be 11 on Linux)
  — the SAME .com yields different errno per host, so they can't be constant. Enum init → "not an
  integer constant". FIX (proven to clear the blocker): patch libuv's `include/uv/errno.h` guards
  (`#if defined(E2BIG) && !defined(_WIN32)` → also `&& !defined(__COSMOPOLITAN__)`) to force libuv's
  FIXED -40xx codes. FOLLOW-UP for correctness: runtime errno→UV translation (like libuv's Windows
  path), since stored `-errno` (host value) won't equal the fixed UV codes — hot-path retries use raw
  `errno==EAGAIN` (runtime, fine); only public error NAMING needs the translation.
- ✓ Remaining libuv work CHARACTERIZED — a bounded source-portability port, "teach libuv that
  `__COSMOPOLITAN__` is a generic-POSIX + poll platform": (a) cosmo defines `__COSMOPOLITAN__`/
  `__unix__` (not `__linux__`/`__APPLE__`) and ships `poll.h` (no epoll/eventfd; has a kqueue-ish
  sys/event.h) → select `posix-poll.c` + self-pipe wakeup [the SAME backend paleo-POSIX/Jaguar
  needs — one port, two frontiers]; (b) add cosmo to libuv's platform `#ifdef` guards + its
  header dispatch (`uv/unix.h`) so system headers get included; (c) DROP the GNU-branch feature
  macros `_POSIX_C_SOURCE=200112`/`_XOPEN_SOURCE=500` — they HIDE `if_nametoindex` et al. in cosmo's
  headers (cosmo guards them under default/BSD-source); (d) write `cosmo.c` platform file for the
  hurd.c-class misc funcs (exepath/cpu_info/rss/uptime/loadavg). NB cosmocc HARD-enforces
  `-Werror=implicit-function-declaration` (no `-w`/`-Wno-*`/`-std` suppresses it) so every missing
  decl is a real fix. libuv's event-loop hooks are self-contained in `posix-poll.c` already.

PHASE A DONE (2026-07-29) — **libuv's event loop RUNS under Cosmopolitan as an APE** (timer test:
3 ticks, uv_run returned 0). A working libuv-on-Cosmopolitan port, which did not exist publicly.
Clean, upstreamable patch (scratchpad `patches-wip/libuv-cosmo.patch`, 637 lines, 5 files, all
`#ifdef __COSMOPOLITAN__`-guarded → behavior-neutral for other targets, applies clean to pristine
libuv 1.52.2):
- `include/uv/errno.h`: guards force libuv's fixed -40xx codes under `__COSMOPOLITAN__` (like _WIN32).
- `include/uv/unix.h`: dispatch cosmo → new `include/uv/cosmo.h`.
- `include/uv/cosmo.h` (NEW): `#include "uv/posix.h"` (poll(2) loop fields) + declares the interface
  helpers cosmo's libc lacks.
- `src/unix/cosmo.c` (NEW): `if_nametoindex`/`if_indextoname` (documented stubs — no interface scope;
  quaude's global-DNS path never uses them) + `uv_interface_addresses` (empty; no getifaddrs on cosmo).
- `src/unix/udp.c`: add `__COSMOPOLITAN__` to the two existing source-specific-multicast guards
  (SSM absent on cosmo → ENOSYS, like OpenBSD/NetBSD). Source set = generic-POSIX + posix-poll.c
  (drop bsd-ifaddrs.c → cosmo.c); build defines `_GNU_SOURCE _DEFAULT_SOURCE` (NOT the strict
  `_POSIX_C_SOURCE`/`_XOPEN_SOURCE` which hide cosmo's default-source decls); `-std=gnu17` (cosmocc's
  GCC defaults to C23 which hard-errors implicit decls). Errno runtime→UV translation still owed for
  correct error NAMING (not exercised by the timer test).

PHASE B — the tjs.com APE RUNS JavaScript under Cosmopolitan (2026-07-29). ✅ `tjs eval` works
(`COSMO RUNS: 42 | 26.6.0`), ✅ the poll(2) event loop works (setTimeout fires, promises resolve),
✅ a genuine 9.9MB APE. The boot HANG is FIXED — two libuv-cosmo bugs, both committed in
patches/libuv-cosmo.patch: (1) **UV__ERR sign** — libuv guards it with `#if EDOM > 0`, but cosmo's
errno macros are runtime symbols so the preprocessor reads EDOM as 0 and picks the NON-negating
form → every libuv error came back +errno → `uv_fs_open` of a missing file returned +2 (a bogus fd),
and tjs's module loader spun on `pread(2)→EBADF`. Forced the negating form under __COSMOPOLITAN__.
(2) **uv_exepath** — `readlink(/proc/self/exe)` is not portable across cosmo's host OSes; use
Cosmopolitan's `GetProgramExecutableName()`. PHASE C (TLS) — DONE (2026-07-29), zero extra work: HTTPS just works under cosmo. Verified from the
tjs.com APE: `fetch("https://example.com")` → 200; **`fetch("https://api.anthropic.com/v1/messages")`
→ 401** (the real target reached securely — 401 = needs a key); and cert verification is genuinely
ON (`expired.badssl.com` rejected: "server's cert didn't look good, expired"). mbedtls + libwebsockets
build and run correctly under cosmo, CA bundle resolves. So the engine can already do quaude's secure
API traffic. PHASE D (fuse) — MECHANISM PROVEN COMPATIBLE (2026-07-29), and the zipos-vs-trailer design fork is
RESOLVED in favor of the EXISTING trailer fuse (no zipos rework). Confirmed on the cosmo tjs.com APE:
(1) appending a 200KB trailer does NOT break the APE (cosmo's zipos tolerates trailing data — it
scans backward for its EOCD and skips our trailer); (2) `tjs.exePath` resolves; (3) the APE opens +
positional-reads its OWN executable tail (the `tx1k1.js` 12-byte trailer read in
src/js/run-main/index.js works). So fusing quaude = run the EXISTING `libexec/clode-fuse.cjs` with the
cosmo tjs.com as the template (append [bytecode][TPK payload][tx1k1 trailer]); the APE reads it exactly
like the native tjs template. PHASE D DONE — quaude.com does a FULL AGENTIC TURN under Cosmopolitan (2026-07-29). `clode build`
smoke PASSES: "PONG round-trip ok, attest ok". So the fused 49.6MB `quaude.com` APE is a fully
working Claude Code single binary: boots, runs the CLI, TLS to the API, AND completes a full agentic
turn (prompt → API → streaming response → output → sha attest). The last runtime bug was the
agentic-turn SIGABRT (bfb6299): a threadpool worker's futex(FUTEX_WAIT) returned EINTR when SIGCHLD
(a spawned child, e.g. `rg`, exiting) interrupted it, and libuv's uv_cond_wait/timedwait abort() on
any non-zero pthread return (POSIX swallows EINTR; cosmo surfaces it) → spawning any child that exits
aborted quaude. Fixed by retrying on EINTR. THREE genuine latent libuv bugs found+fixed this arc, all
upstreamable: UV__ERR sign (#if EDOM>0), uv_exepath (GetProgramExecutableName), uv_cond_wait EINTR.
SELF-MODIFICATION CHECK (2026-07-29): cosmocc 4.0.2 APEs do NOT auto-assimilate — VERIFIED our
quaude.com is byte-identical (same sha256) before/after a run, APE header + tx1k1 trailer intact. So
the shipped binary stays a pristine portable APE (runs on every host after any run) and the fuse
trailer/attest are stable. (Old APEs self-modified their header on first run; cosmocc 4.x makes
assimilation explicit — `--assimilate` only.)

SPAWN FIDELITY FIX SHIPPED (2026-07-29, 6bf98e5): the child_process/spawn divergence is FIXED. Root
cause was the errno→UV translation gap: the UV__ERR sign fix made libuv return -runtime_errno, but
the enum uses fixed -40xx codes under cosmo, so uv_err_name couldn't name them — a missing-binary
spawn reported `code='Unknown system error -2'` (was even `-78` pre-sign-fix) not `ENOENT`, breaking
the node-shim's e.code checks. Added `uv__translate_sys_errno` (src/unix/cosmo.c, 69 #ifdef-guarded
mappings) routed through UV__ERR under __COSMOPOLITAN__. VERIFIED: tjs.spawn of a missing binary now
throws code=ENOENT; in a real agentic run `rg` now fails GRACEFULLY ("ripgrep not found on PATH…"
instead of "spawn rg Unknown system error -78") and the hook `setEncoding of null` cascade is GONE.
Smoke still passes (PONG + attest). So hooks / rg-search / Bash-tool error handling are correct now.

NEXT — the full FIDELITY RUN (to enumerate remaining diffs): the test/fidelity/ agentic suite
(agentic-tools, agentic-subagent-diff, agentic-workflow-complete) needs (a) a reference binary
CLODE_PROVIDER_BIN (naude or a real claude), and (b) the cosmo engine behind a /bin/sh wrapper (the
APE can't be execve'd directly — same MZ→sh issue clode-fuse already solves) pointed at via the
engine's bootP path. Set that up, run vs the cosmo quaude, triage diffs — likely a few more
node-shim/libuv cosmo gaps (the spawn class is now closed, but streams/tty/fs edges are unaudited).
- PHASE E (wire the leg): build-tjs.cjs cosmo target = apply patches/libuv-cosmo.patch +
  patches/libtjs-cosmo.patch + CLODE_TJS_CROSS_FILE=scripts/cosmo.toolchain.cmake + force lean
  (mimalloc/ffi/wasm/sqlite OFF) + build target `tjs-cli` + chmod +x on cosmoranlib; provision
  cosmocc 4.0.2 (pin sha 85b8c37a…); add a cosmo leg to scripts/tjs-legs.mjs + multi-OS CI (run the
  SAME .com on Linux/mac/Windows/BSD). Do this AFTER fidelity so it codifies the final patch set.
  Fuse APE-spawn (clode-fuse MZ→/bin/sh) already done.

PHASE D FUSE WORKS END-TO-END (2026-07-29): `CLODE_TJS=<cosmo-tjs> clode build` produces a 49.6MB
`quaude.com` APE (cosmo engine + full quaude payload: Claude bundle + node-shim + bytecode) that
BOOTS and runs Claude Code — `--version` → 2.1.218, `--help` prints the full CLI. Fix shipped
(90d59d4, clode-fuse.cjs): the fuse spawns the template engine (to append the payload) and
smoke-tests the result by spawning it; an APE begins with the DOS 'MZ' header so execve rejects it
(ENOEXEC) on non-Windows hosts — detect MZ-magic templates and spawn via /bin/sh (ENOEXEC→script
fallback). REMAINING — RUNTIME: the full mock AGENTIC round-trip SIGABRTs (smoke: "did not complete
the mock round-trip", SIGABRT, empty stdout/stderr) — an abort() in a deeper node-shim path under
cosmo exercised by real agent execution (streaming/tool-use/fs), same CLASS as the boot hang. CLI
paths (--version/--help) and basic -p don't crash. NEXT: reproduce with the mock (startPongMock) +
--debug-to-stderr to find the aborting op, likely another cosmo libc/errno/syscall gap. Then E
(wire the cosmo leg into build-tjs.cjs + tjs-legs.mjs + multi-OS CI). Build-cache note: incremental cmake-on-NFS
under-recompiles (mtime staleness); use `rm -rf build` or Ninja for dev — a non-issue for build-tjs
(builds clean each run). Below: the earlier build-complete characterization.

PHASE B EARLIER — the tjs.com APE BUILDS (2026-07-29). The full txiki tree compiles and LINKS under
Cosmopolitan into a 9.9MB `tjs` Actually Portable Executable that BOOTS (starts running). Every
BUILD-level cosmo gap is solved, all as clean guarded patches: `patches/libuv-cosmo.patch` (libuv
port + 4 misc platform funcs uv_exepath/cpu_info/loadavg/uptime) + `patches/libtjs-cosmo.patch`
(txiki's SIG*-in-static-init fixes) + the cosmo toolchain/compat/prelude + CMAKE_RANLIB=cosmoranlib
(host ranlib can't index cosmo fat archives). Lean profile (mimalloc/ffi/wasm/sqlite OFF); the tjs
CMake target is the STATIC LIB (libtjs_core.a), the executable is `tjs-cli`.
**REMAINING — RUNTIME hang, ROOT CAUSE LOCALIZED (2026-07-29 via cosmo `--strace`):** the tjs.com
APE boots then spins in an infinite loop:
  `openat("tjs:internal/bootstrap", O_RDONLY) → ENOENT`
  `pread(fd=2, 65536, offset) → EBADF`  (repeats forever, offset crawling, position advanced on error)
tjs's module loader fails to resolve the compiled-in builtin `tjs:internal/bootstrap` from the
bytecode registry, falls through to a filesystem/fd load path, and spins on a bad descriptor (fd 2).
NOT missing bundles — `strings tjs | grep internal/bootstrap` = 2, the bundle bytecode C arrays
(src/bundles/c/core/*.c) are compiled in. So it's builtin-module RESOLUTION under cosmo (why the
registry lookup misses → openat), plus a loader bug (the pread-EBADF fallback should fail loud, not
loop). Bisect fact: hang correlates with stdout fd-type (pipe stdout → exits; regular file/​/dev/null/
closed → hang) because the fd table shifts and changes whether the loader lands on fd 2. ROOT CAUSE (2026-07-29, deeper): the hang is `uv_fs_open("tjs:internal/bootstrap")` returning **+2**
(a bogus fd = ENOENT's runtime value) instead of a NEGATIVE error, so `tjs__load_file` (vm.c:917)
accepts fd 2 and spins in the `pread(2)->EBADF` loop. (`tjs:internal/bootstrap` legitimately isn't a
builtin — it's imported by the core bundle and normally load-fails cleanly; the bug is that the
"missing file" error comes back POSITIVE.) Isolated with a standalone `uv_fs_open` probe: returns 2.
PARTIAL FIX SHIPPED (6407bae, in patches/libuv-cosmo.patch): libuv's `UV__ERR(x)` is guarded by
`#if EDOM > 0`, but cosmo's errno macros are runtime symbols so the preprocessor reads EDOM as 0
(VERIFIED) and picks the non-negating `UV__ERR(x)=(x)` → all libuv errors come back +errno. Forced
the negating form under `__COSMOPOLITAN__` in uv/errno.h + uv-common.h. **BUT the probe STILL returns
+2 after that fix** (verified: the fixed macro negates correctly AND fs.c recompiled) — so there is a
SECOND source of the positive result in libuv's fs open path. NEXT: trace libuv `src/unix/fs.c`
`uv__fs_open` / `uv__fs_work` result assignment under cosmo — where does req->result become +2 instead
of -2 (a raw `x = open()` returning the errno? a `result < 0` check that fails under cosmo?). Repro
(fast): the standalone probe `uv_fs_open(NULL,&req,"nope",0,0,NULL)` should be < 0. Then the hang
clears and tjs.com runs. Then Phase C (TLS), D (fuse), E (leg). Below is the earlier characterization:

PHASE B EARLIER (2026-07-29) — the full txiki tree CONFIGURES under the cosmo toolchain and
its CORE COMPILES: quickjs, wurl, txiki's C modules, and the patched libuv all build. Landed:
`scripts/cosmo.toolchain.cmake` (CLODE_COSMOCC, CMAKE_SYSTEM_NAME=Cosmopolitan via
`scripts/cmake/Platform/Cosmopolitan.cmake`, -std=gnu17/_DEFAULT_SOURCE, -isystem cosmo-compat,
force-included prelude, -Wno-error demotions) + `scripts/cosmo-compat/` (sys/syslog.h, net/route.h
aliases cosmo omits; cosmo-prelude.h = u_int, SO_PRIORITY, if_* decls). libuv patch has the CMake
Cosmopolitan source-selection branch. Build via: `--source-only` then apply patches/libuv-cosmo.patch
to deps/libuv, then cmake with the toolchain (-DBUILD_WITH_MIMALLOC/FFI/WASM/SQLITE=OFF, target tjs).
REMAINING for a `tjs.com` (a `patches/txiki-cosmo.patch`): txiki's OWN "constants aren't constant
under cosmo" spots — static arrays indexed by SIG* (src/utils.c `tjs_signal_map`; also signals.c
"modding const structs", mod_os.c, mod_posix-socket.c) must be built at RUNTIME, exactly the class
of the libuv errno fix. Then re-check the libwebsockets tail (SO_PRIORITY handled by the prelude;
watch for more). Then link → run the tjs.com APE.
- Phase C: TLS (mbedtls under cosmo — quaude needs HTTPS to the API; expected easy per getentropy).
- Phase D: zipos-fuse the quaude payload into the APE (/zip/).
- Phase E: wire the cosmo target into build-tjs.cjs + scripts/tjs-legs.mjs; multi-OS CI
  (Linux+Mac+Windows+BSD run the SAME .com); land the libuv-cosmo patch in patches/ once end-to-end.
Design forks for productization: (a) FUSING — APE already uses its tail as a ZIP store (zipos,
`/zip/…`); our quaude trailer-append collides, so embed quaude's payload in the APE zipos instead;
(b) TLS scope for v1 (defer mbedtls, ship lean no-TLS first?); (c) mac Gatekeeper on APE (assimilate
or rcodesign ad-hoc); Windows APE runs unsigned. Spike artifacts live in scratchpad (untracked).

### OPEN — cosmo fidelity has run on 2 of 8 declared run-targets (user, 2026-08-31)

**The user:** "We need to run our cosmo quaude through fidelity on every platform where cosmo can
run. We've only done some of them."

**This is Phase E's unfinished half.** Phase E above already says the goal out loud —
"multi-OS CI (Linux+Mac+Windows+BSD run the SAME .com)". The build half landed; the RUN half did
not, and the gap is exactly measurable because the leg declares its own run-targets.

**The inventory, from `scripts/tjs-legs.mjs:902-940` and `test/fidelity/RESULTS.md`:**

    cosmo-macos-aarch64    tier 0   floor 4/6   B1,B4,C1,G7 (+H1,H3,H4,H7,F6,D6,G2 non-floor)
    cosmo-linux-x86-64     tier 0   floor 1/6   G7 only — the build-pipeline PONG on the ubuntu host
    cosmo-linux-aarch64    tier 0   { tier: 0 } — no date, no note, no row
    cosmo-macos-x86-64     tier 0   { tier: 0 } — "
    cosmo-windows-x86-64   tier 0   { tier: 0 } — "
    cosmo-freebsd-x86-64   tier 0   { tier: 0 } — "
    cosmo-openbsd-x86-64   tier 0   { tier: 0 } — "
    cosmo-netbsd-x86-64    tier 0   { tier: 0 } — "

So the whole "one `.com` everywhere" claim rests on ONE deeply-driven host (an arm64 Mac) plus a
single PONG smoke on the machine that built it. Six run-targets have never executed the binary at
all. The map is HONEST about this — the ledger says it in as many words ("the other seven cosmo
run-targets get nothing from this row", RESULTS.md:175) — but honest-and-empty is still empty,
and cosmo is the one leg whose entire value proposition is the platforms it has not been run on.

**The good news: five of the six already have a rig.** These are not new platforms; they are
platforms this repo already boots for other legs (`scripts/tjs-legs.mjs`):

    cosmo-linux-aarch64    <- linux-arm64-glibc   native arm64 runner (ubuntu-*-arm)
    cosmo-windows-x86-64   <- windows-amd64       windows-latest
    cosmo-freebsd-x86-64   <- freebsd-amd64       vmactions guest
    cosmo-openbsd-x86-64   <- openbsd-amd64       vmactions guest, 7.9
    cosmo-netbsd-x86-64    <- netbsd-amd64        vmactions guest
    cosmo-macos-x86-64     <- NOTHING             no leg in this repo uses an x86-64 macOS runner

So for five of them the marginal ask is "carry the one already-built `.com` into a rig that
already boots, and run the floor rows there" — not "stand up a platform". That is the cheapest
fidelity coverage available anywhere in this repo right now, measured in new infrastructure: zero
for five of six.

**What a run has to actually do, per the ledger's own rule.** The six FLOOR_ROWS, executed on the
run-target's own OS+arch. A build-host PONG earns G7 for the build host and nothing else — that
rule is already written down ("a `.com` smoked on the Linux runner earns the row for
`cosmo-linux-x86-64` and for no other cosmo host", RESULTS.md:42), so the work is per-host by
construction and cannot be short-cut by one green.

**Expect failures, and treat that as the point.** Each of these is a QUESTION this has not
measured, deliberately stated as a question rather than a prediction — no claim about how any of
these platforms behaves belongs here until a run on this machine or a rig says so:

- Does the APE self-extract and exec under each BSD's `/bin/sh` and exec path, in a vmactions
  guest, without an installed APE loader?
- OpenBSD enforces W^X by mount option — does the `.com` run at all in that guest, and does the
  answer depend on where it is written?
- On Windows, does the interactive/TTY path work? The one cosmo TTY bug we HAVE found needed a
  libuv patch (`patches/libuv-cosmo.patch`, the reopen-skip); that fix was found on macOS and has
  never been exercised on the Windows console.
- On macOS x86-64, does Gatekeeper/quarantine block an unsigned `.com` differently than on arm64?
  The leg ships unsigned by design and the release-notes item for that is still open.

A red row from any of these is worth more than the six blanks are now: cosmo's whole claim is
portability, and six unrun targets means the claim is untested precisely where it is boldest.

**Filing note (user asked where this goes):** here, under the Cosmo APE leg, because it is Phase
E's remainder rather than a new initiative. The actual todo list is machine-readable and already
in the tree — every bare `{ tier: 0 }` in that leg's `fidelity` map is one unrun platform, and
`floorCoverage()` derives the tier from RESULTS.md, so a row landing is the only thing that
changes a tier. Nothing else needs to be invented to track this.

## Phase 3 — still open (render parity + apicheck v1 + upstream-txiki batch)

M1/M2/agentic Bash under tjs SHIPPED; these remain:
- **M3 (render parity)** — tjs interactive render is byte-heavy (~1.2MB vs node ~8KB/turn,
  redundant full redraws); non-fatal, the last phase-3 milestone. (Overlaps the stale-frames
  runtime bug above.)
- **apicheck v1 → `clode selftest`** — v0 shipped (`scripts/apicheck.mjs`); v1 = the embeddable
  oracle (recording-Proxy coverage %, checked-in golden baselines, a corpus that exercises
  TOOL-USE turns), then wire it into a shipped `clode selftest [--json]`.
- **Upstream-txiki batch** (awaiting go-ahead): the spawn/stream/CLOEXEC patches + the quickjs-ng
  `v`-flag regexp fix + the phase-2 batch + the WIP `txiki-unhandledrejection-no-abort.patch`
  (formalize when patches/ unfreezes). Minor: `process.resourceUsage` still undefined (add when
  a path needs it).

## Endgame — API-surface gate: reference principles (v0 shipped)

`scripts/apicheck.mjs` (v0) runs the seed corpus under node AND tjs and gates on the `[wall]`
miss union + node-vs-tjs divergences (v1/v2 tracked under Phase 3). Load-bearing principles:
- **Oracle principle (for exotic platforms):** where `node` doesn't exist to diff against
  (NetBSD/SPARC), capture canonical/deterministic outputs (exit codes, crypto digests, fixed
  frames) on a reference platform, check them in, and diff the exotic platform against the record
  — this is what catches big-endian divergence.
- **Harness caution (still live):** this env carries `CLAUDE_CODE_BRIDGE_SESSION_ID` (child bundle
  auths via the parent bridge) — strip it to test real subscription auth.

## Hermetic test execution — still open (one item)

Curate the live `/doctor` parity allowlist — `e2e-doctor-parity` **test 2 is skipped**. A STRICT
native-vs-clode comparison reds on environment noise, not clode bugs; the goal (user decision) is a
curated allowlist of ignorable areas (Updates, Remote Control, Keychain warnings) that fails on
anything else — the upstream-`/doctor`-format drift signal. Needs: give clode's capture the REAL
render deps (kill wrapping noise), normalize status glyphs in `doctor-parity.cjs parseScreen`,
extend the allowlist, un-skip. Validation needs live captures (Keychain dialogs each cycle) — batch
it. (Related: un-skip `test_tui` #60, TUI-fails-loud-on-missing-ws, once its hermetic per-project
trust-state fixture is rebuilt.)

## The test suite requires host Node — can't run on clode's own target platforms (2026-07-24)

The suite is `node --test test/*.test.cjs`, orchestrated by `test/run.mjs` off `process.execPath`
(a real node). So the tests can only run where a modern host Node exists — precisely **not** where
clode is aimed. On a target platform (native binary won't run, no modern node) the suite is
unrunnable. Observed on `netbsd11-arm64`: no `node`/`tjs`/`qjs` on the box, `test/.harness` ships
node24 only for darwin/linux/win, so a `bun-shim.cjs` change made for that platform could only be
verified by pushing to CI. Want: run the suite — or a runtime-agnostic subset of the pure-logic
tests (rewriteSnapshot, CLODE_SHADOWS, translators, arg rewriting) — **under tjs/quaude**, so the
shim is validated on the runtimes clode ships to. Blocker: the tests bind to `node:test` + `node:`
builtins; running under tjs needs either a `node:test` shim on the tjs side or a port of the
pure-logic tests to a runtime-neutral harness. Relates to the `tjs-legs.yml` CI leg and the
node-floor squeeze in `LONG-TERM.md`.

## Where's `gh auth login` in the bottom status line?

Observed live: the bottom status line doesn't surface the expected `gh auth login` hint. Likely the
same class as the auto-update nudge — status-line content the bundle computes that clode's
environment (or a shim gap) changes. Investigate: reproduce, compare against native, locate where
the bundle builds that status-line item — is the hint suppressed, mis-evaluated (a `gh`/auth probe
behaving differently under the Node host), or rendered and just not where expected?

## Store our versions more parallel to how upstream stores binary versions

Upstream keeps versioned binaries at `~/.local/share/claude/versions/<ver>` with a
`~/.local/bin/claude` symlink to the active one. clode's cache (`~/.cache/clode/<KEY>`) keys on the
provider binary — `<ver>` when the path encodes one, else `<basename>-<size+mtime>` — and stores an
`.extractor-sig` so a changed extractor re-extracts. The schemes aren't aligned. Want: make clode's
per-version storage mirror upstream's more directly (a `versions/<ver>` layout with an "active"
pointer), so it's obvious which extracted bundle corresponds to which upstream version, easy to GC
stale ones, natural to diff side by side. Relates to the extractor-fingerprint re-extract and the
cache-key logic in `bin/clode` (`cache_key`).

## Proactively steer the model toward clode's update path (system-prompt nudge) — deferred

Idea, deferred. At launch, have `bin/clode` pass a short `--append-system-prompt` line telling the
model it's running under clode/quaude, that Claude Code here is **managed by clode and updated by
rebuilding** (`clode build`) — not `claude update`/`upgrade`/`npm i -g` — and that the target
surfaces a "newer version available" note (in `/status` + `claude doctor`) when upstream ships one.
The flag feeds the bundle's shared system-prompt builder (`Kn1`). WHY MAYBE-LATER: the
`PreToolUse(Bash)` update-guard (SHIPPED) already denies model-issued update/global-install commands
with a clode-pointing message, and the notify surface tells the human — so the reactive case is
covered and the nudge is lower-value than when first written. Revisit if the model keeps reaching
for upstream update paths despite the guard. Tradeoff: `--append-system-prompt` is last-wins, so a
user's own value would override clode's (the bundle also concatenates a settings `appendSystemPrompt`
inside `Kn1`).

## Windows code-signing / Smart App Control — deferred decision memo (2026-07-04)

**Current call: ship UNSIGNED.** For the unsigned `clode.exe` (and, now, an unsigned win32
`naude.exe`): most Windows users run it today; revisit signing when a real SAC-blocked user reports
it. Who's affected:
- ❌ **Hard-blocked:** Windows 11 with **Smart App Control (SAC) in Enforcement** — checks all
  executables regardless of origin; only signing fixes it, and only once reputation builds (no
  per-file "Run anyway"). SAC auto-enables only on clean/OEM Win11 (never on a 10→11 upgrade).
- ⚠️ **Bypassable warning ("Run anyway"):** Win10 / Win11-without-SAC when the file carries
  Mark-of-the-Web (browser/email download). One click, per file hash.
- ✅ **Runs clean:** Windows 10 (all), Server, any Win11 with SAC Off/Evaluation, AND any Windows
  where the file has no MOTW — fetched via CLI (curl/wget/`gh`/winget/scoop), git, or copied.
  clode's dev audience skews heavily here.
Notes: EV certs no longer bypass SmartScreen; reputation is per (hash+publisher) and ramps over
weeks; CLI installs usually don't set MOTW. Cheapest signing path when worth it: **Azure Trusted
Signing** (~$10/mo, cloud HSM, CI-native, individuals in US/Canada eligible). `scripts/sea-sign.cjs`
is already structured to add a real `signtool sign` on Windows when creds are present — wiring is a
small `release.yml` + `sea-sign.cjs` change behind a secret. **OPEN ITEM:** that Windows `signtool`
wiring, deferred until a user is actually SAC-blocked.

## node-shim Linux portability (first surfaced by the s390x BE oracle, 2026-07-09)

The s390x-musl leg is the first time the node-shim suite runs against a **Linux** tjs (the pinned
binary is darwin; the qemu guests are NetBSD). The BE oracle proved the engine is big-endian-clean,
but surfaced darwin assumptions the shim bakes in — Linux-portability debt, NOT big-endian bugs:
- **os.constants.signals is a hardcoded darwin table.** The shim returns darwin signal numbers
  (SIGBUS=10) where Linux differs (SIGBUS=7). Fix: per-platform signal tables (linux/darwin/
  netbsd/BSDs) in os.cjs (or constants.cjs). TDD: characterize against host node per-platform.
- **bun:ffi `suffix` hardcodes macOS 'dylib'.** Should be platform-aware (.so Linux/BSD, .dylib
  darwin, .dll Windows) — bun-shim.cjs BUN_BUILTINS['bun:ffi'].suffix. The bunshim test hardcodes
  the macOS extension too; fix both.
- **Audit for other hardcoded darwin assumptions** now that a Linux target exists: library
  extensions, default paths, os.constants.* / signal / errno tables, DYLD_* vs LD_* env handling.
  Sweep libexec/node-shim/** and libexec/bun-shim.cjs.
Not matrix-blocking (the BE oracle scopes these out); about node-shim FIDELITY on Linux, which the
shim-fidelity gate should grow to cover once a Linux tjs is a first-class local build target.

## ★ OPEN — MCP over SSE POSTs to `/[object Object]` under quaude (2026-08-06)

**Symptom.** With an `{"type":"sse"}` MCP server, quaude opens the stream fine and
receives the `endpoint` event, then POSTs its JSON-RPC to a path that is a
STRINGIFIED OBJECT. Straight off the server's wire log:

```
<< GET  /sse?_=1786022754527
<< POST /[object%20Object]   {"method":"initialize",...}
```

The upstream binary against the SAME server completes `initialize` -> `tools/list`
-> `tools/call` and returns the needle. So the transport works; ours mis-builds the
POST URL.

`new URL('[object Object]', 'http://h/sse')` resolves to exactly `http://h/[object
Object]`, so the value handed to the URL constructor was already an object — i.e.
the `endpoint` event's `data` is not the string the parser expects.

**ELIMINATED with evidence — do not re-chase:**
- `new URL(rel, base)` with a STRING base and with a URL-OBJECT base: identical to
  node.
- `URL.parse(rel, base)` (the static form): present and identical to node.
- `fetch()` response-body chunks for the SSE stream: byte-identical to node
  (`Uint8Array`, decodes to `event: endpoint\ndata: /messages?sessionId=probe`).
- `TextDecoderStream` / `TransformStream` via `pipeThrough`: yields the same
  STRING chunk as node.
- `EventSource` is undefined in node, engine, and shim alike, so the bundle parses
  the stream itself — this is not a missing-global problem.

**Where to look next:** whatever turns a parsed SSE event into the endpoint value.
Everything BELOW that (stream bytes, decode, URL resolution) is proven equivalent,
so the divergence is in the event-object shape the bundle's own parser builds —
likely a `MessageEvent`/event-record field that is a string under node and an
object under the shim. Instrument the value passed to the URL constructor rather
than re-testing the layers above.

**Severity.** MCP/SSE is unusable under quaude; MCP over stdio (fixed 2383de2) and
over HTTP (fixed fc54ae9) both work now. Bundle references: http 314, stdio 136,
sse 94, ws 24 — so SSE is the last common transport still broken. ws is untested.

## ★★ P0 — bundle 2.1.243 BROKE THE EXTRACTOR; `clode build` fails for anyone on it (2026-08-24)

**Found mid-release, by a release dry run.** Upstream published 2.1.243 while dry run 3
and 4 were minutes apart, and 19 legs failed at once.

    2.1.241: extracts OK (28,255,317 bytes)
    2.1.243: EXTRACTION FAILS
      clode: build: extraction failed: no block named entrypoints/cli.js;
             bundle format may have changed (largest candidate was 665 bytes).
             Refusing to guess.

Both are valid Mach-O arm64 binaries that report their own `--version`. Tested with the
CORRECT platform binary each time, so this is NOT the provider-selection bug below —
the packaging changed. Size went 325,055,632 → 361,529,696 bytes.

**Why this outranks the cross-build DOA.** `clode build` extracts from whatever `claude`
the user has. Anyone on 2.1.243 fails immediately, on every platform, native AND cross.
The DOA affects `--target` users only. This is the [[bundle-bumps-add-node-api-reads]]
pattern again, in its most severe form: upstream can kill quaude with no repo change.

### RESOLVED 2026-08-25 (92058a3) — clode builds from the code-split bundle

    clode: fused /tmp/b245/quaude (60149146 bytes)
    clode: smoke: PONG round-trip ok, attest ok

Verified beyond the smoke on darwin-arm64: `--version` reports 2.1.245, `--help`
renders, a real `-p` turn reaches the login prompt (so settings, workspace trust and
auth all work), and `--quaude-attest` verifies every member.

How, in one line each — none of it rewrites upstream's bytes:

- `libexec/bun-graph.cjs` decodes Bun's module table (`base = trailer - 32 - byteCount`).
- `libexec/bun-graph-plan.cjs` orders the graph topologically and generates one shim per
  bare specifier.
- `transformGraph` applies clode's hooks across the graph, exactly-once ACROSS modules.
- The engine compiles each module AS IT IS (`tjs.engine.compile` already passes
  JS_EVAL_TYPE_MODULE); the loader deserializes all and evaluates only the entry.
- Four engine/shim walls, each found by BUILDING rather than reasoning: import.meta
  resolved by name instead of identity, `import.meta.url` not a `file://` URL, namespace
  imports needing declared exports, and eager shim reads tripping walls on import.
- The PRELUDE (globalThis.Bun + __clodeCheckUpdate) rides as its own member, since a
  graph has no single text to prepend to.

**Still to verify: every platform other than darwin-arm64.** The engine patch has only
been compiled here, and the graph path — 41MB of bytecode, 1459 modules deserialized at
boot — has never run on NetBSD, Windows, Solaris or Haiku. Watch startup cost and memory
on the small legs, and the interaction with canonical-LE on big-endian.

---

**ORIGINAL STOP-SHIP, kept for the reasoning:**

**DO NOT TAG A RELEASE UNTIL WE HANDLE THE FORMAT.** (User, reaffirmed 2026-08-25.)

The ORIGINAL reason written here was "a release built against 2.1.241 would ship a clode
that cannot build from current upstream". **That reason is now factually wrong** and is
corrected rather than deleted, because the decision it supported still stands on better
grounds.

What is actually true (verified 2026-08-25 by `npm view ... dist-tags`):

    stable: 2.1.231     latest: 2.1.241     next: 2.1.245

`latest` is 2.1.241, which carves fine — so stable users are NOT broken today, and
2.1.243 has been withdrawn from both `latest` and the public changelog. I read that as
"the release is unblocked". The user disagreed, and was right:

> "I do not agree. The release is blocked. We know we do not handle this format and it's
> already been out there as latest"

**The reasoning that matters:** 2.1.243 WAS `latest` — that is how it turned 19 CI legs
red in the first place. A dist-tag can flip back the day after we ship, with no warning
and nothing we control. "Not currently latest" is a snapshot, not a property. Shipping a
clode we KNOW cannot build the format upstream has already released once means the next
flip breaks every user who took our release, and it looks like we caused it.

And the change is not reverted, only staged: **2.1.245 on `next` has the same shape**
(1385 bare-ESM modules, 12420 static chunk imports — verified by running the extractor
against it). Users who set `autoUpdatesChannel: next` are broken RIGHT NOW.

So the gate is not "is it latest today" but "can clode build the format upstream ships".

**Reproduce:**

    npm i -g --prefix /tmp/npm243 @anthropic-ai/claude-code@2.1.243
    P=$(npm_config_prefix=/tmp/npm243 node scripts/find-provider.mjs)
    node libexec/extract-claude-js.cjs "$P" /tmp/out.cjs      # fails
    # same with @2.1.241 -> succeeds

### DIAGNOSED 2026-08-24 (22f197f) — it is Bun CODE SPLITTING, not compression

**The zstd hypothesis below was WRONG, and I put it there.** Both binaries contain
exactly 25 zstd magic frames (`28 b5 2f fd`), all in the same 62–65MB region, identical
in both — they are Bun's own zstd library constants. The npm platform package ships the
raw uncompressed binary in both versions. The changelog's "75MB instead of 340MB" is the
NATIVE INSTALLER's download channel, not this artifact, which is exactly why the npm
binary GREW (325,055,632 → 361,529,696) instead of shrinking. That size discrepancy was
visible from the start and should have killed the hypothesis before an agent had to.

**What actually changed.** Decoding the Bun standalone module graph in both (trailer
`\n---- Bun! ----\n`; the 32 bytes before it are
`{u64 byte_count, u32 modules_off, u32 modules_len, u32 entry_point_id, …}`; 52-byte
module-table entries — `780/52 = 15` and `72332/52 = 1391`, both exact):

| | 2.1.241 | 2.1.243 |
|---|---|---|
| modules in graph | 15 | **1391** |
| entry_point_id | 0 | **801** |
| entry contents | **28,252,504 B** | **19,949 B** |
| entry first bytes | `// @bun @bytecode @bun-cjs\n(function(exports, require, modul…` | `// @bun @bytecode\n// Claude Code is a Beta product…` |
| bare `// @bun @bytecode` modules | 1 | **1383** |
| `"/$bunfs/root/chunk-*.js"` specifiers | 0 | **110,101** |
| static `from"…"` / dynamic `import("…")` | 0 / 0 | **12,416 / 1,039** |

The entry is now bare ESM with no CJS wrapper — ~20KB of imports that ends
`let{main:gt}=await import("/$bunfs/root/chunk-sypcjjyb.js");…await gt()`. The 28MB CLI
lives in 1383 `chunk-<hash>.js` ESM modules.

**Why `strings` found nothing:** at offset 62,911,598 in 2.1.243 sits Bun's own
format-template string table, which literally contains
`// @bun @bytecode @bun-cjs\n(function(exports, require, module, __filename, __dirname) {`.
Those two stray unnamed ~600-byte blocks are the ENTIRE result of `carveBlocks` on
2.1.243 — they are the "largest candidate was 665 bytes". Real payload names live in a
packed, NUL-free name table
(`…/chunk-1r8fj9eb.js/$bunfs/root/src/entrypoints/cli.js\0`).

**This is not fixable by a carve, and we did not fake one.** There is no single CommonJS
module to extract. Relinking 1391 ESM modules into one `require()`-able file needs scope
analysis, live bindings and dynamic-import handling — a textual approximation is exactly
the wrong answer that `pickEntry`'s refusal exists to prevent. Carving any one block
would boot and then die at the first missing chunk.

**Measured groundwork for the real fix** (measured, not assumed):

- all 1381 carved chunks pass `node --check` as ESM — **0 syntax errors**, so the
  next-NUL boundary is still correct for the new shape
- the static import graph is a **DAG (0 back-edges)**
- **20,070 distinct export names, only 51 collisions** (esbuild renames globally)
- **0 confirmed top-level-await** modules of 1055 conclusively checked (326 inconclusive)

So both "emit the graph as linked ESM files on disk" and "write a real relinker" are
live options. Choosing between them is an architecture decision and belongs to the ★★★
overhaul, not to a hotfix.

**Landed with the diagnosis (22f197f):** `extract-claude-js.cjs` still refuses, but now
names the shape (fires only when BOTH signals are present, so 2.1.241 with zero
specifiers cannot false-positive); output on supported bundles is byte-identical
(2.1.241 → `e87057b7…d123a`, 28,255,317 bytes). Plus
`test/extract-bundle-format.test.cjs` — synthetic fixtures in both shapes and a
real-provider gate, verified passing on 2.1.241 and failing on 2.1.243. NOTE: `npm test`
installs no provider, so that gate SKIPS there; it bites only in CI jobs that set
`CLODE_PROVIDER_BIN`. The durable tripwire is the drift check below.

### ★ THE WORSE BUG: the daily ratchet was GREEN through all of this (FIXED 22f197f)

`scripts/upstream-drift-check.mjs` reported `OK — all 5 anchors present` against
2.1.243 — a bundle `clode build` cannot touch. Verified by running it. The cause is
structural, not a typo: `inspect-claude-bundle.cjs` scans the WHOLE binary for anchors,
and 2.1.243 still contains all that JS as plain text, just in 1383 uncarvable chunks.
**Every check we had asserted something about the CONTENT of the bundle; none asserted
that clode could still GET the content.** A ratchet that stays green through a P0 is
worse than no ratchet — it certifies the break.

Fixed by asserting the one fact every hook depends on: a CJS block named
`entrypoints/cli.js` exists (`inspect --json` already emitted `bun_cjs_blocks`). Proven
green on 2.1.238 and 2.1.241 (darwin AND musl), red on 2.1.243. The general rule, now
written into that file's header: **prefer checks that fail when the product stops
working over checks that confirm a string is still present somewhere in 340MB.**

### Also found: `patchUpdateHint` has been silently skipping since at least 2.1.210

`grep -c 'npm i -g @anthropic-ai/claude-code'` = **0** on 2.1.210, 2.1.218, 2.1.241 AND
2.1.243. That anchor is not in the drift-check `ANCHORS` list, so nothing ever noticed.
Unquantified how long it has been dead or what users lose. Add it to `ANCHORS` — after
determining what the current upstream text is, so the re-pin is real and not a deletion.

### The upstream release notes explained it, and nothing pointed us at them

**2.1.243's own changelog pointed at the area**, and I found it only because the user
asked whether we look. Read it as a POINTER, not an explanation — taken literally it
sent me to compression, which was wrong (see the diagnosis above):

> "Improved native install and auto-update download size: the binary is now
> **zstd-compressed** (about 75 MB instead of 340 MB on Linux x64)"
> "Improved memory usage of native builds: **code is now loaded on demand** instead of
> keeping the whole bundle resident"
> "about 2 MB smaller by **storing the bundled skill and prompt text more compactly**"

When 19 legs went red I went straight to byte-diffing two binaries. The answer was in a
public changelog the whole time.

**We are not without machinery — it is aimed at the wrong moment.**
`libexec/clode-update.cjs:159` already "surfaces Anthropic's direction-of-travel signals
(release-note lines + bundle markers)" and, in a source checkout, writes a reviewable
`signals/<ver>.json`. Three problems:

1. **It fires on `clode update`** — a user-facing action — not when a bundle bump breaks
   CI, which is when the question actually gets asked.
2. **Its output is not kept.** There are 9 `signals/*.json` on disk and exactly ONE is
   tracked in git. The evidence is captured and then thrown away, so nobody can look
   back at what upstream said around a break.
3. **Nothing connects "CI broke after a bundle bump" to "read the release notes".** The
   upstream-drift job boot-smokes a leg daily, which detects breakage but says nothing
   about WHY.

**What would have caught it:** the daily upstream-drift job already knows the bundle
version it tested. Having it fetch and diff the upstream changelog between the last-known
and current version — and print the delta on failure — turns "19 legs are red" into "19
legs are red, and upstream says the binary is now zstd-compressed". That is a small
change to a job that already runs.

**Caveat learned the hard way:** the delta is a LEAD, not a diagnosis. The zstd line
above is a true statement about a different artifact that would have sent the next
person down the same wrong path. Print it as context to investigate, never as a cause.

This belongs to the ★★★ overhaul under "what we can DETECT", not just what we can build:
upstream has now broken us twice with no repo change ([[bundle-bumps-add-node-api-reads]]
was the first, `os.constants.errno` in 2.1.238), and both times we found out by accident.

### Fixed while finding it (both real, both mine)

1. **Three files still had hand-rolled provider lookups** — `.github/actions/build-leg`
   (x4), `naude-cross.yml` (x4), `upstream-drift.yml` (x1) — despite my claiming "one
   home" when I converted ci.yml. 2.1.243 ships `bin/claude.exe` INSIDE the wrapper, so
   `find … | head -1` yields a WINDOWS binary first and every Linux/macOS leg picked it.
   All nine sites now use `scripts/find-provider.mjs`, which ranks by platform.
2. **The ratchet had a hole**: `test/find-provider.test.cjs` checked only `ci.yml`. It
   now walks all of `.github` — and that widening is what found the two files I missed.
   A ratchet that covers one file is a ratchet with a hole.

## RESOLVED — the API-surface gate's "25 items to triage" was the instrument (2026-08-25)

Filed earlier today as real work: with the graph runner in place the gate ran again and
reported 25 `Bun.*` uses with 9 unaccounted, 4 missing external modules, and — the part
that mattered — THREE hooks MISSING/AMBIGUOUS, including a claim that `<target> update`
would install upstream Claude Code over the binary. That is the behaviour this release's
changelog says we fixed.

**None of it was true. All nine hooks had applied.** inspect-claude-bundle scans for
literal code fragments, and a graph runner carries upstream as ONE JSON string where every
`"` is `\"`. It was reading JSON and comparing against JavaScript. The three hooks that
"failed" are exactly the three whose patched markers contain a double quote:

    await globalThis.__clodeCheckUpdate("
    switch("clode-managed-target"){case"npm-local":
    globalThis.__clodeWsUnavailable)return"

The other six passed, and that is what made it convincing: a PARTIAL failure reads as
"some hooks did not apply" rather than "this tool cannot read this file". I nearly went
looking for the product bug it described.

Fixed by decoding the envelope before analysing (`decodeGraphRunner`), so every existing
check sees real code. `inspect --strict` is clean on 2.1.245 and the gate passes. Two
tests pin it, including a refusal for a file that claims the marker and carries no graph —
falling through to scan the envelope is the whole defect.

**The lesson is the one already written down and still not automatic:** check the
measuring device first. [[instruments-lie-check-them-first]]. The tell was available
before any investigation — the extractor reports every hook it fails to apply, and it had
reported nothing.

**SECOND DATA POINT, 2026-08-26: netbsd-amd64 hung the same way.** 54+ minutes with every
other job green, against 19 successes spanning 2.3-5.6 minutes. Same shape as dragonfly
that morning: a leg that installs guest packages from a third-party repo, stalling rather
than failing. Two hangs in one day, both in package-installing legs, is no longer a
coincidence worth waiting on — it is the recurring outage this item exists to remove.

**Timeouts are now measured, not defaulted**, on every fast package-installing leg
(netbsd/freebsd/openbsd/omnios/midnightbsd/dragonfly amd64 = 20 minutes against maxima of
2.8-5.6). That BOUNDS the damage; it does not fix the cause. Pinning is the fix.

**REFRAMED 2026-08-27 — the choice is THREE-WAY, and pre-baking is probably the winner.**
The user: "instead of pinning, maybe there's a facility for pre-baking for images with
packages already installed? If that's better." There is, and it likely is.

`VM_PRE_INSTALL_PKGS` in the vmactions builder confs (e.g.
`vmactions/freebsd-builder/conf/freebsd-16.0.conf`) bakes packages into the image at build
time — today it carries `tree`, `rsync`, `fusefs-sshfs`. Our five tools could sit beside
them.

**Why that beats pinning on the merits:** pinning makes the install RELIABLE; pre-baking
REMOVES it. No dependency closure to size, no per-manager offline-install path across six
package managers, no miss to handle, nothing fetched at build time at all. Every mechanism
the pin store needs exists only because an install still happens.

**Three shapes, with their costs:**

1. **Upstream it** — PR the tools into each builder's conf. Cheapest if accepted, and
   almost certainly declined: those images are general-purpose and `cmake`/`node` are our
   build deps, not theirs.
2. **Fork the builders, publish our own images** — full control, pin by digest, zero
   runtime fetch. But it is eleven image pipelines, hundreds of MB each, and we would own
   the base-OS refresh cadence. NOTE THE TRAP: Haiku moved to vmactions precisely BECAUSE
   cross-platform-actions had no beta6 image. Fork, and we become the party who owes an
   image when Haiku ships beta7.
3. **Bake once into a layer we own** — boot the stock image, install the five packages,
   snapshot, reuse. Pre-baking without forking the builder, and the same artifact shape as
   the templates blob we already ship. Probably the target.

**PHASE 1'S MEASUREMENT STILL DECIDES, and its question is now bigger.** It was "how big a
pin store?"; it is now "is the content small enough that pinning is simpler than baking?".
Small closures favour pinning; large ones favour baking decisively, because image size
stops mattering once the alternative is fetching that same content on every run. Do not
pick before the numbers.

## ★★ Our own package pins — stop betting a release on 13 third-party repos (2026-08-25)

**The user, on the dragonfly hang:** "I wonder if it's a package-repo communication
problem. In which case like with Haiku I wonder if we should start having our own tiny
package mirrors with the handful of things we need."

**Confirmed for the earlier failure the same day**, which was not a hang but this:

    Updating Avalon repository catalogue...
    pkg: An error occurred while fetching package: No error
    repository Avalon has no meta file, using default settings
    Unable to update repository Avalon
    Error updating repositories!                          -> exit 3

Same step as the 68-minute hang later that day, so the hang is plausibly the same fetch
failing to RETURN rather than failing to work.

**THE EXPOSURE IS 13 LEGS, and the thing they need is tiny.** 13 of the legs in
scripts/tjs-legs.mjs install guest packages, and the distinct set across all of them is
essentially five things wearing different names per platform:

    cmake (8)  gmake (8)  bash (8)  node (6)  git (5)
    ... plus omnios/IPS spellings: developer/build/cmake, developer/versioning/git,
        developer/build/gnu-make, runtime/nodejs, shell/bash

So every release is 13 independent bets that someone else's repo is up, answering, and
still carrying the version we asked for. The code already knows the last part is false —
`(2026Q1 will eventually be pruned from the mirror)` is a comment in build-leg today.
This is the same class as the Haiku blocker: our build depends on hosting we do not own
and cannot fix. See [[haiku-image-guest-is-superseded]].

**RECOMMENDATION: pin, don't mirror.** Mirroring whole repos means per-platform catalogue
formats, signing, and pruning — a lot of surface for five packages. Instead:

1. **A package PIN store**, one per leg: the exact package files that leg installs, with
   sha256, fetched once and kept in durable storage we control. The templates blob is
   already exactly this shape (one blob + manifest + range fetch, `CLODE_TEMPLATES_BLOB`
   for offline), so it is a pattern this repo has already proven rather than a new idea.
2. **Populate deliberately, never during a release.** A separate job refreshes pins and
   is ALLOWED to fail loudly; a release build installs from pins only. Today the fetch
   and the build are the same step, which is why a repo outage is a release outage.
3. **Fail loudly on a miss**, naming the package and how to repopulate — never a silent
   fall back to the network mid-release, which would restore exactly the flakiness this
   removes.
4. **One mechanism for all 13**, per [[solve-it-portably-not-per-platform]]. The per-leg
   package NAMES already live in tjs-legs.mjs, so the input is a single source already.

**Second prize, if the above is too much for now:** cache the fetched packages by
leg+package-set. Cheaper, and it makes a repeat build immune — but GitHub cache eviction
means a cold release still rides on upstream, so it fixes the common case and not the one
that matters. Worth stating so the choice is deliberate rather than accidental.

**A pin store also buys reproducibility**, not just uptime: today two builds of the same
commit can install different package versions and we would not know. That is a fidelity
question hiding inside an availability question.

## dragonflybsd-amd64 hangs, and its 90-minute default timeout hides it (2026-08-25)

MEASURED across 25 recent runs: a healthy dragonfly leg finishes in **2.8-5.9 minutes**
(n=9 successes) and a genuine failure lands in ~1.4. The leg declares no `timeout` in
scripts/tjs-legs.mjs, so it inherits the 90-minute default in tjs-legs.yml — and one
observed job ran 160 minutes.

It hung THREE TIMES today. On the 2026-08-25 release-gate run it sat at step 4
(`build-leg`) for 68+ minutes with every other leg green, and because the oracle and
Windows jobs are `needs: tjs`, they had not even been CREATED. One flaky VM leg was
holding the whole verdict, and the only way to learn that was to compare elapsed time
against history by hand.

**Two separate to-dos, and the second is the durable one.**

1. Find out WHY it hangs. It hangs before producing log output we can read (GitHub does
   not serve logs for an in-progress job), so the first move is making it say something:
   a heartbeat, or `set -x` in the guest bootstrap, so a hang has a last known position.
   Suspect the same mirror flakiness that failed it earlier today, but that is a guess
   and should be labelled one until measured.
2. Give it a timeout matched to its measured behaviour — 20 minutes is >3x the slowest
   success. A 90-minute ceiling on a 6-minute job does not report a hang, it just delays
   the report by 84 minutes, and everything downstream waits. Check first whether any
   success in the sample was a COLD cache build; if cold builds are legitimately longer,
   the number should cover those, not just the warm case.

Generalises past this leg: **no leg should inherit a default timeout an order of magnitude
larger than its measured runtime.** That is a silent-until-late failure mode across the
matrix, and it is the kind of thing a per-leg `timeout` field derived from observed
duration would fix everywhere at once. Related doctrine:
[[ci-job-is-to-tell-the-truth]] — a check that takes 90 minutes to tell you what it knew
at minute 7 is not telling the truth promptly.

NOT LANDED YET, deliberately: changing CI config now would cancel the in-flight
release-gate run, which is 29/30 green.

## vm.SourceTextModule / vm.SyntheticModule — JS tool-plugins on quaude (2026-08-26)

**Decision: BUILD IT.** The user, asked whether this should work on quaude or be left to
naude: *"Beats me how to decide that, beyond 'yes I always want to match upstream
behavior'."* Matching upstream is the default; see [[match-upstream-by-default]]. My
question was the mistake — cost is an argument about sequencing, not about scope.

**What upstream does with it.** Exactly one module (`_831.js`) uses these, and it is the
JAVASCRIPT TOOL-PLUGIN SANDBOX: `createContext({__proto__:null}, {codeGeneration:
{strings:false, wasm:false}})`, then `SourceTextModule` / `SyntheticModule` with
`initializeImportMeta`, `importModuleDynamically`, and an explicit `importRefusal` for
anything outside the plugin's own folder. Its strings are `tool.register`,
`tool.describe`, `PermissionRequest`, `permissionMode`, `"resolves outside the plugin's
folder"`.

**Scope, measured, because I first got this wrong out loud:** 81 modules mention plugins;
**2** import `vm`. Commands, agents, hooks, skills and marketplace manifests never touch
it. What is unavailable today is specifically a plugin that REGISTERS TOOLS BY RUNNING
JAVASCRIPT — not plugins.

**Also not new.** 2.1.245 has the identical single use of each. We only saw it when the
oracles came back to life after the code-split extraction was fixed — a standing gap
surfacing the moment its instrument worked again, which is the argument for the oracle.

**MOST OF THE WORK IS ALREADY DONE, which I also got wrong out loud.**
`libexec/node-shim/modules/vm.cjs` provides Script, createContext, isContext,
runInThisContext, runInContext, runInNewContext and compileFunction with REAL per-context
isolation, via the `__tjs_vm` primitive in txiki's `src/mod_vm.c`: each context is a child
JSContext with its own global on the shared heap. The isolation primitive — the part that
would have been genuinely hard, and the part that MUST be real because this is a security
boundary — exists and ships.

**DECIDED 2026-08-26: NOT in 0.20260825.1; first item of the next cycle.** Not a scope
retreat — it is an ENGINE change, and that is the whole sequencing argument. `mod_vm.c` is
ours (added by `txiki-vm-context.patch`), so touching it rebuilds tjs on every leg, cuts
new templates, and moves the engine-RECIPE identity — invalidating a full day of matrix
green. Shipping without it regresses nothing: 2.1.245 has the identical usage, so this gap
predates the release. Writing a new security boundary in C and shipping it the same night
is the one sequencing worth refusing.

**THE CRUX, traced rather than guessed.** `__tjs_vm` exposes create / setGlobal /
getGlobal / run, and `run` evals a SCRIPT (`JS_EVAL_TYPE_GLOBAL`) in the child context.
`tjs.engine.compile` compiles a MODULE but only in the main context. So there is no way to
get a module record into an isolated context today, and that — not the sandbox — is the
missing primitive.

**The design that avoids the hard part.** Node's linker is async; quickjs's module loader
is synchronous, and mapping one onto the other looks like the blocker. It is not, because
WE own `.link()`: run the async linker to completion in JS first, collect every resolved
source, then compile them into the child context in dependency order. quickjs checks its
loaded-module list before calling the loader, so the imports resolve with no loader
callback at all — exactly the trick libexec/bun-graph-plan.cjs already relies on for the
main graph. New C needed: `compileModule(wrapper, source, identifier)` and
`evaluateModule(wrapper, mod)` on the child context, plus reaching the existing
import.meta-by-identity patch into that context for `initializeImportMeta`. Roughly 150
lines, plus the JS layer.

**What is actually missing** is the ESM module-record layer over it:

- `SourceTextModule(source, {context, identifier, initializeImportMeta,
  importModuleDynamically})` — compile in a CHILD context, expose the link/evaluate
  lifecycle and `status`.
- `SyntheticModule(exportNames, evaluateCallback, {context, identifier})`.
- The linking protocol: upstream resolves imports itself and returns module objects, so
  `link(linker)` must call back and accept our records.

**The one thing NOT to do**, stated because it is the tempting shortcut: implement these
over our ordinary module machinery in the MAIN context. It would pass a smoke test and
run plugin code with full host access, no codeGeneration restriction, and no import
refusal — a sandbox that is not one, failing silently. A wall is better than that.

Until it lands the wall is honest: a real use throws `node:vm SourceTextModule not
implemented`. It is no longer reported as an exercised wall on ordinary turns — see the
probe/wall split in libexec/node-shim/loader.cjs.

## ANSWERED — Windows 8.3 paths: upstream refuses them, and so do we (2026-08-26)

**Filed hours earlier as an open question — "does real Claude Code refuse a short-path cwd
too, or is our path resolution diverging?" — with a note not to close it on the strength
of a green CI run. It is now answered, by reading the refusal instead of theorising about
it.** The tool_result says, verbatim:

    "Claude requested permissions to write to
     C:\Users\RUNNER~1\AppData\Local\Temp\p3-agentic-*\edit-target.txt, which contains
     a suspicious Windows path pattern that requires manual approval."

**It is upstream's own security heuristic**: Claude Code refuses a Windows path containing
`~` without manual approval, and `RUNNER~1` is an 8.3 short name. quaude reproduced that
refusal faithfully. There is no divergence, nothing to implement, and the containment
theory in the original entry was wrong.

**Two corrections worth keeping**, because both were mine and both cost a CI cycle:

1. I diagnosed "resolved file path vs unresolved cwd" from the shape of the failure
   without reading the whole message — the sentence naming the real cause was there,
   truncated in my own grep.
2. My first fix used `fs.realpathSync`, which does NOT expand 8.3 short names. It failed
   on Windows identically, still reporting `RUNNER~1`. `fs.realpathSync.native` asks the
   OS for the canonical path and returns the long form.

**Kept as a note, not a to-do:** anyone running quaude on Windows from a directory with
`~` in it will hit the same manual-approval prompt — exactly as they would with upstream
Claude Code. That is fidelity, and it is the answer this entry was opened to get.

## ENGINE BUG — evalBytecode on a COMPILED module aborts; only a deserialized one is safe (2026-08-25)

Found while building the graph runner. Compile a large ES-module graph in-process and hand
`tjs.engine.evalBytecode()` the freshly COMPILED entry, and the engine dies with SIGABRT
and no diagnostic. Round-trip the same object through `serialize` -> `deserialize` first
and it runs. Reproduced repeatedly on darwin-arm64 with the real 2.1.245 graph (1432
modules); `--version` survives it and `-p` does not, so it is size- or depth-dependent
rather than categorical.

The runner therefore does what the fuse worker does — compile, serialize, deserialize —
and says why at the call site. THAT IS A WORKAROUND, NOT A FIX, and it costs a
serialize/deserialize pass over the whole graph on every start (measured: about 4s for
2.1.245 on this box, versus a quaude's near-instant bytecode load).

Worth chasing because it is an ENGINE defect we are papering over, and because the fact
that a compiled module and a deserialized one are not interchangeable is exactly the kind
of asymmetry that will bite somewhere else. Minimal repro to build first: N trivial ES
modules compiled in dependency order, evaluate the entry, bisect on N.

Related and probably the same asymmetry: a directly-compiled, never-evaluated module gets
NO import.meta at all (not even `url`), while a deserialized one does — see
test/graph-runner.test.cjs, which pins the runner's own workaround for that.

## ★★★ NEXT: a clear, clean, well-factored, fully cross build (2026-08-24)
### RESOLVED 2026-08-27 — "if we ship it, CI gates it" is now a property, not a list

The push-CI/tag-release divergence item asked for this and it is done for the CI-coverage
half. `CI_EXEMPT` in test/tjs-legs.test.cjs is EMPTY: every OS with a publishing leg is
exercised on push, with no name allowed through.

Both former entries were removed the same day. **haiku** returned to publish:true on the
vmactions/beta6 backend. **openindiana** gained `ci: true`, which it had never had — it was
release-only, so nothing touched it between tags and an image or package-repo drift would
have surfaced DURING a release. On the day this changed, three third-party package repos
misbehaved, which is exactly how that goes wrong.

Both also had an inert `'soft-fail': true` that both tiers stripped from publishers. Inert
until `publish` came off, at which point it would have silently softened a gate. Removed
from both.

**The lesson is the recurring one:** the test's own comment argued at length that
openindiana "should not be exempt at all" and then exempted it by name. A rule that
argues against its own exemption is a rule enforced by a list. Verified: a publishing leg
with `ci: false` now turns the gate red.

**Still open in the parent item:** the release tier publishes assets the push tier never
builds in other respects (the 11 published-but-not-CI-gated legs counted on 2026-08-25 are
now fewer, but the two matrices are still derived separately). This entry closes the
CI-coverage hole, not the whole divergence.


### The case for explicit dependencies: naude broke and only CI could tell us (2026-08-25)

**The user, on being shown that three oracle jobs went red for a reason found locally
twenty minutes earlier by accident:** "Feels like another reason to need CMake and have
explicit dependencies and build steps that I can understand. No reason this needed to wait
till CI to get discovered."

**What happened.** When upstream went code-split at 2.1.243 the extractor learned the new
shape and now stages `graph.json` (+ `graph.qbc`) instead of a single `cli.cjs`. quaude was
fixed, proven, and green. **naude was not, and nothing noticed** — `clode build --naude`
dies with:

    build-naude: --cli path does not exist: <cache>/claude-391948592-.../cli.cjs

That is the REFERENCE ENGINE of the three-way fidelity recipe. It is also the thing that
makes the two shim layers worth keeping distinct at all.

**Why nothing caught it, which is the actual lesson.** The dependency "naude consumes an
extracted `cli.cjs`" is not stated anywhere. It is:

- an argument assembled at `libexec/clode-fuse.cjs:1080` (`'--cli', cliPath`), and
- validated by a path-existence check inside `scripts/build-naude.mjs` at RUNTIME,
  about two minutes into a build.

So when a producer stopped emitting a file, the consumer could only find out by running.
There is no edge to break, because there is no graph — `grep -l 'graph.json'` returns
`quaude-fuse.js`, `node-shim/loader.cjs`, `clode-extract.cjs` and nothing on the naude
path. In a declared build (CMake or otherwise) the extractor's OUTPUTS and build-naude's
INPUTS are both named, and a producer that stops producing is an error at generate time,
before a single byte is compiled.

**THE BLAST RADIUS IS BIGGER THAN naude, and CI spelled it out.** Five jobs fail on
`62df154`, all from the one missing capability — nothing can produce a single linkable
`cli.cjs` from a code-split graph:

    native-builder-oracle      build-naude: --cli path does not exist
    node-shim-oracle           agentic Bash + Edit round-trips, API-surface gate,
    node-shim-oracle-darwin      "extractor byte-identical tjs vs node"
    windows-amd64-tests        same agentic round-trips
    windows-arm64-tests

So it is not "the reference build is down", it is **the entire oracle apparatus is down**
— the agentic round-trips, the shim parity gate, and the tjs-vs-node extractor
differential all stage a single `cli.cjs` and all now hit the code-split refusal. The
thing we would use to check whether the new build path is FAITHFUL is the thing the new
build path broke, and we shipped the build path anyway because its own smoke was green.
That is worth stating as a property: **a change that disables the oracle must be treated
as unverified, not as verified-by-the-remaining-tests.**

**And there is no local target that builds BOTH products.** clode makes exactly two things
— quaude and naude — and the dev loop builds one of them. I found this only because I
happened to build a naude to check something unrelated. That is not a process.

**Three concrete asks for the overhaul, in order of value:**

1. **Name the artifacts and their edges.** stage(provider) -> {graph.json, graph.qbc,
   bun-shim.cjs, cli.cjs?} -> {quaude, naude}. A consumer's input must be a declared
   output, so a format change breaks the graph instead of a job.
2. **One target that builds every product.** If `clode` ships it, the default local build
   makes it. The oracle is a PRODUCT, not a test fixture.
3. **Failure at the earliest possible stage.** A missing staged input should fail at
   configure/generate, not at minute two of an emulated leg. This is the same shape as
   the provider-staging defect above: how a step fails is part of what the step IS.

**Immediate follow-up, tracked separately, and it is a P0** — `clode build --naude` is
broken for anyone on current upstream. CORRECTION to my first read of this: it is NOT
just wiring. `bun-graph-plan.cjs` plans a graph for the ENGINE (compile each ES module,
preregister, evaluate the entry); it does not emit a single CJS, and nothing else does.
naude's SEA main must be CJS, so the shapes genuinely do not meet.

The aligned fix is `module.registerHooks()` (synchronous resolve/load, present in the
v24+ node naude already requires — build-naude.mjs:478 enforces >= v24): embed graph.json
as a SEA asset, serve upstream's modules from it, `import()` the entry. That preserves
the property the quaude path already holds — UPSTREAM'S BYTES ARE NEVER REWRITTEN
(bun-graph-plan.cjs header) — and keeps both targets running the same text, which is the
only thing that makes the oracle an oracle. The alternative, rewriting ESM into a CJS
registry, is explicitly argued against there: it can mangle a prompt string and fail
silently, and a fidelity oracle that quietly differs from its subject is worse than none.


### ★★ Extraction cache key lacked the provider's platform (FIXED 2026-08-28)

**What is PROVEN.** `~/.cache/clode/<version>/` was keyed on the version alone, and reuse
was guarded by the EXTRACTOR's signature. Bun constant-folds `process.platform` at carve
time, so the same version carved from a linux provider and from a darwin provider are
different graphs. Nothing in the key could tell them apart, so extracting one silently
served every later build of the other. Fixed: the key now composes the extractor signature
with the provider's platform, read from the container bytes, and the graph records
`providerPlatform`. Same missing-dimension bug class as the templates cache that served a
sha256 mismatch before the last release.

Graph-level evidence for the mixing, measured in the JSON (valid — graphs are plain text):
`find-generic-password` appears 7× in 2.1.246, 2.1.250 and a fresh extraction of the
installed official DARWIN 2.1.248, but only 2× in the cached 2.1.243 and 2.1.251. 2.1.250
and 2.1.251 are adjacent versions, so a 7→2 swing between them is not plausibly upstream.

**CORRECTION — what I claimed and could not support.** I first wrote that the shipped
2026-08-27 quaude "contains no macOS keychain store", from `strings` finding 0 of three
darwin markers in the binary. **That instrument is invalid.** A fused quaude compiles
modules to BYTECODE, so JS string literals are not present as ASCII. A quaude built from a
known-good darwin graph (7 markers in its graph.json) also scores 0 in the binary — and
authenticates fine. `strings` can measure a graph; it cannot measure a fused target.
Fourth instrument failure in one session: [[instruments-lie-check-them-first]].

**So the Aug-27 failure is NOT root-caused.** What is established: a quaude built
2026-08-28 from the official darwin 2.1.248 on the current tree logs in and completes a
real authenticated turn (`PONG`, real Keychain credential), while the 2026-08-27 2.1.243
binary fails every turn with a 401. The cause of the OLD binary's failure is still open —
a non-darwin carve, a genuine 2.1.243 difference, or something else fixed since. Do not
re-tell the carve story as settled without a darwin 2.1.243 graph to compare against.

**Still worth doing:** a fused target needs a way to answer "which platform was this carved
for?" that does not depend on `strings`. `providerPlatform` now rides in the graph; carry
it into the binary's attest/metadata so the question is answerable after fusing.


### Delete the keychain emulation — upstream already falls back (2026-08-28)

**DONE 2026-09-02.** The premise was re-verified at the version we now actually ship
against, 2.1.251 (not the 2.1.248 this entry originally checked) — a source-level
trace of the staged `~/.cache/clode/2.1.251/graph.json`, not a live driven turn.
Result: the premise holds even more strongly than at 2.1.248. `kn()` (the store
selector) is hardcoded to return the `"plaintext"` store unless a test-only override
throws in production; the OAuth save path (`nOe`/`yqt`) never calls `security` at
all; the API-key keychain-write branch in `unr()` is dead code behind a hardcoded
`let o=!1`; the API-key keychain-remove function `AN()` is an empty stub; and the
doctor's keychain probe is `async function de(){return null}`. The ONLY live
`security` call left anywhere in the 2.1.251 graph is a best-effort, try/catch-wrapped
`find-generic-password` legacy prefetch that never throws on failure. Upstream 2.1.251
does not attempt the real keychain for credential persistence at all in the normal
flow — it goes straight to `~/.claude/.credentials.json`. Deleted the ~300-line block
(`_kcMode` through `_kcMaybe`, all ~55 `_kc*` references) from
`libexec/node-shim/modules/child_process.cjs`, `scripts/kc-mode.cjs`,
`test/kc-mode-suite-default.test.cjs`, `test/node-shim-keychain-async-child.test.cjs`,
`test/node-shim-credentialed-dispatch.test.cjs`, and the emulation-only ~180 lines of
`test/node-shim-child-process.test.cjs`. Centralized the `security`-shadowing PATH
stub (previously duplicated in node-shim-roundtrip-oracle.test.cjs) into
`test/run.mjs`, with a positive-control test
(`test/central-security-stub.test.cjs`) proving a spawned child actually reaches it.
Full report: `.superpowers/sdd/2026-09-02-phase2-name-the-steps/kill-keychain-emulation-report.md`.

**The user:** "Ugh, we still have Keychain emulation? That's caused like five different
problems now." The tally is accurate. Commits touching that block
(`child_process.cjs:206-509`, ~300 lines):

1. `ded7b24` introduced it
2. `714e607` Readable dropped data pushed before a consumer attached — **bug #1**
3. `e928e26` fake `security` calls dropped stderr
4. `1b530eb` emulate mode wrote to its own store, not the shared `.credentials.json`
5. 2026-08-28: `_kcRealSec` bypasses PATH, so a PATH-wrapper instrument reports "zero
   security calls" for a client that is merely being intercepted — hours lost to a
   confident wrong diagnosis

**Its premise is false as of 2.1.248.** `ded7b24`'s written reason was that upstream
"dead-ends" on a headless mac and never persists the token. Tested directly: with a
`security` that always exits 44, official 2.1.248 falls back to
`~/.claude/.credentials.json` and reports the file token's own error. Upstream implements the
store as a named registry — `{name:"keychain", read, readAsync, update, delete}` where
`update()` returns `{success:false, transient}` — i.e. a pluggable store with explicit
failure, and the file store is what it falls back to. We are re-implementing a fallback
upstream ships.

**Sixth latent gap, found while checking:** upstream WRITES via `security -i` on stdin (to
keep the secret out of argv). `_kcSecurityArgs` returns `['-i']`, no subcommand matches, and
the write falls through to the real binary — so in emulate mode reads are faked while writes
are real. Split-brain by construction.

**Recommendation: delete the whole block.** `passthrough` is a no-op by definition;
`emulate` is redundant with upstream's own fallback; `translate` was justified by old-macOS
`security` lacking `-X`/`-U`, but if those flags fail upstream falls back to the file anyway
— and `ded7b24` itself records translate as UNTESTED on real old hardware, so it is an
unverified divergence. Removing it deletes ~300 lines, one divergence, and a whole bug class,
per [[match-upstream-by-default]] and [[solve-it-portably-not-per-platform]]. Confirm the
Tiger persistence story once, then delete.


### ★★★ Make it structurally hard to ship a release without working authentication (user, 2026-08-28)

**The user, on being shown that a shipped quaude cannot authenticate at all:** "it should
be structurally difficult to attempt to ship a release without authentication working."

**What happened.** A quaude built 2026-08-27 fails EVERY turn on macOS with
`401 OAuth access token has been revoked`, because it never reads the platform credential
store — zero `security` calls, silent fallback to a `~/.claude/.credentials.json` that had
been dead for 20 days. Full diagnosis in the session notes; the point HERE is what the
gates did:

- `--version` — green.
- `--help` — green.
- the build's own mock PONG smoke — green.
- 38 CI legs — green on the legs that were green.

**Every one of them passed on a binary that cannot log in.** The product's single most
important capability was completely broken and nothing in the pipeline had an opinion.

**Why the mock PONG can never catch this.** It answers from a canned in-process Messages
mock. It reads no credential, opens no connection, and consults no keychain. It proves the
graph evaluates and the turn loop runs — real value, keep it — but it is structurally
incapable of noticing that auth is broken, because auth is precisely the part it replaces.
This is the [[a change that disables the oracle must be treated as unverified]] shape again:
we substituted the hard part and then read the green as coverage of the whole.

**Two gates, and the cheap one is the important one.**

1. **A real authenticated turn, on the host leg, before a tag.** Standing user
   requirement as of 2026-08-28: prove it by logging in and driving an interactive-TUI turn
   or two with real tokens. This cannot run on every emulated leg — no credentials, no
   network, and we must never put credentials on a runner — so it gates the RELEASE on
   darwin-arm64, not the matrix.

2. **Assert the credential store is ATTEMPTED — needs no credentials at all, so it runs
   everywhere.** The bug was not "the token was wrong"; it was "we never asked". That is
   observable without ever holding a secret: put a logging shim earlier on PATH and assert
   that on darwin the client invokes `security find-generic-password`. It fails closed on a
   binary that silently downgrades to the file store, costs no secret, needs no network, and
   would have caught this exact defect on day one. Same trick generalises per platform as we
   learn each one's store.

   **Validate the harness with a control.** An empty log is equally consistent with "never
   called" and "my wrapper never ran". Wrapping `git` alongside `security` is what made the
   negative trustworthy today (6 git calls, 0 security). A negative assertion with no
   positive control is not evidence — [[instruments-lie-check-them-first]].

   **Gate 2 DONE 2026-09-04:** `test/credential-store-attempted.test.cjs`, wired through
   `test/guard.cjs`'s `defineGuard`/`guardTests` (phase 5, task 13) so the check itself
   carries a mandatory positive control. Real gate: stage a provider's `cli.cjs`, run it
   under real node with `security` AND `git` both shadowed by a private, logging PATH
   stub (`git` also passes through for real), in a scratch git repo, against an
   unroutable `ANTHROPIC_BASE_URL` — no real credentials, no real network, ~5s wall
   clock. Measured: the real artifact issues exactly the two calls this entry names
   (`find-generic-password -a <user> -w -s "Claude Code-credentials"` / `"Claude Code"`)
   during auth/argument resolution, before it ever reaches the network. `examined` is
   deliberately the GIT call count (the positive-control channel), not the security
   count, so a harness that never reached the child reads as BROKEN rather than a false
   OK — the exact "empty log means nothing without a control" property named above. The
   guard's own `control()` reproduces the literal shipped shape (git calls present, zero
   security calls) and is proven, both directions, to make the check go red: with the
   real scan logic the control produces a finding (guard "can fail"); with the
   store-lookup detection itself disabled (`scan` returning no findings unconditionally)
   the SAME control flips `checkControl`'s verdict to `CANNOT_FAIL`, failing the guard's
   own test — i.e. removing the check is what makes this file's tests go red. Darwin-only
   for now, matching everything else in this section; "same trick generalises per
   platform" above is still open, not narrowed.

   **Gate 1 remains open** (a real authenticated turn on the host leg, before a tag) —
   that is credentialed and stays a human release-ritual step per "Release acceptance:
   the checks only a human with credentials can run" below.

**The structural part, which is the actual ask.** Not "add two tests" — tests get skipped,
exempted by name, and quietly stop running (see the openindiana-by-name exemption and the
coverage that turned on and off with machine state). Shipping must be IMPOSSIBLE, not
merely inadvisable, without a recorded authenticated turn against the exact artifact being
tagged. The release job should refuse to publish absent that evidence, the same way it
already refuses on a stale engine. Make the missing proof fail at the earliest stage, not
after the matrix — "how a step fails is part of what the step IS".

**Also worth fixing while here:** the read swallows every failure
(`try{ execFile("security",…) }catch{ i(null) }`), so a shim gap is indistinguishable from
"no credential stored". We cannot patch upstream's swallow, but our own smoke can refuse to
treat a silent fallback as success.


### Which supported platforms actually ship a zstd? (open, 2026-08-30)

We now REQUIRE a host zstd to carve 2.1.251+, and we do not know which of our ~13 supported
platforms provide one out of the box. Verified so far: macOS 26.6.2 ships NONE (absent from
`/usr/bin`, `/usr/local/bin`, and Homebrew's prefix); Haiku needed `cmd:zstd` added to its leg;
the pinned NetBSD/sparc `wd0` image has none at all. Everything else is inference: 19 CI legs
passed with a usable decoder, but GitHub runners and cross-platform-actions guest images are not
stock installs, so that says little about a user's machine. FreeBSD is believed to carry zstd in
base since 12.0 — believed, not checked.

This matters for the README line and the release note, both of which currently imply macOS is
the exception. It may be the rule. Answer it per platform against a BASE install, not a CI
runner, and say so in the docs.

### Nothing renders a diagram (open, 2026-08-30)

2.1.250's chart/mermaid/highlight assets were REFERENCED AND UNSERVED in every target ever
built, and no smoke caught it because those files are read only when something renders. We fixed
the serving and added `test/graph-unserved-refs.test.cjs`, which asserts the rows are SERVED —
but grep says nothing in `test/fidelity/` or elsewhere renders one. So the property that was
actually broken is still unverified: a row can be present and wrong (truncated, mis-decompressed,
wrong encoding) and every current gate stays green.

The fidelity harness is the right home — it already drives real turns against a real API. A turn
that asks for a mermaid diagram or a syntax-highlighted block, asserting the rendered output,
would close the loop the ratchet only half closes. Note this is also the honest answer to
"have our fidelity tests grown to cover diagrams?": no, they have not.

### ★★★ Cross-build everything TWICE, from two very different hosts, and diff (user, 2026-08-30)

**The user:** "Sounds like for *** a good test of the build system would be to cross build
everything twice, from two very different host systems, and look for variations."

**Why this is different from every other gate we have.** Every guard in this repo encodes a
HYPOTHESIS about what might break — an asset that might go unserved, a loader that might move, a
name that might get renamed. They only catch what someone thought of. A two-host differential
encodes no hypothesis at all: it asks whether the output depends on something we claim it does
not. That is the one question our gates structurally cannot ask, and it is the question behind
most of what went wrong on 2026-08-28/29.

**What it would have caught, from this week alone:**
- A darwin target fused from a linux carve. Bun constant-folds `process.platform` at carve time,
  so the graph is per-platform — a fact we learned by shipping a quaude with no macOS credential
  store in it. Two hosts producing different bytes for the SAME target names that instantly.
- The staging merge now runs on the HOST engine while compilation runs on the TARGET's. Its
  output is source text so it SHOULD be host-neutral — flagged as a concern precisely because
  nothing exercises that seam. This is the test that would.
- Host tools leaking into output: we now resolve `zstd`, `tar`, `gzip`, `sha256` from the host,
  each with its own version and quirks. Two hosts means two toolsets; if any of them changes a
  byte of the product, that is a finding.

**Design, and the layering is the whole value.** Do NOT diff only the final binaries. Compare at
each stage — provider carve -> `graph.json` -> merged graph -> bytecode -> fused artifact — and
report the FIRST layer that differs. A binary diff says "something is wrong"; a layered diff says
which step introduced it, which is the difference between a finding and a mystery.

**Expect the first run to fail, and expect that to be the point.** Byte-identical output across
hosts is a strong property we have never claimed, let alone measured. The likely first result is
an inventory of nondeterminism — embedded timestamps, temp-directory names, hash-map iteration
order, absolute paths, tool version strings. That inventory IS the deliverable of round one; the
differential only becomes a gate once the noise is either eliminated or explicitly normalised.

**"Very different" should be chosen for maximum contrast**, not convenience: different OS,
different libc, and ideally different endianness (we have big-endian legs, and canonical-LE
bytecode exists exactly because endianness once bit us). macOS/arm64 versus linux-x64-musl is the
cheap pair; adding a big-endian host is what makes it interesting.

**Relationship to what exists:** this is [[target-matched-assembly]] turned from a rule into a
measurement, and it is the natural gate for the cross-fuse work. It also belongs with
"nothing gates the gates" above — a differential is the one form of gate that cannot be green by
construction, because nothing about it is asserted in advance.

### ★★★ naude and quaude should behave identically, unless there is a written reason (user, 2026-08-30)

**The user:** "I would much prefer, as always, that `naude` and `quaude` behave identically or
nearly so. Unless there's a reason not to."

**First instance, found 2026-08-30: provenance and attestation exist only on quaude.**

| capability | quaude | naude |
|---|---|---|
| `--quaude-attest` — recompute EVERY member hash at runtime, print `all members verified` | yes (`quaude-bootstrap.mjs`, `QUAUDE_FLAGS`), and the build gates on the string (`clode-fuse.cjs:1591`) | **nothing** |
| `providerPlatform` in the artifact — which platform's Claude Code is inside it | yes, `manifest.json` (`clode-fuse.cjs:1452`), readable off the FILE without executing it | **nothing** |
| shared `-p 'say PONG'` smoke against a local mock, `NODE_PATH` deleted | yes | yes (factored out deliberately) |

**Is there a reason?** Partly, and it is worth stating so the fix does not overreach. A quaude is
a tjs engine plus an ARCHIVE OF MEMBERS with a manifest, so "are my members intact?" is a
question it can ask itself. A naude is a Node SEA — one blob — so there is no member archive to
walk. That justifies a DIFFERENT MECHANISM; it does not justify the absence of the capability.
Node SEA supports assets (we already embed `naude-entry.bundle.cjs` via postject), so a naude can
carry a manifest and verify against it.

And for `providerPlatform` there is no structural excuse at all: it is metadata about which
upstream carve went in. Recording it is a one-line-shaped change on a path that already knows the
answer.

**Why this matters more than symmetry for its own sake.** naude's JOB is to be the ORACLE that
quaude is judged against ([[node-only-as-oracle]], [[three-engine-fidelity-recipe]]). Every
divergence between them is a place where the reference and the subject are not comparable — so a
fidelity differential either cannot run, or runs and means less than it appears to. The 2026-08-29
platform-carve bug is the cautionary case: we could not ask a fused binary which platform's bundle
was inside it, drew a confident wrong conclusion from `strings`, and only fixed it for quaude.

**The ask:** treat behavioural parity as the default for the two products, the way
[[match-upstream-by-default]] treats upstream. Any capability present on one and absent on the
other needs a written reason IN THE CODE, next to the divergence — the shared smoke in
`clode-fuse.cjs:526` already models this well, naming what stays out of the shared function and
why. Start by auditing the two surfaces against each other; provenance and attestation are the
two known gaps, and an audit is what says whether they are the only ones.

#### RESOLVED 2026-08-30 — the first instance (attestation + provenance) is closed

`--clode-attest` is now the SAME flag on both products, and the product-named flag it
replaces is DELETED, not aliased (user: "I didn't know it was there and nobody else does
either"). `libexec/clode-attest.cjs` is the one implementation of the argv carve and the
report format; `quaude-bootstrap.mjs` carries the byte-identical inline copy the drift test
enforces, because it is compiled raw to bytecode and cannot require. A naude now bakes a
`manifest.json` + `manifest.sig` SEA asset with the same key set and ORDER as the quaude
archive manifest, `providerPlatform` included, and re-hashes every asset against it.

Both builds run the SAME gate (`attestTarget`) on the binary they just produced, greping ONE
constant imported from the module that prints it. Proved able to fail, on real artifacts, by
flipping one byte: a quaude reports `FAIL bun-shim.cjs` and exits 1; a naude (re-signed
ad-hoc, or macOS kills it before attest can speak) reports `FAIL target-update-check.cjs`
and exits 1.

Two divergences remain, both stated in the output rather than papered over:
- naude prints `note: node_modules rides inside the verified deps.tar member; individual
  packages are not checked`. quaude does per-package SET verification because its node_modules
  ARE members; naude's are one tarball, and opening it would make attest side-effecting.
- naude's manifest has no `idna` — that records which Unicode level the quickjs/wurl URL
  parser was built with, and a Node SEA has no equivalent build-time knob to report.

The general ask above (parity as the DEFAULT, audit the whole surface) is still open.

### ★★ One version, one place to edit it (user, 2026-08-30)

**The user:** "The four-file bump sounds like another one for ***. One place ought to suffice."

**Today it is one fact in four places, bumped by hand every release:** `VERSION`,
`package.json`, and `package-lock.json` TWICE (`.version` and `packages[""].version`).
`test/version-single-source.test.cjs` asserts they agree — and its own header concedes the
point: *"Every release bumps all four BY HAND. Nothing asserted they agree, so three of them
could silently drift."* It chose to ASSERT agreement rather than achieve it, citing that
date-versioning is a human choice rather than something computable from a pin.

That reasoning is sound for why `VERSION` stays committed. It is not a reason for the other
three to be hand-edited.

**The fact that makes this easy: `package.json` is `private: true`.** We never publish to npm —
the release is 40 platform binaries on GitHub. So the npm-side version is metadata no external
consumer reads. It exists to keep npm's own tooling coherent, not to tell anyone anything.

**Two shapes worth weighing, and the choice is not obvious:**
1. **Derive at bump time.** One script takes the new version and writes all four; the human
   edits one thing, the repo stays internally consistent, and the existing test becomes the
   check that the script ran. Cheapest, and it survives npm regenerating the lockfile.
2. **Stop mirroring.** Let `VERSION` be the only truth and leave the npm files inert. Cleaner in
   principle, but npm rewrites `package-lock.json`'s version from `package.json` whenever it
   regenerates, so this trades a manual bump for lockfile churn that will confuse someone later.

I lean to (1) — it is the one that does not fight the tooling — but the decision belongs with
whoever does the work, on evidence about how often the lockfile actually gets regenerated here.

**Related, same shape:** the release also has a "cut under the day it ships" rule, because
date-versioning names the day of the tag rather than the day of the draft. A bump script is the
natural place for that too: it can refuse to write a date that is not today, which is a rule
currently kept by a human remembering it.

### The deadlock guard cannot get scratch space on Windows runners (deferred 2026-08-31)

The `bun-graph` deadlock guard decodes a ~4MB frame to ~6MB, and `test / suite (windows-latest)`
has run out of disk mid-decode twice — at `482e9ec`, and again at `9ee9b1a` WITH a `RUNNER_TEMP`
redirect in place, which means the roomy volume is not where I assumed it was. Two blind fixes
from off-box, both wrong:

- job-wide `TMP/TEMP/TMPDIR -> RUNNER_TEMP` (`4c8d94c`): fixed the space, broke `tar` — Git for
  Windows ships GNU tar, which reads `D:\a\_temp\x` as the REMOTE HOST `D`. Reverted.
- redirect scoped to the test file (`460ea61`, `9ee9b1a`): moved the fixture, then the product's
  `os.tmpdir()` staging too — and it STILL ran out.

**Shipped as a loud skip**, not a red: an ENOSPC-shaped child result now skips naming both sizes,
because "the host had no room to run this check" is not "the decoder streams through stdin", and
reporting the second when the first happened is a lie about the product. The skip is deliberately
narrow — a real decoder failure, a hang, and a success all still take the assertion path
(verified by table).

**Why it cannot simply use a smaller fixture:** the hazard only appears past ~2.65MB through the
pipe, so the frame has to be genuinely large. A highly-compressible payload would shrink the
frame and defeat the guard.

**To fix properly**, someone needs to look at an actual Windows runner and answer what none of my
attempts could from here: which volume has room, how much, and where `spawnSync` stdio capture
puts its bytes on win32. Until then this guard is dark on Windows — and a skipped oracle reads
like a clean one, which is the whole reason it says so out loud.

### ★★★ The quaude build is slow and opaque — name the steps, show how done we are (user, 2026-08-31)

**The user:** "Building quaude has gotten very slow. We need explicit steps and a way to know
how done we are so that we can show the user progress."

**What a build shows today.** `clode build` drives a TTY-only phase SPINNER
(`libexec/clode-fuse.cjs:708`, `makePhaseSpinner`) with exactly three labels, set at
`clode-fuse.cjs:1366`, `:1569` and `:1619`/`:1645`:

    ⠹ Extracting bundle… (14.2s)
    ⠹ Fusing… (211.7s)
    ⠹ Smoking… (8.9s)

Its own comment says why it is a label and not a bar: "discrete phases with no known total".
That was true when it was written. It is not true any more — see below. Everything under
`Fusing` is one word for a minutes-long stretch that internally compiles ~1800 modules, merges
cyclic groups, packs assets, and links a template. The spinner is a liveness indicator, not a
progress indicator: it tells you the process has not died, and nothing else.

**The denominator already exists on disk, before the slow part starts.** Measured here on the
staged 2.1.251 graph:

    $ node -e "...JSON.parse(graph.json)..."
    read 43ms parse 144ms moduleCount 1795
    order array 1835   sources obj 1835   assets obj 173   cyclicRequires array 33

So `graph.json` names the work: 1795 modules to compile, 173 assets to pack, 33 cyclic requires
to merge. `quaude-fuse.js` already prints these AFTER the fact — "compiled N modules -> graph.qbc"
(`libexec/quaude-fuse.js:467`), "pre-compiled N modules" (`:147`), "N text assets ->" (`:462`).
The numbers are known up front and reported only in the past tense. A counter is not a research
project; it is moving an existing number earlier.

**And "very slow" is, right now, an unfalsifiable claim — which is the deeper half of the ask.**
No build records per-step time anywhere durable. The spinner's seconds are drawn to a TTY and
erased by `done()`; a piped or CI build renders nothing at all. So "has gotten very slow" cannot
be checked against "was fast on <commit>", and we cannot say WHICH step grew. One cheap
measurement already narrows it: reading and parsing the 46MB `graph.json` costs 187ms total, so
the minutes are not I/O or JSON — they are in bytecode compilation, the merge, and the engine
build. That is a hypothesis, and it stays a hypothesis until each step is timed.

**What this item asks for, then, is three things and they are ordered:**

1. **Explicit steps.** A named, enumerated step list the build declares before it runs — not
   three ad-hoc `spin.phase()` calls scattered across a 1678-line file. Whatever form the
   out-of-tree/CMake work takes, the step list should come from the same place the build graph
   does, so a step cannot be added without appearing in the display.
2. **A denominator per step.** Compile is `n/1795`. Assets are `n/173`. Merge is `n/33` groups.
   Steps with no natural count (fetch a template, sign, smoke) stay labels, and that is fine —
   an honest mixed display beats a fake percentage.
3. **A durable timing record.** Every step's elapsed time written where a piped/CI build keeps
   it, so a regression is a diff and not a feeling. This is what turns the user's report into
   something we can act on, and it is also what makes any future "we made it faster" claim
   checkable.

**Why it belongs to ★★★ and not to a display tweak.** Steps you can show are steps you have
named, and steps you have named are a build graph. We do not have one — that is exactly what the
naude entry above ("The case for explicit dependencies") found the hard way, when a producer
stopped emitting `cli.cjs` and only a two-minute runtime path check noticed. A progress bar
bolted onto today's imperative script would be a fourth hand-maintained list of what the build
does, going stale the same silent way. Sequence this WITH the out-of-tree/CMake item, not before
it: get the steps declared, and the progress display falls out of the declaration.

### Default artifact names should carry the Claude bundle version (user, 2026-08-31)

**The user:** "Maybe the default built quaude/naude should have the Claude bundle version in
their filename by default."

**Where the two defaults land today** (no `--out`):

    quaude   ./quaude[.exe]                                   resolveBuildOut, clode-fuse.cjs:772
    naude    build/clode-<CLODE ver>-<osToken>-<arch>/naude   seaBin -> artifactDir, platform-tag.cjs:231

So quaude's default carries NO version of anything, and naude's carries **clode's** version, not
the bundle's. Neither answers the question you actually ask of a built binary sitting in a
directory: which Claude Code is inside it? Build twice across an upstream bump and the second
`./quaude` silently overwrites the first; keep both by hand and you are the one remembering which
is which. The binary itself knows (`--clode-attest` reports `bundleVersion`), but the filename —
the only part visible in `ls`, in a bug report, in a scrollback — does not.

**The one real obstacle, and it is a sequencing one.** The output path is resolved at
`clode-fuse.cjs:1221` (`resolveBuildOut`), and the bundle version only becomes known ~200 lines
later at `:1437`, as `staged.key` from `stageUpstreamCli` — which is also where the manifest gets
its `bundleVersion` (`:1510`) and `--self` gets none at all. So this is not a string edit in the
name formatter: either the default name is decided AFTER staging, or the bundle version is
resolved before it (`resolve.cacheKey`, `:457`, is what computes the key). Whichever way, the
`--self` branch has no upstream bundle and must keep a version-free default.

**Open questions this needs answered before it is built, not while:**
- Does an explicit `--out` still win verbatim? (It must — CI passes the canonical published asset
  name, and `resolveBuildOut`'s contract at `:759` is load-bearing for attest/publish agreement.)
- Does naude's name become `clode-<ver>-<token>-<arch>/naude-<bundle>`, or does the bundle version
  join the DIRECTORY key? The directory is the "if it's in build/clode-*, it's shippable" contract
  (`platform-tag.cjs` file header) — changing its shape is a bigger blast radius than changing a
  basename.
- Should quaude's default also move under `build/` rather than cwd? Adjacent to the ★★★
  out-of-tree item; answer them together rather than twice.

Related: [[Arch / artifact-name rationalization — release-atomic remainder (2026-07-27)]] above,
which is the same "one name, agreed by every consumer" problem on the publish side.

### ★★★ Nothing gates the gates — make "a guard that cannot fail" structurally impossible (user, 2026-08-29)

**The user:** "How are you finding these gaps? Is it automated into the build? Or is that another
one for ***?"

**It is not automated. It is people poking at instruments, and that is why it is not repeatable.**
Here is how each defect found on 2026-08-28/29 was ACTUALLY discovered:

| defect | how it was found | automated? |
|---|---|---|
| shipped builder cannot decode zstd (all 21 legs) | CI failed loudly | **yes** |
| a test seeded the real `~/.local/share/clode` | the hermeticity gate | **yes** |
| Windows `accessSync(X_OK)` = EINVAL for every path | CI, but only after an unrelated change routed through `findTool` | partly |
| oracle harness cannot resolve chunks (since 2.1.243) | CI — but invisible for WEEKS because pushes kept cancelling those slow jobs | the signal existed and was being destroyed |
| the pipe-deadlock guard could not fail | a reviewer REVERTED the fix by hand and watched 21/22 rows stay green | no |
| the KAT a header-walking fake could pass | a reviewer BUILT the fake and ran it | no |
| the leg regex matched the library (`zstd`) not the command (`cmd:zstd`) | a reviewer MUTATED the value and watched 41/41 stay green | no |
| layer-2 shim map reported zero gaps for two years | the assert died on `Bun.ant` first; someone checked instead of re-baselining | no |
| SUBCOMMANDS regex matched nothing since 2.1.243 | counting occurrences by hand | no |
| scanner counts OUR generated wrappers and `export{}` facades as upstream references | manual classification of every hit | no |
| `windows-path-ratchet`'s `stripComments()` blanks 1,335 lines across 14 files | unmasked by accident when an agent reordered declarations | no |
| the suite's verdict depends on which `node` runs it (SEA layout changed in node 26) | two agents reported different baselines on identical commits; testing the variable | no |

**Eight of twelve were found by hand, by someone being suspicious.** That is not a process, it is
a mood. It worked because this session happened to have adversarial reviewers with budget; it
will not survive a tired afternoon.

**The unifying defect: we have many gates, and NOTHING GATES THE GATES.** Every hand-found item
above is one shape — a guard that could not fail. It passed for a reason unrelated to the
property it claimed to check: a regex that matched nothing, a fixture below the threshold, a KAT
whose only block was RAW, a scanner counting our own emitted code, a comment stripper that ate
the file.

**The mechanism that makes this structural is MUTATION TESTING, and we already do it by hand.**
Every one of those was caught the same way: BREAK THE THING THE GUARD CLAIMS TO DETECT, ASSERT THE
GUARD GOES RED. Reviewers did it manually and it worked every time it was tried. The ask is to
stop doing that as a favour and make it a property of the build:

1. **A guard must ship with its own red proof.** Not "the test passed" — a recorded mutation that
   makes it fail. If a change cannot make it red, it is not a guard, and CI should say so.
2. **Zero is a failure, not a pass.** Any scanner that can return "found nothing" must treat a
   zero result as broken unless a floor is asserted. Note the one place this ALREADY existed —
   `expected many minified require("fs") aliases, found 0` — is the reason we caught the
   two-year-blind map at all. Generalise that reflex.
3. **A scanner must not count our own emitted code.** Three classes of false positive
   (`__m["X"]` interop wrappers, generated `export{}` facades, recycled minified names) inflated
   an 8-item gap list to roughly 2 real items.
4. **Record the environment with the verdict.** "The suite is green" is a property of the tree
   PLUS the interpreter, and nothing printed which interpreter. Two agents disagreed on identical
   commits for a whole afternoon.
5. **Never let a slow gate's signal be destroyed by a fast one.** `if: ${{ !cancelled() }}` on
   `node-shim-oracle` exists because a haiku failure once skipped it and three windows jobs in one
   stroke. The same lesson applies to the CONTROLLER: pushing for fast leg feedback cancelled the
   slow oracle jobs for many commits, which is exactly how a weeks-old red stayed invisible.


**The concrete population this entry owns.** These are the individual gates found broken or
absent on 2026-08-28/29. They are filed HERE rather than fixed one by one, because fixing each
in isolation is what produced a codebase full of guards nobody re-checked:

1. **`shim-surface` and `guard-subcommands-gate` do not run in CI at all.** `shim-surface` skips
   without BOTH a tjs binary and `CLODE_PROVIDER_BIN`; `guard-subcommands-gate` skips on an empty
   `~/.cache/clode`. The `test` job has neither, so neither has run in CI since 2.1.243 — they
   were locally red and remotely absent for months. Note this is a PLACEMENT problem, not a
   plumbing one: `node-shim-oracle` already stages a provider and sets `CLODE_TJS`.
   `shim-surface.test.cjs` even anticipates the hazard in its own comment — a skipped run "would
   contribute zero gaps and read exactly like a clean one."
2. **`test/node-shim-wall-tripwires.test.cjs` is unaudited and green by construction.** It matches
   the direct `require("fs").watch(` shape, which upstream has not emitted anywhere since the
   2.1.243 code-split. It is the fourth instrument of the family whose other three were all found
   blind. Nothing forces the question because it is green; ask it anyway.
3. **RESOLVED 2026-09-04 (phase 5, task 9).** `windows-path-ratchet.test.cjs` was blind on an
   estimated ~1,335 lines across 14 files — its `stripComments()` mis-paired `/*`…`*/` across
   template literals and blanked real code. Found by ACCIDENT when an agent reordered
   declarations and unmasked two pre-existing `process.env.PATH` sites it had never seen. Fixed
   with a real tokenizer; the measured (not estimated) size was 1,950 lines across 45 files. See
   the "RESOLVED 2026-09-04" entry above and task-9-report.md.
4. **`native-builder-oracle` should be a REQUIRED gate whose failure says the SHIPPED ARTIFACT is
   broken.** It is the job that would have caught the zstd carve break on day one — "the native
   builder BUILDS THE PRODUCT (node-free, real provider)" — and it sat as one red among
   twenty-two. It is the closest thing we have to a gate on the thing users actually get.
5. **No CI leg builds against more than one platform's graph.** That is why a merger corruption
   that broke linux shipped green on darwin. One extra `clode build` against a second platform's
   graph on the macOS leg closes it.
6. **No CI leg carves a zstd row inside a guest any more**, since `stage-provider.mjs` minimises
   for every leg — so the shipped `zstd`-spawn path has unit coverage only, days after that path
   was the single point of failure for the entire matrix.
7. **The live-TUI acceptance cannot run where it matters most.** It requires native Claude Code as
   a control, so it structurally cannot run on NetBSD, Mavericks, Haiku, illumos or sparc — the
   platforms whose mechanisms differ most. Evidence it matters: the fullscreen renderer works on
   macOS and CRASHES on NetBSD/arm64. A control-free variant (assert the target renders an answer
   absent from the prompt) would run anywhere credentials reach.

8. **Any gate that greps the STAGED CARVE for a quote-bearing string is silently blind.**
   Found 2026-08-29 by insisting a new pin prove itself red: it reported two walls DOWN against
   a bundle whose walls were intact, because since 2.1.243 the staged `cli.cjs` is the GRAPH
   RUNNER — module sources ride as JSON inside a JS string, so a literal like
   `switch("clode-managed-target")` is present only in escaped form. Two gates had already died
   of exactly this (`guard-subcommands-gate`'s `.command("…")` and the fs.watch alias scanner),
   so this is a CLASS, not an incident. Sweep every gate that pattern-matches a staged artifact:
   read `graph.json`, whose `sources` are real strings, or make the pattern escape-blind with a
   self-check pinning BOTH encodings. The pin in `a42bf7e` does the latter and is the worked
   example.

**Why this belongs in *** and not in a test file:** items 1-5 are properties of how the build
reports, not features of any one gate. Bolting them onto individual tests reproduces the problem
one level up — a hand-maintained list of which guards were mutation-checked, which will itself go
stale silently. See also [[instruments-lie-check-them-first]], which states the principle; this
entry is the argument that the principle needs a mechanism.


### ★★★ Out-of-tree builds must be easy AND the default (user, 2026-08-28)

**The user:** "Out of tree builds are to be easy and default."

**Measured, on this box, 2026-08-28.** The checkout lives on NFS
(`ap-juicer:/export/code/trees` -> `/Users/schmonz/Documents/shared-trees`). Same operations,
same machine, NFS vs local disk:

| operation | NFS (repo) | local | penalty |
|---|---|---|---|
| 8 MB write | 441 ms | 4 ms | 110x |
| 8 MB read | 364 ms | 2 ms | 182x |
| **300 file creates** | **39,838 ms** | 40 ms | **~1000x** |
| 300 stats | 1,368 ms | 1 ms | ~1400x |
| 300 reads | 3,071 ms | 7 ms | ~440x |

**133 ms per file create.** Bulk throughput is merely bad; METADATA operations are
catastrophic — and a build is almost entirely metadata operations. Node stats hundreds of
files per `require`, the fuse worker materializes a member tree, tests create fixtures.

**It also poisons the tree itself.** 2,913 AppleDouble `._*` files, and 513 loose git objects
because `git gc` cannot repack on this mount ([[git-gc-fails-appledouble]]) — so git gets
slower over time and never recovers.

**The part that should worry us most: it silently corrupts our PERFORMANCE WORK.** We spent
today's effort on merger timings — 398s baseline, 643s after a fix, 223s after a memo — and
treated them as CPU. Those runs read `libexec/` from NFS. Any number measured here conflates
CPU with a filesystem that is 1000x slower at the operation builds do most. We do not
currently know how much of any of those figures was I/O, which means a "regression" or a
"win" measured on this box can be neither. Same shape as
[[instruments-lie-check-them-first]], one layer lower: the instrument is the FILESYSTEM.

**The ask, and "default" is the load-bearing word.** Not a documented `CLODE_CACHE=/tmp/...`
incantation — the incantation already exists and I used it today for one build, which is
exactly why it is not enough: it protects whoever remembers it, on the runs they remember it
for. A build should place every byte it writes on local disk without being asked, and should
never write into the checkout at all. Then a shared/NFS tree stays a perfectly good place to
KEEP source (which is why it is on NFS — the user shares it across machines), and stops being
the place we BUILD.

Design notes worth carrying:
- The source tree is still READ over NFS even with scratch elsewhere; if that read cost
  matters, the build wants a local materialized copy of its inputs, not just its outputs.
- `git gc` should be made to work (or the `._*` files swept) or the repo degrades on its own.
- Once builds are out of tree by default, `bin/` holding a built binary stops being a
  contradiction — see the stage0 entry above.


### ★★★ clode is a BINARY WE BUILD, and only that — retire bin/clode as a way to run clode (user, 2026-08-28)

**The user:** "I think we confuse ourselves having bin/clode in tree and using it for some
things. Clode needs to be a binary we build and only that."

**Two entry points, and only one of them ships.** `bin/clode` is a `#!/usr/bin/env node`
script in the checkout. Every one of the 40 published assets is a fused tjs binary —
`clode-<ver>-freebsd-14.0-amd64`, `…-linux-riscv64`, `…-cosmo.com`. Users never run
`bin/clode`. But `bin/clode` is what we develop against, what most tests drive, and what the
local build loop exercises. So the artifact we reason about is not the artifact we ship.

**This is not a tidiness complaint — the two paths have DIFFERENT CAPABILITIES, so the dev
path answers capability questions wrong.** Today's proof, start to finish inside one hour:

- 2.1.251 embeds its assets as zstd frames, so carving now needs a zstd decoder.
- Under Node, `zlib.zstdDecompressSync` exists (22.15/24+). The fix looked like a version
  floor, and on the dev path it IS one — a checkout with a new-enough Node carves fine.
- Under tjs there is no zstd AT ALL. So as of 2.1.251 every shipped binary cannot carve a
  current provider — while CI, the local suite, and my own builds stay green.
- I then told the user twice, confidently and wrongly, first that the floor bump was
  user-facing and then that it was dev-only, because "clode" names two different programs
  and I was answering about whichever one I had last run.

A floor bump on the dev path is invisible to users. A missing capability in the shipped
binary is invisible to the dev path. Having both entry points is what let one hour produce
two opposite wrong answers about the same change.

**What this means concretely** (the shape, not the plan):

1. **`bin/clode` RENAMED and MOVED — the name is the bug (user, 2026-08-28).** Demoted to a
   stage-0 whose only job is producing the first binary. Leaving it called `clode` in `bin/`
   guarantees the confusion returns: `bin/` is what says "this is the program you run", and
   the name is what let one hour produce two opposite answers about one change.

   Two names are already spoken for, so do not reach for them: **bootstrap** means quaude's
   RUNTIME bootstrap (`libexec/quaude-bootstrap.mjs`), and `scripts/build-clode-main.mjs`
   already builds a different artifact, so `build-clode` reads as its sibling.

   Suggested: **`scripts/stage0.mjs`** — it cannot be mistaken for the product, collides with
   nothing, and names the property that actually matters: it exists only until a real clode
   binary does. Whatever the final name, it belongs beside the other `build-*`/`make-*` dev
   scripts, and `bin/` should hold the BUILT binary or nothing at all.

2. Tests and the local loop drive the FUSED binary. Anything that cannot is named as an
   exception with a written reason, the way divergences are.
3. `native-builder-oracle` ("the native builder BUILDS THE PRODUCT (node-free, real
   provider)") stops being one red among twenty-two and becomes the gate that decides
   whether we shipped something that works. It is the job that would have caught the zstd
   break; it was failing, and it read as ambient noise.

**This is already the recorded direction, and it has not happened.** [[node-only-as-oracle]]
(2026-08-25) says no Node in DEV either, only for oracular comparison. The gap between that
direction and today is exactly the confusion above, so this entry is evidence for a
direction already chosen rather than a new proposal.

**The tension to design against, honestly.** A fused `--self` costs real wall-clock, and a
dev loop that fuses before every check is a slower loop than the one we have — that is WHY
`bin/clode` keeps getting used. So the ask is not "delete it": it is a fast path to a fused
builder plus a hard rule about what may run the Node entry. Without the fast path, the rule
will be broken the first time someone is in a hurry, which is how we got here.

**Related, and blocked by the same confusion:** a fused clode-native cannot carve a split
provider at all today (`bun-graph.cjs` is not in the builder role's member list), which has
been true since 2.1.243 and was found only by an agent building the real thing.


### Write down the doctrine — propose a CLAUDE.md from this project's own history (user, 2026-08-25)

**The user, immediately after being told that "solve it portably" existed in the repo only
as instances:** "Maybe part of *** is to review the history of this project and propose a
CLAUDE.md with doctrine like I assumed we had here."

**The premise is exactly right, and today produced three independent proofs of it.** This
repo HAS doctrine. It is real, it is load-bearing, and it is enforced BY EXAMPLE rather
than stated as a property — so it does not fire when it should:

1. **Solve it portably.** Written twice as instances (`bun-shim.cjs:617` "translates rg to
   portable applets ON PURPOSE"; `gen-node-constants.mjs:101` "THE NAME LISTS ARE STATIC ON
   PURPOSE. DO NOT RE-DERIVE THEM FROM THE RUNNING HOST"), generalised never. Cost: a
   provider-minimising step that ran on three legs through two call sites with opposite
   failure policies, discovered three hours into the slowest job in the matrix.
2. **If we ship it, CI gates it.** Enforced by a test that checked two hardcoded leg names.
   Cost: `linux-s390x-musl` published but never CI-built, and eleven others like it.
3. **Every release OS is exercised.** Enforced by a test that exempts openindiana BY NAME.

Each was found the same way: something broke, and the rule that would have prevented it
turned out to be present in the codebase as a comment on one line of one file.

**What the task actually is.** Not "write a style guide" — mine the history and state the
properties that are already true, with the evidence that made them true. The material is
sitting in ~1,150 commits, in BACKLOG.md, and in the session memory files. Candidates
already evidenced, each with a real incident behind it:

- CI's job is to tell the truth, not to be green. Red is a to-do trigger; ask of every
  check "does GREEN hide an outstanding action?"
- Any CI red is our red. "Pre-existing" and "not mine" are not dispositions.
- One implementation, every platform. A per-platform branch needs a written reason, and
  the reason must be about the platform, not about who noticed the bug there.
- Failure policy is part of the implementation. Two call sites disagreeing about whether
  an error matters is the same defect as two implementations.
- Instruments lie — check the measuring device before the product.
- Every fix lands with the mechanism that would have made it cheap to notice.
- Derive, never declare: dependency lists, constants, module lists come from a source of
  truth, not from a hand-maintained copy.
- Build fresh for fidelity; warm dev-box state hides defects.
- A rule enforced by example WILL rot. State the property, then gate the property.

**Two hazards, both worth stating in the file itself.**

*It must not become a second place where facts live.* The value is in properties that
CANNOT be expressed as a test (judgement, sequencing, what to do when red). Anything that
CAN be gated should be gated, with CLAUDE.md pointing at the gate rather than restating
it — otherwise it drifts, and a drifted CLAUDE.md is worse than none.

*The evidence is the payload.* "Solve it portably" alone reads as a platitude and gets
skipped; "solve it portably — here is the three-hour sparc red that came from not doing
it" is a rule that changes behaviour. Every entry carries its incident.

**Sequenced with the rest of ★★★ deliberately**, because the overhaul is where several of
these rules get their first real gate — writing the doctrine and building the mechanisms
that enforce it should be the same pass, or the file is aspirational on the day it lands.


### No special cases: one path, applied equally (user, 2026-08-25)

**The user, on learning netbsd-sparc had its own provider-minimising step:** "I didn't
realize sparc was a special case. Whatever we do for sparc should then be applied equally
everywhere else."

**What the special case cost.** `scripts/make-min-provider.cjs` shrinks a provider so the
sun4m guest (512MB, TCG) can build at all. When upstream went code-split it was not
updated with the extractor, and the failure surfaced as a red netbsd-sparc — a PUBLISHING,
hard-gated leg — roughly three hours into the slowest job in the matrix, after twelve
other legs had already gone green. A break in shared code would have shown up in minutes.

**And it is worse than "only sparc uses it": the two call sites disagree.**

    build-leg:689   `... make-min-provider ... 2>/dev/null; then`   failure SWALLOWED
    build-leg:728   bare call                                       failure FATAL

So the identical breakage is invisible at one site and fatal at the other. That is not a
special case, it is two different policies for one script, and nothing said which was
intended.

**Fixed now:** the script handles both bundle shapes, and `test/make-min-provider.test.cjs`
pins the contract for each — same shape in and out, byte-identical entry/graph content,
idempotent, and a loud refusal on a non-provider. It can no longer rot unnoticed
regardless of which legs call it.

**MECHANISM BUILT (2026-08-25): `scripts/stage-provider.mjs`.** One choke point that
resolves the platform-correct provider and minimises it, so every leg that BUILDS gets the
same treatment on every platform. Verified end to end: resolve -> 36MB -> `clode build` ->
PONG + attest. It distinguishes the two failure modes the old code conflated ("no provider
resolved" vs "resolved one and could not minimise it"), and neither is silent.

**The ONE declared exception is about PURPOSE, not platform.** Anything that INSPECTS a
bundle must use the real binary, because the minimiser drops exactly what inspection
reports on — measured: real provider `embedded_assets=16, napi=8`; minimised `0, 0`. So
`upstream-drift-check` and `inspect-claude-bundle` keep calling `find-provider.mjs`
directly. Building from a bundle and asking questions about it are different jobs.

**NOT YET WIRED, deliberately, and this is a sequencing call not a scoping one.** There
are 21 build-path call sites of `find-provider.mjs` across `build-leg`, `ci.yml` and
`naude-cross.yml`. Replacing them is mechanical but touches EVERY leg's provider staging,
and it should land as one change rather than a partial one — a half-applied uniformity
rule is just a new set of special cases. It is queued behind the release, which at time of
writing is one job from a verdict.

**Still open, and it is the user's point:**

1. **Unify the two call sites.** Pick one policy deliberately — either minimising is
   required and its failure is fatal everywhere, or it is an optimisation whose failure
   falls back to the full provider everywhere. Today it is both, by accident.
2. **Decide whether ALL legs should minimise.** The obvious argument is uniformity: one
   path, exercised everywhere, so a break appears on a fast leg in minutes rather than on
   the slowest leg in hours. There is a real counter-argument to weigh, not dismiss — if
   every leg builds from a MINIMISED provider, nothing in CI ever builds from a real
   upstream binary, and that is a fidelity axis we would be dropping. A defensible answer
   might be "minimise everywhere except one named leg that deliberately uses the real
   thing", which is still one policy with one declared exception rather than an accident.
3. **Audit for other single-leg paths.** This one was found by tripping over it. Whatever
   else only one leg does is equally able to rot for three hours before anyone hears.

**The general rule this belongs to:** a code path exercised by exactly one leg is tested
at that leg's cadence, which for the emulated legs means hours per attempt and days per
fix. Sharing the path is not just tidiness; it is the difference between a minutes-long
feedback loop and an hours-long one.

### ★★★ Borrow someone else's test corpus for both shims (user, 2026-08-25)

**The user:** "'Bun-on-Node shim with node's own test corpus behind it' sounds awesome."

**The insight is that the valuable asset is the CORPUS, not the shim code.** We implement
each shim member when something notices we need it; correctness per member is then
whatever we happened to think of. Node ships thousands of tests for exactly these APIs,
written by people who cared about the edges.

**PROVEN IN TEN MINUTES, and the result is the argument.** Fetched ONE file —
`nodejs/node test/parallel/test-path-basename.js`, 76 lines — wrote a ~15-line stub for
`require('../common')`, and ran it against our shim on the engine. It found **three
separate bugs in `path.basename`**:

    basename('.js', '.js')         gave '.js'   node: ''      (ext === whole path)
    basename('aaa/bbb', 'bbb')     gave ''      node: 'bbb'   (ext === basename only)
    win32.basename('a', 'a')       gave 'a'     node: ''      (posix fix missed win32)

The middle one is there because MY FIRST FIX WAS WRONG — I stripped whenever the basename
matched, and node's own test caught that too, immediately. All three are now fixed.

**Our own `test/node-shim-path.test.cjs` was GREEN the entire time**, all 10 tests, before
and after. That is the whole case in one sentence: our tests encode what we thought of;
node's encode what is true.

**Why this is different from the "18 members missing" measurement** (see the shim-surface
golden inventory): that counts PRESENCE. Every bug found on 2026-08-25 — deepStrictEqual
approving unequal values, fs discarding a mode it accepted, Buffer.indexOf returning -1,
these three basename cases — was in an API that was PRESENT AND WRONG. A shim judged
complete by member count would ship all of them. **The metric we want is corpus pass rate
per module, not member coverage.**

**The two layers are NOT symmetric, and the plan should say so:**

- **Layer 2 (node-on-txiki): node's own corpus, and it is enormous.** `test/parallel/` is
  MIT-licensed, self-contained per file, and mostly needs only `assert` plus the module
  under test. The single real dependency is `test/common`, and a stub covering
  `mustCall`/`mustNotCall`/`isWindows`/`skip` unlocked the first file outright. Highest
  value, lowest effort, start here.
- **Layer 1 (bun-on-node): the analog is Bun's own tests, and it is a worse fit.** They
  use `bun:test` and assume the Bun runtime, and we implement ~25 Bun members of which
  most of Bun's suite never touches. Likely worth hand-porting the tests for the members
  we DO implement rather than adopting the suite wholesale.

**Constraints:** vendoring test FIXTURES is compatible with zero-dependency and
Node-absent — tests are not shipped, and the corpus is MIT. Pin the corpus to a node
version and record which, so "we pass node 24's path tests" is a dated, checkable claim
rather than a vibe. Expect to find bugs faster than we can fix them; that is a reason to
land it, and a reason to gate on a per-module ratchet (pass count must not fall) rather
than requiring 100% on day one.

**Sequencing:** it needs the engine-test harness from the feasibility spike, so it lands
after that. Same doctrine applies — the `common` stub must supply plumbing ONLY; anything
it supplies that the shim should have is a finding, not a hole to fill.

### Revisit the shims: named, organized, parallel, maintainable (user, 2026-08-25)

**The user:** "We shim Bun onto Node and Node onto QuickJS-NG/Txiki and both of those are
valuable layers to keep distinct for as long as we want to be able to do oracle testing
against Claude-on-Node ('naude'), which is probably for as long as this project exists."

**The layering, and why the split is load-bearing:**

    quaude   Claude (Bun-built)  ->  bun-shim  ->  node API  ->  node-shim  ->  txiki/quickjs
    naude    Claude (Bun-built)  ->  bun-shim  ->  REAL NODE

`bun-shim` is shared by both products; `node-shim` exists only under quaude. THAT is what
makes naude an oracle: a divergence seen in quaude but not naude is isolated to the
node-on-quickjs layer. Collapsing the two shims would destroy the differential.

**Confirmed, not assumed:** `scripts/build-naude.mjs:227` bakes the bun-shim from the SAME
staged location quaude reads, deliberately ("never one reached back for from the repo").
So the invariant holds today — by construction, but not by assertion.

**The asymmetry, measured 2026-08-25:**

    bun-shim     1 file    1,386 lines     3 test files
    node-shim   39 files   8,636 lines    ~70 test files, wall tripwires,
                                          API-surface gate, fidelity goldens,
                                          test/shim-surface/ with committed goldens

Same KIND of job, organized completely differently. node-shim is one module per node
builtin plus a loader; bun-shim is a single file. node-shim has machinery for declaring
and gating its surface; bun-shim has almost none.

**Their declared surfaces are different shapes, too:**

    bun-shim    const PROVIDES = { bunBuiltins: [...], hostModules: [...] }   structured
                literal, read as TEXT by the dep-closure gate
    node-shim   const KNOWN = ['assert','buffer',...]                          a bare array
                inside loader.cjs

**Why this matters, with today's evidence.** `util/types` was missing from `KNOWN` and we
found out because a 2.1.245 build DIED — not because anything declared a gap. And
`util.types` turned out to be `{ isDate }` alone, so `isProxy` was silently absent. Two
gaps in one builtin, both discovered by a failing build rather than by a surface that
knows what it claims to provide.

**What "parallel" should probably mean (to decide, not presumed):**

1. **One organizing shape.** If per-module files are right for node-shim at 8.6k lines,
   they are right for bun-shim as it grows — and bun-shim is where the least machinery
   is pointed today.
2. **One way to declare a surface**, machine-readable for both, so "what do we claim to
   provide" and "what does the bundle actually use" can be diffed for either layer. The
   node-shim API-surface gate already does this for one side.
3. **One wall convention.** node-shim has named-throwing walls and tripwires; bun-shim's
   equivalents are ad hoc. A wall should look the same in both layers and fire on USE.
4. **The naming is already right and should be preserved deliberately:** both are named
   for what they PROVIDE (bun-shim provides Bun; node-shim provides Node), not for what
   they run on. A future rename could easily flip one and make the pair incoherent.
5. **Assert the oracle invariant** rather than relying on build-naude reading the right
   path: naude must contain bun-shim and must NOT contain node-shim. If that ever stops
   being true, every naude-vs-quaude differential silently stops meaning what we think.

**Related:** the shim tests do not run on the engine (filed separately) — which bites
node-shim hardest, since it is the layer that only exists there.

### Revisit the CLI and subcommands (user, 2026-08-25)

**The user:** "let's revisit the clode CLI and subcommands, given how we build quaude by
default and also naude, and how building is mostly all that clode does".

**The surface today, measured:**

    subcommands   build   fetch   watch        (+ --help, --version)
    flags         --out  --naude  --target  --self  --verbose

**The tell is in clode's own help text:**

    clode build --naude --target Y   cross-build a naude for macos/linux/windows ...
                                     anything else: plain --target builds a quaude instead

`--target` means something different depending on whether `--naude` is present, and the
help has to explain the fallthrough. That is what conflated axes look like from outside.

**What is actually being expressed is a small matrix on an ad-hoc flag surface.** There
are THREE products —

    quaude          the default: engine + compiled Claude Code
    naude           --naude: a Node SEA, Node hosts only
    clode itself    --self: the standalone native builder

— crossed with ONE platform axis (`--target`), and the two are not orthogonal today.

**And "building is mostly all clode does" is literally true of the verb list.** `fetch`
obtains the upstream provider (a prerequisite), `watch` runs one update-signal check (a
notification). Neither is a peer of `build`; both exist in service of it.

**Options to weigh, none decided:**

1. `clode build <product> [--target P]` — product as a positional, platform orthogonal.
   Says what it builds, and `--target` finally means one thing.
2. `clode` with no arguments builds a quaude for this machine, since that is the common
   case; everything else is explicit.
3. Keep `build` but make the product a real flag family and orthogonalise `--target`.
4. Fold `fetch` and `watch` into a shape that says they are about the PROVIDER, not the
   build — e.g. `clode provider fetch` / `clode provider check`.

**Two constraints the redesign inherits:**

- **The env-var review is the same conversation.** 51 CLODE_* names are read by shipped
  code and 0 are documented, against 4 flags. If building is what clode does, its inputs
  belong on the command line — so whatever the CLI becomes should absorb the knobs that
  survive that review rather than leaving two parallel input systems.
- **The domain-language item lands here too.** "fuse" appears in user-visible strings;
  whatever the CLI says should already speak the new vocabulary rather than being renamed
  twice.

**Sequencing:** after the release. This is a breaking surface change, and it wants to
happen once, with the vocabulary and the surviving knobs already decided.

### Domain language: stop saying "fuse" (user, 2026-08-25)

**The user:** "You keep saying 'fused' like it means something to me because the code
apparently says 'fuse'. I've learned what you mean by it but I want to change the code
language and your language when talking about it."

**The earlier half-measure was wrong, and the user said so plainly.** A prior note had it
as: use build language in specs/docs/messages, leave the fuse symbols in code "until a
deliberate rename", and map between them. When I apologised for letting the code word leak
into conversation, the user rejected the whole framing:

> "No, the code convention absolutely should leak into the conversation. It's the code
> convention that I want to change, not specific rules for how you talk about this
> particular code."

That is right, and it is the same principle as the rest of this overhaul: a translation
layer between the code's vocabulary and the humans' is a fact stored in two places, and
somebody has to maintain the mapping. **There is no conversational half to fix — there is
only the rename.** Until it lands, speaking the code's word when discussing the code is
correct; the mismatch is the bug and should stay visible.

**Scope, measured 2026-08-25:**

    145  files mention "fuse"
      8  files whose NAME says fuse (clode-fuse.cjs, quaude-fuse.js,
         cross-fuse/action.yml, four tests, one Dockerfile)
     ~11  user-visible strings printed to stdout/stderr

    heaviest: libexec/clode-fuse.cjs 86 · build-leg/action.yml 45 · quaude-fuse.js 35

**THE TRAP: "fuse" names TWO different operations, and a find-replace would flatten them.**

1. the WHOLE act of producing a quaude — extract, transform, compile, assemble, smoke.
   That is what `clode build` already calls itself, and what a user means.
2. the SPECIFIC step of appending the member archive to an engine binary. Today that is
   also "fuse" (`quaude-fuse.js` does exactly this and nothing else).

Renaming (1) to "build" while leaving (2) unnamed would lose a distinction the code
genuinely needs. So the rename has to introduce a word, not just remove one.

**Proposed vocabulary — the user picks, this is a starting point:**

| today | proposed | why |
|---|---|---|
| fuse (whole) | **build** | matches the command and the user's mental model |
| fused (adj.) | **built** | "a built quaude", not "a fused quaude" |
| cross-fuse | **cross-build** | same, and `--target` already says it |
| fuse (append step) | **assemble** or **pack** | needs its own word; it is a real, distinct operation |
| `libexec/clode-fuse.cjs` | `clode-build.cjs` | |
| `libexec/quaude-fuse.js` | `quaude-assemble.js` | it appends the archive; that is all it does |

**Why this belongs to ★★★ and not a tidy-up pile:** the overhaul's goal is that one place
answers a question and the answer is legible. A word that has to be LEARNED before the
build makes sense is the same tax as a fact stored in two places — it just gets paid by
the reader instead of the maintainer. And the giveaway that it is genuinely confusing is
that it names two operations at once.

**Sequencing:** after the release, and probably alongside whatever moves
`clode-fuse.cjs`/`quaude-fuse.js` anyway (the second-half language question). Renaming
files twice would be worse than renaming them once, later.

**THE MAP:** <https://claude.ai/code/artifact/d5ecba30-da4f-4f61-a83e-f310bac959af>
— "clode build system — a map before moving", the zeroth deliverable. Measured from the
tree on 2026-08-21: the two-pipeline diagram, which stages are compilation concerns
versus orchestration, the four original arguments for migrating and which of them have
since been closed INSIDE the existing script, and the constraints any plan must respect
(canonical-LE is load-bearing; patch order is enforced; `clode build` must work with Node
absent; vendor off NFS but not reapable; ccache belongs to this work, not before it).
Read it before touching this item — everything below is a delta on it.

**One thing to reconcile, and it is on-topic for this overhaul.** The map says
`CLODE_* knobs: 25 (7 documented)`. Counting on 2026-08-25 gave 116 distinct CLODE_*
names, 51 read by SHIPPED code (libexec + bin), and 0 documented in clode's usage text.
Both numbers are probably honest under different definitions — "knobs a user might set"
versus "environment names the code reads" — but nobody can tell which from either
artifact, and that is the disease: two measurements of the same thing, no single place
that answers it. Whatever the env-var review decides, it should leave ONE count that is
derived rather than asserted.

### ★★ Anchors exist TWICE, by hand (2026-08-25)

    libexec/extract-claude-js.cjs      17 anchor definitions
    libexec/inspect-claude-bundle.cjs  18 hand-written MIRRORS

The mirroring is documented in inspect's own comments — "a VERBATIM mirror of
extract-claude-js.cjs's SNAPSHOT_GEN", "in lockstep with extract-claude-js.cjs". Lockstep
maintained by discipline is lockstep that breaks: `snapshotGeneratorPresent` gated on a
SUBSTRING NEAR the anchor rather than the anchor, and reported the site healthy for three
releases while the hook was dead.

One definition, two consumers. Whether that is a shared module or a shared library is the
same question as the second-half language note; the duplication is a defect either way,
and it is the cleanest single example of the duplicated-truth problem ★★★ exists to fix.

### ★★ The shim tests do not run on the engine (2026-08-25)

**PROVEN, and it paid immediately.** A feasibility spike ran the suite on the engine and
found SIX genuine shim bugs plus two product bugs that node-hosted testing had been
hiding. All eight are now FIXED (see git log for 2026-08-25); the spike's harness is NOT
yet integrated.

    C1  fs dropped the CREATE MODE            writeFileSync/openSync/appendFileSync gave
                                              0644 for {mode:0o755}. The SIBLING of the
                                              cpSync bug found in the field — that fix
                                              covered copyFileSync and never the create
                                              path. promises.writeFile also dropped opts
                                              ENTIRELY (encoding as well as mode).
    C2  deepStrictEqual APPROVED UNEQUAL      Map/Set/Date/RegExp/boxed/typed arrays keep
        VALUES                                contents in internal slots; it walked
                                              ownKeys only, so both sides looked like {}.
                                              assert.deepStrictEqual delegates to it.
    C3  crypto.randomBytes threw above 64KB   WebCrypto caps getRandomValues at 65536;
                                              node has no cap. Now chunked.
    C4  os.networkInterfaces returned an       node keys by interface name. The existing
        ARRAY                                 test asserted `typeof === 'object'`, which
                                              an array satisfies — green, wrong shape.
    C5  util.inspect was JSON.stringify       Errors printed as '{}', and it THREW on
                                              circular objects and BigInt. Since it backs
                                              console.log, an error logged during a
                                              failure vanished exactly when needed.
    C6  buffer-lite搜索 silently wrong         Uint8Array.indexOf coerces a string needle
                                              to NaN, so indexOf('cab') was -1 and
                                              includes() false. concat ignored
                                              totalLength; no toJSON.
    C7  clode-watch spawned process.execPath  Under a fused clode that is the clode
        (PRODUCT bug)                         binary; the spawn failed, was swallowed, and
                                              HIGH update signals became high=0. The
                                              identical trap is documented at
                                              clode-fuse.cjs:294.
    C8  platform-tag emitted an EMPTY FLOOR   os.release() is '' under a node-free clode,
        (PRODUCT bug)                         so non-darwin/linux/win32 produced `netbsd-`
                                              silently. Now walls.

**C5 is a partial fix, deliberately.** util.inspect is not node-exact: no colours, no
depth/breadth options, no getter evaluation, spacing differs. What it now guarantees is
that it NEVER THROWS and never returns '{}' for a value with content. Widen it when a
caller needs more, not speculatively.

### ★★ Finish the engine-test migration (2026-08-25)

The spike above proves the approach; the harness is uncommitted in an agent worktree. What
it established, measured:

- **A node:test-shaped harness is enough.** The suite uses `test(name[,opts],fn)`,
  `t.skip()`, `t.diagnostic()` and nothing else — ZERO files use `describe`, `it`,
  `t.plan`, subtests, `mock` or reporters.
- **Full sweep, 199 files unmodified on the engine: 90 pass / 106 fail / 3 hang.** That is
  a FLOOR — the spike's worktree had no `build/` and no `deps/claude/node_modules`.
- Rough shape: ~45-55% run as-is; ~20% need one mechanical change, almost always
  replacing `process.execPath` with an injected node (`CLODE_NODE`) — and many files
  already have that seam; ~10% need loader work (`.mjs` requires,
  `createRequire(import.meta.url)`); ~15-20% should STAY on node as the oracle (PTY,
  SEA/naude legs, fidelity differentials that already drive the engine as a subject).

**THE DESIGN CONSTRAINT TO DECIDE FIRST: it must run in TWO LABELLED CONFIGURATIONS.**
With `NODE_PATH` unset you are testing the clode-native toolchain (`buffer-lite`); pointed
at the ext-dep closure you are testing what quaude ships (feross/buffer). C6 exists ONLY
in the first, and the spike nearly reported it as a general Buffer catastrophe before
checking. A migration that runs one leg will confidently mislead about the other.

**Anti-flattery requirement, non-negotiable:** the harness must supply `test`/`assert`
plumbing and NOTHING else. The spike validated this by sabotaging `path.join` and watching
the shim test go red while a pure-JS control stayed green. Any future harness change
should be checked the same way — a harness that stubs enough to pass reproduces the exact
defect this work removes.

### ★★ s390x ATTEMPTS the cross-fuse onto big-endian and throws the result away

The `linux-s390x-musl` leg's `verify: qemu-user` does a "level-2.5 full fuse
attempted+logged". That is exactly the operation canonical-LE exists to make safe — an
LE host producing bytecode a BE target must load — and its outcome is LOGGED, NOT
ASSERTED. The leg is also `soft-fail: true` and release-tier only, so it never runs on
push.

Making that assertion real would turn the project's largest untested property into a
five-minute signal. Related: the matrix note above (published-but-ungated legs) and the
canonical-LE risk below.

### ★★ canonical-LE is knowingly incomplete, and the code-split path multiplies the risk

`test/fixtures/bc-le-baseline.json`, measured with both engines from one release build
(s390x under qemu-user):

    stress(inline)                        identical
    build/bundle/clode-main.bundle.cjs    differs
    libexec/node-shim/loader.cjs          differs      <- "the known regexp wall"

Synthetic corpora match byte-for-byte; REAL files diverge from offset 1, because
libregexp stores compiled regexps in host byte order. Tracked as a ratchet rather than
failing the release, deliberately.

### MEASURED 2026-08-26 — ROUNDING ERROR, leave it. (was: does the BE regexp mitigation cost real time?)

**ANSWERED. ~0.2% of CPU in every workload measured, and it does not grow with session
length.** The mitigation stays as it is; the optimisation below is recorded as available,
not needed.

**Mechanism, from the patch:** `OP_regexp` calls `js_re_recompile_le()` under `is_be()`,
which does `JS_ToCStringLen2(pattern)` + `lre_compile()` + an alloc, and never writes back
to the cpool — so a literal inside a function recompiles on EVERY evaluation. Its
structural discriminator makes freshly-parsed literals free, which is irrelevant to
quaude: the loader runs `cli.qbc`/`graph.qbc` through `evalBytecode`, so on a BE target
every literal in the bundle is LE-deserialized and recompiles.

**Method.** Instrumented the off-repo vendor quickjs with an `OP_regexp` counter, a
distinct-pattern set, a `CLOCK_MONOTONIC` accumulator, and `CLODE_RE_FORCE=1` to perform
the identical recompile work on this LE box. Instrument validated against the wall clock
before use ([[instruments-lie-check-them-first]]): 100,007 evaluations — instrument
824.5 ms, wall-clock delta 820 ms, agreeing to 0.6%.

**Measured (darwin-arm64, recompile forced):**

    workload                          OP_regexp   distinct   recompile
    --version boot (2.1.218)              2,805         72      2.00 ms
    1 mock agentic Bash turn             12,505        957   15.0-21.1 ms
    15 mock agentic Bash turns           38,588        957   54.5-56.5 ms
    --version boot (2.1.246, 53MB)        3,270         72      2.18 ms
    1 / 15 turns (2.1.246)         18,852/49,601  1,278/1,278  37.6/71.8 ms
    TUI boot + trust (real PTY)          18,432      1,022     22.1 ms
    + 400 keystrokes (~46s)             182,272      1,025    104.3 ms  (~0.21 ms/key)
    TUI idle, 120s                     +216 evals   1,022 (flat)  +0.50 ms

Per-recompile: 0.7-2.0 µs for real bundle patterns. A/B wall-clock on a whole boot is
BELOW THE RESOLUTION OF `time` (2.1.218 off 3.43s / on 3.43s).

**Two findings that matter more than the percentage:**

1. **The cost does not grow with session length.** Distinct patterns are FLAT — 957 at
   turn 1 and 957 at turn 15, 1,278 and 1,278 on 2.1.246, 1,022 -> 1,025 across 400
   keystrokes. Every marginal cost is recompiling a pattern already seen.
2. **The code-split fear did not materialise.** 2.1.218 -> 2.1.246 is 2.5x the bundle
   (20MB -> 53MB) but only 1.17x the boot evaluations and the SAME 72 distinct boot
   patterns. 20,000 lines of tool output added 80 evaluations — there is no
   per-line/per-token literal in the hot path. That was the specific worry when this was
   filed, and it is retired.

**Derived for Tiger PPC** (40x from [[tiger-ppc-quaude-perf]]; percentages carry because
numerator and denominator are the same slow CPU): ~90 ms added to a ~40,000 ms boot,
~95 ms per tool turn, ~8 ms per keystroke, ~0.17 ms per idle second.

**NOT MEASURED, stated plainly:** no BE run — the Tiger guest was down (ssh refused) and
ultimate-hat's docker context timed out, killing the qemu-s390x route. And the corpus was
an extracted 53MB CJS rather than a real `graph.qbc`; the same JS executes, but that was
not confirmed on a built quaude. Cheapest confirmation when a rig returns: `gh run
download` the s390x tjs artifact, run the same instrumented count under
`qemu-s390x-static`, compare `recompile_ns` against an LE control.

**If ever optimised**, the headroom is real and the prize is small: caching by pattern
cuts boot from 3,270 to 72 compiles (-98%) and a 15-turn session from 49,601 to 1,278
(-97%) — about 88 ms at boot and 2.8 s per long session on Tiger.

**Superseded framing kept for the record:** — the fix
is known and cheap if the numbers justify it, and unnecessary if they do not. It sat
un-headed inside this section for a day, which is why it is being given its own heading:
a to-do that `grep '^## '` cannot find is not tracked, it is stored.

**AND THE COST FALLS ON THE WRONG PLATFORMS (user, 2026-08-25): "I would hope that we
wouldn't punish platforms that are already slow."** The mitigation is a runtime
RECOMPILE at every `OP_regexp` — i.e. every time a regex LITERAL is evaluated — and it
fires only when `is_be()`. So little-endian hosts pay nothing and the entire cost lands on
m68k, sgimips, macppc, hppa and sparc: the oldest and/or emulated targets. That is a
performance regression aimed precisely at the machines with the least headroom, and the
code-split bundle multiplies the number of literals involved.

Correctness is not the worry here; the pattern string is endian-neutral, so recompiling
from it is right by construction. **The worry is that BE targets get slow rather than
wrong**, and slowly enough that nobody notices it as a regression.

**The fix is local and cheap if it bites:** cache the recompiled blob keyed by the
pattern (a literal's pattern never changes), or hoist to compile-once-per-module, both
inside the same opcode. Neither touches serialization or canonical-LE. Measure before
building: a BE leg that reports startup and a PONG turn's wall-clock would say whether
this is a real cost or a rounding error.

**Why this got sharper on 2026-08-25:** the sparc leg is CROSS-FUSED from x64, so an LE
host's bytecode must load on a BE target. Until now that meant one CJS blob. It now means
**1,459 ESM modules and 41MB of bytecode**, and those modules are dense with regex
literals — the exact construct behind the known wall, multiplied by three orders of
magnitude. Whether it bites is unknown: the modules may carry regexps that recompile
cleanly on read, which is what canonical-LE was for. Nothing green today can see it.

### ★ tjs_evalBytecode over-consumes its argument (SIGABRT at teardown)

`src/mod_engine.c:148` does `JSValue obj = argv[0]` and hands it to `JS_EvalFunction`,
which CONSUMES it, while the caller still owns `argv[0]`. Refcount underflow, symbolicated:

    abort <- js_free_value_rt <- free_var_ref <- js_bytecode_function_finalizer
          <- free_gc_object <- JS_RunGC <- JS_FreeRuntime <- TJS_FreeRuntime <- main

Pre-existing, not from the import.meta work — `compile()` + `evalBytecode()` of
`globalThis.__D = 42;` aborts identically on both engines. **quaude is unaffected** (the
deserialize path exits 0), so this is not urgent; but any stock user of
`tjs.engine.compile` + `evalBytecode` crashes at exit, and a test harness that checks exit
codes would see 134 for a run that succeeded.

### ★★ Rationalize the push-CI and tag-release matrices (user, 2026-08-25)

**The user's reaction on learning `linux-s390x-musl` is released but not in CI:** "I keep
being surprised at the ways our push-to-build and tag-to-release matrices are different.
That needs to get rationalized so it's hard to diverge by mistake."

Measured the same day:

    ci-tier legs        28
    release-tier legs   42
    PUBLISHED legs      35
    PUBLISHED but NOT in the ci tier   11

The eleven we ship without per-push gating:

    linux-s390x-musl        <- BIG-ENDIAN
    linux-x86-musl          <- 32-bit
    linux-armv7-musl        <- 32-bit
    linux-arm64-musl        linux-ppc64le-musl      linux-riscv64-musl
    linux-loongarch64-musl  netbsd-arm64            freebsd-arm64
    openbsd-arm64           openindiana-amd64

**This is why we have no big-endian or 32-bit signal.** Every leg that would exercise
those properties is either unpublished-and-untested or published-and-untested. On
2026-08-25 the entire BE/32-bit answer for the code-split release sat behind the SLOWEST
emulated NetBSD legs, while a 5-minute qemu-user s390x leg existed and simply did not run.

**The invariant already exists — as prose, enforced by example.** `test/tjs-legs.test.cjs`
asserts "if we ship it, CI gates it", but only inside a loop over TWO HARDCODED NAMES:

    for (const name of ['netbsd-m68k', 'netbsd-sparc64']) {
      ...
      assert.strictEqual(l['soft-fail'], undefined,
        `${name} publishes, so CI must gate it (if we ship it, CI gates it)`);

So the rule is stated, believed, and checked for 2 of 35 published legs. That is the same
shape as every instrument failure of 2026-08-25: a check that looks ADJACENT to the
property instead of AT it.

**The cheap fix, and it is a property not a list:** every leg with `publish` must be in
the ci tier and must not be `soft-fail`. Any exception carries a written, dated reason in
the manifest — the same shape as EXPECTED in upstream-drift-check.mjs, where an
undeclared entry is an error rather than a silence.

**The real decision behind it, which is the user's to make:** adding 11 legs to per-push
CI costs runner time (they are qemu-user and VM legs). The honest options are

1. gate them — pay the runner time;
2. stop publishing the ones we will not gate — ship less, honestly;
3. keep publishing with a recorded, dated reason per leg — but then the reason must live
   in the manifest and be asserted, not be an accident of two tiers drifting.

Any of the three is defensible. What is not defensible is the current state, where the
difference between "what we build on push" and "what we ship on tag" is discoverable only
by diffing two tiers by hand.

**Related and already actionable:** s390x's leg does a "level-2.5 full fuse
attempted+logged" — it ATTEMPTS the exact cross-fuse-onto-BE that canonical-LE exists to
make safe, and throws the result away. Making that assertion real, and promoting the leg
to ci, would turn the project's largest untested property into a 5-minute signal. See
also the canonical-LE baseline, which records `differs` for real files (the regexp wall)
while synthetic corpora match.

### The tests under a CMake/CTest build (design discussion, 2026-08-25 — not decided)

Companion to the "what language is the SECOND half" note below: same decision seen from
the test side. Measured composition:

    199  test files
    112  spawn a real binary (integration)
     87  pure unit tests, no spawn
     14  use node as an ORACLE (compare against node's own behaviour)
     38  `shell: bash` steps across ci.yml + build-leg   <- the Windows problem

**Which MUST stay JavaScript — only two categories, both smaller than they look:**

1. The 14 oracle tests. Node IS the subject; that is the sanctioned Node use under
   [[node-only-as-oracle]].
2. Anything asserting shim behaviour under the engine.

**And (2) exposes something worth fixing regardless of any language decision:** those
tests mostly do NOT run under the engine today. `npm test` is node:test, so the shim is
`require`d into NODE. That exercises the shim's logic and says nothing about its behaviour
on quickjs — which is where it ships. The Haiku "SIGKILLed child reported as exit 0" bug
and the Haiku write deadlock were both found by clode RUNNING ON THE ENGINE, not by these
tests. **Running the existing suite under the engine is worth more than rewriting any of
it in C**, and it is the step that makes correctness observable in the environment that
ships.

**Which could be C:** the byte-level ones — bun-graph decode, archive format and attest,
sha256, tar KAT, canonical-LE bytecode equivalence — plus the anchors-and-splices tests
if the anchors move. The principle that scales: **a test follows its subject.**

**The 112 integration tests are language-agnostic.** They spawn a binary and assert on
output and exit code, which is already the CTest model.

**Shell that must also run on Windows.** This is where CMake earns its place, and it is
not CTest specifically — it is `cmake -E` (portable copy, compare_files, rm, tar, env)
and `cmake -P` script mode. The 38 bash steps become CMake scripts that run identically
on Windows, instead of today's dependence on bash being present on the runner.

**Would CTest run them well? Yes — and four of its properties map onto bugs from
2026-08-25:**

| CTest property | the bug it would have prevented |
|---|---|
| `ENVIRONMENT` per test | an exported `CLODE_CLAUDE_BIN` leaking into a later test run |
| `SKIP_RETURN_CODE` | "60 skipped" being uninformative; skips become reported WITH REASONS |
| `RESOURCE_LOCK` | tests sharing the vendor tree / provider store contaminating each other |
| `FIXTURES_SETUP` / `FIXTURES_REQUIRED` | build one quaude, run N assertions against it, instead of depending on ambient state |

**Honest weakness:** CTest's assertion model is coarse — exit code plus output regex — so
rich per-assertion reporting must come from the test binary. For 87 unit tests with many
assertions each, node:test reports better. The answer is NOT to atomize: register a
node:test file as ONE ctest entry, not one per assertion.

**Incremental path:**

1. **CTest becomes the front door now**, wrapping suites as they are. Zero rewriting, and
   it immediately buys per-test environment, labels, timeouts, resource locks and real
   skip reporting — several of which are direct answers to the coverage-that-turns-on-
   and-off problem recorded above.
2. Run the suite under the ENGINE, not node. Highest-value step, independent of language.
3. Tests migrate by subject as their code does.
4. Replace the 38 bash steps with `cmake -P` at whatever pace suits.

### What language is the SECOND half? (design discussion, 2026-08-25 — not decided)

The build has two halves that get conflated because one command runs both. Building the
ENGINE is a C compile: patch a pinned txiki checkout, fix up portability bugs, regenerate
bytecode, CMake, verify. Building a QUAUDE is not a compile at all — it extracts the
Claude Code bundle, appends it to an engine as a trailer, and smoke-tests the result.
Only the first half is a natural CMake candidate. The second is data handling that
happens to be written in JavaScript.

**The question (user):** greenfield, with CMake in mind, what else might the second half
be? Could it be C? Would that serve cross-quaude and the no-Node-in-dev goal? What are
the payoffs, and how would we move incrementally?

**Measured composition (2026-08-25):**

    extract-claude-js.cjs   1062 lines   68 anchor/regex sites
    clode-fuse.cjs          1587
    bun-graph-plan.cjs       220
    bun-graph.cjs            189
    bundle-carve.cjs          38

    node builtins across the graph/extract path:  node:fs x2, url x2

**FIRST CORRECTION TO THE PREMISE: the second half is already Node-free.** It runs under
our own engine — that is what `clode build --self` producing a builder that works with
Node absent from PATH proves. So a C port would NOT advance "no Node in dev": Node lives
in `scripts/build-tjs.cjs` (the ENGINE half — the CMake candidate) and in the test suite.

**Cross-quaude: neutral.** The cross constraint is that bytecode must be readable by the
target engine, solved by canonical-LE inside the engine. The driver's language does not
touch it.

**Could it be C, by part:**

| part | verdict |
|---|---|
| trailer scan, module-table decode, topo sort, archive assembly, sha256 | yes, comfortably — C's home turf, and `bun-graph.cjs` is already written in that idiom (Uint8Array, integer math) so it could move |
| the 68 anchors and splices | see the CORRECTION below — my "slow edit loop" objection was measured and is false, and dropping it turns this row from the crux AGAINST into an argument FOR |
| bytecode compilation | neither — it is the engine's API wherever it lives (but see below) |

**CORRECTION (user, same day): the "slow edit loop" objection is false — measured.**

I claimed moving the anchors to C meant "the slowest edit loop". The user's counter was
that anchors and splices can be their own `anchors-and-splices.so`, relinked incrementally.
Measured on this box, a realistic stand-in for that component (2000 lines, 68 pattern
sites plus splice helpers):

    cc -O2 -fPIC -shared   full build   0.15s
                           relink after a one-line edit   0.10s

That is faster than Node's own startup. The objection was an assertion I had never
tested — the exact failure mode this session kept finding elsewhere. Withdrawn.

**AND DROPPING IT SURFACES A BETTER ARGUMENT FOR C, which I had not made.** The anchors
exist TWICE today, by hand:

    libexec/extract-claude-js.cjs      17 anchor definitions
    libexec/inspect-claude-bundle.cjs  18 hand-written MIRRORS

The mirroring is documented in that file's own comments ("a VERBATIM mirror of
extract-claude-js.cjs's SNAPSHOT_GEN", "in lockstep with extract-claude-js.cjs"). It is
not hypothetical drift: `snapshotGeneratorPresent` gated on a SUBSTRING NEAR the anchor
instead of the anchor, so it reported the site healthy for three releases while the hook
was dead — one of the four instrument failures of 2026-08-25.

A shared `anchors-and-splices` library, linked by both the extractor and the inspector,
makes that duplication structurally impossible. That is a LINEARITY win of the kind the
★★★ overhaul is actually for — one place answers the question — and it is available
whether the library is C or JS, but C is what makes it natural to link from a CMake
build.

**What genuinely remains as a cost:** the one-time port of 68 anchors across a regex
dialect boundary (JS named groups and backreferences to PCRE), on the most
fidelity-critical strings in the project. Mitigable, and the mitigation is obvious
because we have the bundles: run both implementations over real 2.1.210/.215/.218/.241/
.243/.245 binaries and require identical match sets before switching. That is a
differential test, not a leap.

**ARGUMENTS FOR C THAT SURVIVED SCRUTINY (user's, and stronger than my first answer):**

1. **Legibility/linearity.** A CMake build that compiles almost entirely C is one build
   system, one language, one mental model — no "which half am I in". Plus a payoff I
   missed: a C clode could LINK libquickjs and compile bytecode IN-PROCESS (`qjsc.c` is
   already that program), deleting today's oddest step — spawning the freshly built
   template to act as its own bytecode compiler. BC_VERSION lockstep would then hold BY
   CONSTRUCTION rather than by the writer==runtime convention we maintain by hand, and it
   might simplify the CLODE_TARGET_TEMPLATE dance.
2. **Slow weird machines.** The one hard number is **~30s clode startup on Mavericks**
   (fast hosts are not compile-bound; the floor box is). Essentially all of that is
   parsing/compiling clode's own JS, and a C binary makes it ~0. The work itself — regex
   over 28MB, sha256 over 60MB — would also speed up in an interpreter-vs-native
   comparison.

**THE COUNTERARGUMENT (user's, and the heaviest):** we would stop exercising QuickJS in
clode itself. Verified: `.github/actions/build-leg/action.yml` fuses `clode build --self`
on EVERY leg and then uses that binary to build a quaude. So on ~15 platforms per push,
clode-as-JS-on-the-engine does real work — 360MB read, 68 anchors over 28MB, 1459 module
compiles, archive assembly. That is the shim's fs/spawn/path surface under load, per
platform, and it has caught things a quaude session would not: the shim reporting a
**SIGKILLed child as exit 0** (cost a day on Haiku), `cpSync` **dropping file mode**, the
**Haiku write deadlock**. A C clode loses exactly those.

**Where this lands, not decided:**

- **Split by VOLATILITY rather than wholesale.** C for the hot, stable spine (binary
  read, decode, sha256, archive, bytecode via linked libquickjs); engine JS for the
  anchors and splices, which change every few upstream releases and want a 10-second edit
  loop. Costs some linearity — two languages — but keeps clode running the engine on
  every leg, so the coverage counterargument answers itself.
- **Or full C, paying explicitly** for the lost coverage with a per-leg engine-exercise
  suite. Defensible, but a deliberate replacement for ACCIDENTAL coverage tests what
  someone thought of, and nobody would have thought of the Haiku exit-code bug.

**NEXT STEP, and it is small: profile a Mavericks build.** This repo's own doctrine is to
profile on the slow box before choosing a lever ([[profile-on-slow-box-first]]). We have
the 30s startup number and no breakdown of the rest. If the time is mostly startup, the C
spine buys nearly all of it while the anchors stay cheap to change — and the decision
makes itself.

### ★★ Critically review the environment variables (user, 2026-08-25)

**THE QUESTION TO ANSWER (user, sharper than the original framing):**

> "if we had zero CLODE_* env vars, what would break?"

That inverts the default. "Which can we remove?" assumes keeping and asks for a reason to
delete; this asks each one to justify existing.

**A first pass at answering it, 2026-08-25:**

     51  CLODE_* vars read by SHIPPED code (libexec + bin)
      0  documented in clode's usage/help text
      4  command-line flags in total: --help --naude --verbose --version

The literal answer is **nothing a user could know they were relying on** — all 51 are
undocumented back doors. `--verbose` already exists as BOTH a flag and `CLODE_VERBOSE`,
which is the shape survivors should have: clode is a command that builds, and a command's
inputs are arguments.

**The builder/runner leftover is visible in the list, not merely suspected.** These are
read by the shim INSIDE A BUILT QUAUDE, not by clode:

    CLODE_TTY_FOCUS  CLODE_TTY_MOUSE  CLODE_SHADOWS  CLODE_KC_MODE
    CLODE_RG_UNTRANSLATABLE  CLODE_NO_WATCH  CLODE_WATCH_INTERVAL

Target runtime knobs wearing the builder's prefix. Setting `CLODE_*` to affect a running
quaude is reasonable given the name and wrong given the architecture; whatever survives
probably should not say `CLODE_` at all.

**Groups, so the review is a few decisions rather than 51 arguments:**

| group | examples | plausible answer |
|---|---|---|
| host-tool overrides | `CLODE_BFS` `CLODE_UGREP` `CLODE_RG` `CLODE_TAR` `CLODE_GZIP` `CLODE_UNZIP` `CLODE_SHA256` `CLODE_ZSTD` `CLODE_NPM` `CLODE_NODE` | ten vars for "use this binary" is ten chances to disagree; one flag or a config file |
| paths / state | `CLODE_CACHE` `CLODE_DEPS` `CLODE_STATE_ROOT` `CLODE_PROVIDERS` `CLODE_LIBEXEC` `CLODE_VERSION_DIR` | genuinely useful for isolation; needs ONE story, not six |
| input selection | `CLODE_CLAUDE_BIN` `CLODE_TJS` `CLODE_TARGET_TEMPLATE` `CLODE_MAIN_BUNDLE` `CLODE_TEMPLATES*` | these change WHAT IS BUILT — the dangerous group. Flags, and announced |
| network | `CLODE_RELEASES_URL` `CLODE_CHANGELOG_URL` `CLODE_TEMPLATES_BASEURL` `CLODE_UPDATE_CHANNEL` | mostly test seams pointing at local servers |
| debug | `CLODE_SHIM_DEBUG` `CLODE_SHIM_TRACE` `CLODE_PROBE` `CLODE_RG_DEBUG` `CLODE_HINT` | most defensible; still one name per idea |
| target runtime | the TTY/shadow/watch set above | wrong prefix entirely |

**The user's framing:** "I worry that we have a lot of unneeded env vars left over from
before we discovered the architecture that clode is only a builder, never a runner. And I
worry that the remaining ones are also susceptible to mistaken usage."

Inventory taken 2026-08-25, so the review starts from facts rather than impressions:

    116  distinct CLODE_* variables across libexec, bin, scripts, test, .github
     28  referenced ONLY in tests or CI — no shipped consumer in libexec/, bin/ or scripts/

The 28 with no shipped consumer:

    CLODE_BAKE_EOF CLODE_BUN_SHIM CLODE_CROSS_BUILD CLODE_CROSS_BUILD_TIMEOUT_MS
    CLODE_DARWIN_PROVIDER_BIN CLODE_ENGINE CLODE_ENV_TEST_NUM CLODE_ENV_TEST_X
    CLODE_GUEST_PACKAGES CLODE_GUEST_SCRIPT CLODE_LEAK_CANARY CLODE_NAUDE_SMOKE
    CLODE_OFFLINE CLODE_ORACLE_BINARIES CLODE_QUAUDE CLODE_QUAUDE_EXE
    CLODE_REGEN_URL_GOLDEN CLODE_REGEN_URL_REJECTS CLODE_SCREEN CLODE_SELF
    CLODE_SHIM_WALL_BUNDLE CLODE_SMOKE_EOF CLODE_TARGET CLODE_TARGET_KIND
    CLODE_TJS_STUB_SYNC CLODE_TJSC CLODE_UPDATE_CONSTANTS_GOLDEN CLODE_X

Not all are dead — some are deliberate test fixtures (`CLODE_ENV_TEST_X`, `CLODE_X`), and
`CLODE_SELF` appears only in tests because `test/no-clode-self.test.cjs` is a RATCHET
asserting it stays retired. Each needs judging, not sweeping. But others in that list
(`CLODE_ENGINE`, `CLODE_OFFLINE`, `CLODE_TARGET`, `CLODE_QUAUDE`) read like they once had
shipped consumers, which is exactly the leftover the user suspects.

**Mistaken usage is PROVEN, not hypothetical.** On 2026-08-25 I exported
`CLODE_CLAUDE_BIN` for a build; twenty minutes later it silently redirected `npm test`,
failing `the installed provider still carves to a single entrypoints/cli.js module`
because the override pointed at a code-split 2.1.245. I nearly edited that test before
noticing the contamination was mine. The var wins over the clode-managed provider store
(`libexec/clode-resolve.cjs:101`, first check in `resolveClaudeBin`), is unscoped, is
never echoed, and nothing warns that a test run is using an overridden provider.

**Overlapping names for one concept — at least four ways to say "which provider":**

    CLODE_CLAUDE_BIN  CLODE_PROVIDER_BIN  CLODE_PROVIDERS  CLODE_DARWIN_PROVIDER_BIN

and engine selection is spread across `CLODE_TJS`, `CLODE_TJS_OUT`, `CLODE_TARGET_TEMPLATE`.
Whatever survives the cull should have ONE name per concept.

**Questions the review should answer, per variable:** who reads it; is it a user-facing
knob, a test seam, or build-tool plumbing; does it still make sense now that clode is
only a builder and never a runner; and — for anything that changes WHICH INPUTS a run
uses — should its use be announced rather than silent.

**Candidate mechanisms** (decide during the review, do not presume):

1. A single declared registry, so an undeclared `CLODE_*` read is a failure. Same shape
   as the EXPECTED table in `scripts/upstream-drift-check.mjs`, and it makes the count
   ratchet instead of drift.
2. Anything that redirects an INPUT (provider, engine, deps, cache) announces itself on
   stderr when set. My contaminated test run would have said so in its first line.
3. Tests that must not inherit ambient overrides clear them explicitly, rather than
   trusting the shell they happen to run in.

Related: [[isolate-clode-runs-from-user-deps]] (the existing convention of pointing
CLODE_DEPS/CLODE_CACHE at temp dirs) and [[dev-box-state-hides-bugs]].

### Hooks under the code-split bundle: 9 of 9 apply (RESOLVED 2026-08-25)

**snapshot_bridge is fixed, and the investigation found a worse problem underneath.**
Re-pinned to the GENERATOR, not the memoizing wrapper, on measured evidence: `storageV5`
reaches the snapshot down exactly one path (plugin bin dirs appended to `export PATH=`),
the shadow snippets clode's probe reads come from no-argument helpers, upstream's own
first call passes `undefined`, and `iqo` does not touch the memo that `ozn` sets. So
pre-warming via the generator stays a throwaway — the semantics the hook shipped with
through 2.1.241 — while wrapper-pinning would have planted a storageV5-less shellConfig
in the memo the app uses all session.

**The re-pin alone would not have worked.** Awaiting the bridge does not await the
snapshot: upstream's shell-provider builder starts generation and returns without
awaiting the promise, and has done for as long as that shape has existed. Measured:
`await bridge()` resolved 7ms in having read ZERO findings. So the "eager" step was
DECORATIVE even on versions where the anchor matched. The splice now also awaits a
probe signal (`__clodeAwaitSkewProbe`), bounded so a session that never generates a
snapshot degrades rather than stalls.

**And the gate was lying, again.** `snapshotGeneratorPresent` in inspect gated on the
substring `return{provider:await ` instead of the real anchor, so it reported the site
healthy for three releases while the hook was dead. Same shape as patchUpdateHint. Now
mirrors SNAPSHOT_GEN verbatim.

Verified after integration: the hook applies on 2.1.241 (CJS) and on 2.1.243 and 2.1.245
(split), all 9 hooks apply on both split bundles, and the drift check is green on all
three.

### Original entry, kept for the reasoning: 7 of 9 survive untouched; 1 needed a decision

Ran the REAL patch functions from `libexec/extract-claude-js.cjs` against every module of
the 2.1.245 graph (not coarse signatures — the actual anchors):

    patchDoctorWarnings            exactly once   chunk-svasnyw2.js
    patchAutoupdater               exactly once   chunk-b8dwartr.js
    patchNativeAutoupdater         exactly once   chunk-b8dwartr.js
    patchUpdateNotice              exactly once   chunk-svasnyw2.js
    patchRemoteControlUnavailable  exactly once   chunk-tq5wjes2.js
    patchLegacyAutoupdater         exactly once   chunk-b8dwartr.js
    patchManualUpdate              exactly once   chunk-vwrzap7y.js
    patchUpdateHint                2 modules      (correct — global replace, no
                                                   exactly-once contract by design)
    patchSnapshotBridge            NO MATCH       <-- the one real casualty

**Structurally this is good news:** no anchor spans a module boundary, so per-module
patching works and `transform()` keeps its exactly-once contract by applying each patch
across the graph and requiring one hit total. That was the risk I expected to bite.

**The casualty is ordinary upstream drift, not the split.** The snapshot generator gained
a parameter. 2.1.241 (matches the anchor):

    async function G(){let h=await S();return{provider:await I(h)}}

2.1.245, in `chunk-ctcq7phx.js`:

    async function iqo(e){let t=await sqo();return{provider:await NUn(t,{storageV5:e})}}

`SNAPSHOT_GEN` requires `\(\)` and a single-argument inner call, so it matches neither
2.1.243 nor 2.1.245. Confirmed it still applies on 2.1.241, so this arrived with the
.243 line.

**DO NOT re-pin this blind, which is why it is filed instead of fixed.** Two things make
it a semantics decision, not a regex edit:

1. The generator now takes `storageV5`. `patchSnapshotBridge` exposes the function so
   clode's splice can pre-warm it; calling `iqo()` with no argument passes
   `storageV5: undefined`, which may not be what upstream passes.
2. The caller MEMOIZES: `ozn(e){return jC.shellConfig ??= iqo(e), ...}`. Invoking `iqo`
   ourselves creates a promise upstream never sees, so the pre-warm could populate a
   different snapshot than the one the app then uses — a silent fidelity divergence of
   exactly the kind [[fixes-scoped-to-reduce-fidelity-diffs]] warns about.

Candidate targets are the generator itself or the memoizing wrapper `ozn`. Deciding needs
evidence about what upstream passes for `storageV5` and whether the memo is shared —
observable by instrumenting a real run, not by reading minified code.

**Consequence if left:** the eager-snapshot bridge does not apply on 2.1.243+, so
applet-skew findings appear only after the first shell command instead of at startup.
Degraded, not broken. The drift check already gates this anchor
(`snapshot_generator_present`), so it will go red the day .243+ becomes `latest`.

### Rebuilding the code-split bundle: EMBED THE GRAPH (decided 2026-08-25, spike green)

**Decision (user):** "Sounds like time to try embedding the graph as is and see how that
shakes out." Chosen over rewriting ESM into a CJS registry.

**Why, in one line:** the rewrite path can corrupt PROMPTS, and it would do it silently.
The bundle ships skill documentation containing the literal text ``| `import` | Call ...``
and a template literal `defaults import com.apple.Terminal`. A regex that mangles those
does not crash — it quietly changes what Claude is told. Three separate hand-rolled
scanners tripped on exactly those strings while I was building the rewriter; the fourth
would have been the one that stopped tripping and started corrupting.

**Spike result — the reassembled graph RUNS.** Feeding the decoded modules to node's own
ESM machinery (link + evaluate + a dynamic-import callback resolving through the same
registry), with node builtins as real externals:

    linked OK        1382/1382 modules, no missing chunks
    evaluated        entry ran, reached main(), resolved dynamic import()s
    ran on into      vendored execa code, 3 modules deep past the entry

Failures now are ENVIRONMENT, not structure — first `globalThis.process` (my sandbox
passed `globalThis: undefined`), then `S("stream")`, Bun's injected CJS-require helper.
Both are what quaude's shim exists to provide. **Not one byte of upstream source was
modified to get there.**

**What is still unbuilt:**

1. An emitter: one artifact holding every module VERBATIM plus the entry name.
2. A resolver for `/$bunfs/root/*` reading from that table. txiki already has
   `tjs_module_loader` wired via `JS_SetModuleLoaderFunc2` (src/vm.c:497), so the engine
   can load modules — the question is exposing an in-memory registry to it, which likely
   means an engine patch. We already patch the engine, so this is known territory.
3. Where clode's hooks apply. They currently patch one big text; with the graph embedded
   they apply per-module. The anchors are regexes pinned to specific sites, so this
   should be mechanical — but `transform()` and every EXPECTED anchor need re-pointing,
   and the fidelity of that is exactly what the drift check gates.
4. naude (the Node SEA variant) needs node's loader hooks rather than txiki's.

**Retired:** `libexec/esm-relink.cjs` (uncommitted) — the ESM->CJS text rewriter. Kept
nothing but the lesson: do not lex minified JS by hand. If a future change ever needs
this again, use the engine's own parser, never a regex.

### Coverage that turns on and off with machine state (root-caused 2026-08-25)

**Concrete instance, fixed:** `test/clode-watch.test.cjs` gated 16 tests on
`existsSync(~/.local/share/clode/node_modules/semver)` — the SHARED USER STORE, outside
the repo. CI populates `deps/claude/node_modules` (`npm ci --prefix deps/claude`) and
never that store, so **all 16 skipped in CI, silently, forever**. On a dev box they ran
only if something had happened to prime the store.

Two of them asserted pre-`1af2027` wording ("Node-impacting" vs "repackaging-impacting")
and had been passing for months BY NOT RUNNING. They failed the instant an unrelated
`clode build` created the store at 01:13 on 2026-08-25 — i.e. the suite's answer changed
because of something no one did to the repo.

Fixed by making the gate mirror the resolution order of the code under test
(`libexec/clode-watch.cjs:54-56` checks the store OR the sibling `deps/claude`), so the
tests now RUN in CI. Verified both ways: 25/25 with the store present, 25/25 with
`XDG_DATA_HOME` pointed at an empty dir.

**The general problem, which is NOT fixed and belongs to this overhaul.** At least eight
test files gate on state outside the repo (`REAL_STORE`, `XDG_DATA_HOME`, `homedir()`):

    clode-deps  clode-paths  clode-watch  e2e-self_update
    guard-subcommands-gate  e2e-ctrlz-tui  inspect  clode-resolve

Nobody knows which of them run in CI, which run on a given dev box, or which have been
quietly passing by not running. `npm test` reporting `60 skipped` is not information —
it is a number that changes with the weather.

What this wants, in rough order of value:

1. **A skip census.** Print WHY each skip fired and WHERE the gate looked, so a skip is
   attributable instead of anonymous. Today a skipped test and a passing test are
   indistinguishable in the summary.
2. **Gates that mirror the code under test**, as the clode-watch fix does — never a
   single hard-coded location when the product checks several.
3. **A CI assertion on the skip COUNT** (or better, the skip SET), so coverage silently
   shrinking is a failure. Same shape as the exact-count rule that keeps
   `test/windows-path-ratchet.test.cjs` honest.
4. Longer term, and the real fix: make the suite hermetic enough that these gates are
   unnecessary — which is the same direction as [[node-only-as-oracle]] and the existing
   hermeticity roadmap.

Related doctrine already in the repo: "a skipped oracle is not a pass"
(.github/workflows/ci.yml), and the ambient-red P0 below. This is the third time in two
days that the SUITE, not the product, was the thing lying.

**User directive, and it gates further feature work:** *"I'm tired of the build being so
baroque as to become opaque. We have to have a clear clean well factored fully cross
build before we go any further"* — **including extracting dependencies to standalone
repos where that makes sense.**

**The evidence that provoked it, from one day:**
- `be-oracle` ran 30 times, never caught the big-endian bug it existed for, and its one
  endianness assertion was `assert.ok(x === 'LE' || x === 'BE')`.
- `templates-drift` was red on every push about a STATE (engine sources moved past the
  last release), so main was never green and "is main green?" stopped being answerable.
- I then moved that check into release.yml, where it would have blocked the very release
  that fixes the staleness — it compares against `releases/latest`.
- `haiku-x64`'s `soft-fail: true` was INERT because it publishes, so a dead upstream
  package repo hard-gated every release.
- The provider lookup could kill its own step silently: `find` under `set -euo pipefail`
  exits before the error message that explains it.
- Five separate Windows walls in one chain, each invisible until the previous fell.
- The MCP probe could not distinguish "transport broken" from "the binary never
  launched", and blamed SSE for a spawn failure.
- `spike/quickjs/` — a directory named for throwaway work — holds PINS.md, 23 engine
  patches, atomic-shim.c and the qemu rigs, and four of six engine-recipe inputs.

The pattern is not that any one of these was indefensible. It is that **gates
multiplied faster than the doctrine for what a green means**, and the headline fidelity
number (`floor 6/6`) excludes G2, the only row that involves a real logged-in user.

**Work this implies** (not a plan — the plan comes first, see [[clode-backlog-plan-first]]):
1. Name what a green MEANS, and delete or fix every gate that cannot deliver it.
2. Separate the engine recipe from spike residue; one patches directory, not two (the
   split already cost 13 commits of undetected cosmo rot).
3. Extract what is genuinely a separate artifact into its own repo — the engine
   (pin + patch stack, since the vendor tree is already not in-tree), the qemu/VM rigs,
   possibly the node-shim. Each has its own release cadence and its own tests.
4. Make the cross-build story ONE mechanism, understandable end to end, rather than
   tiers × legs × fixups × templates × recipes discovered one failure at a time.
5. Fold in the already-tracked: [[spike/quickjs is not a spike]] entry, the wall-aware
   gap inventory, and derived `how: 'ci'` fidelity rows.

**Do this before further feature work.** The 2026-08-24 release ships first because it
fixes a confirmed 40-target cross-build DOA; the overhaul starts after.

### POSTSCRIPT (user, 2026-08-31) — what if clode were an orchestrator of small Unix programs?

**The user:** "What if clode were not one big program, but an orchestrator of several small Unix
programs, each of which does one job that composes into 'building quaude' (or naude)?"

**WHERE THIS STANDS: NOT DECIDED, and recorded as a question, not a plan (user, 2026-08-31):**
*"Not 100% sure I want this design. It'll probably be really annoying on Windows, like everything
always is. But also it makes clear for me (and agents) what the steps in a build are, and whether
JavaScript is advantageous for these steps."*

So there are two payoffs and one tax, and they should be weighed as such rather than argued into
a foregone conclusion:

- **Payoff 1 — legibility, for humans AND for agents.** This is the stated ★★★ goal ("tired of
  the build being so baroque as to become opaque") applied to the one place it has not been: an
  agent reading this repo today cannot enumerate the build's steps, because they are control flow
  inside a 1678-line function, not things with names. Neither can a person.
- **Payoff 2 — it forces the per-step language question to be asked per step.** Right now "what
  language is this written in" is answered once, for a monolith. Programs with argv contracts let
  the answer differ by step, and make a rewrite of ONE step a contained experiment. This is
  exactly the open question in [[What language is the SECOND half?]] above — that entry could not
  reach a verdict partly because "the second half" is not divided into parts you could decide
  about separately. Decomposition is the precondition for answering it.
- **Tax — Windows, and the worry is well-founded** (see the Windows section below).

**Half of this already exists, which is the strongest argument for the other half.** Two build
steps are ALREADY separate programs, spawned through a declared, injectable seam
(`clode-fuse.cjs:889`, "the one spawn seam every build step goes through"; the naude call takes
its own `opts.spawnRun` override at `:1135` so it is stubbable without stubbing every other
spawn — a seam per program, which is what a program boundary looks like when it is real):

    fuse    spawnRun(template, ['run', libexec/quaude-fuse.js, <7 positional args>])   clode-fuse.cjs:1571
    naude   spawnRun(blobgenNode, [build-naude.mjs, --cli … --bundle … --out …])       clode-fuse.cjs:1136-1148

`quaude-fuse.js` even documents its own argv contract as a usage block (`:7-21`) — signed base,
stage dir, node-shim dir, node_modules dir, bootstrap, extras.json, out. That is a Unix program
with a man page, already. So the proposal is not "restructure clode into a shape it has never
had"; it is "finish a shape it half has, and stop growing the parts that resisted."

**What did not get decomposed, by line count:**

    scripts/build-tjs.cjs        3796
    libexec/clode-fuse.cjs       1678   resolve+stage+extract+close deps+sign+thin+fuse+smoke+attest
    libexec/extract-claude-js.cjs 1593
    libexec/scc-merge.cjs        1428

**Why this is the same answer as the two items above, not a third project.** A step that is a
program has a name, a start, an end, and declared inputs and outputs. That is *precisely* what
the progress item needs (a step list you cannot add to without it appearing) and *precisely* what
the out-of-tree/CMake item needs (a dependency graph where a producer that stops producing is an
error at generate time, not two minutes into a build — the naude/`cli.cjs` lesson above). Three
asks, one mechanism.

**The obvious first extraction is also the slow one.** The cyclic-group merge is already a pure
function of the staged graph, already keyed, already cached to `graph-merged.json` — and it costs
**~380s of a 6:52 build** on a fast arm64 Mac (measured in situ; see the 1800000ms timeout
comment at `clode-fuse.cjs:1585`). A pure keyed transform from one file to another IS a Unix
program; today it is a stretch of `Fusing…` inside a worker nobody can run by hand.

**Three questions this has to answer BEFORE it is built, because each one can invert the design:**

1. **How does a fleet of programs ship as one binary?** clode's entire point is a single artifact
   you can carry to a machine with no Node — see [[clode is a BINARY WE BUILD, and only that]].
   Twelve programs must not mean twelve downloads. The busybox answer (ONE image, dispatch on
   subcommand/argv[0]) keeps single-artifact shipping AND gets separable programs, and quaude's
   member/index layout is already a container for exactly that. Likely right — but decide it, do
   not drift into it.
2. **What is the interchange, given the payloads are huge?** Unix composition suggests pipes;
   ours are a 46MB `graph.json`, a 49MB `cli.cjs`, and a template binary. Those are FILES in a
   work dir, not a shell pipeline — the make/CMake shape, not the `|` shape. Say so explicitly,
   or someone builds a pipeline that spends its life serializing. (Measured, for scale: reading +
   parsing that `graph.json` is 187ms — cheap enough that a file boundary between steps costs
   nothing next to a 380s merge.)
3. **Which engine runs each program?** Not a stylistic choice: anything that emits quickjs
   bytecode MUST run under the same tjs binary that becomes the template — the
   runtime-compiles-for-itself rule (`quaude-fuse.js:1-5`); bytecode from any other build is
   undefined behavior. So the programs are inherently NOT uniform — some node-side, some
   tjs-side — and the boundary falls exactly where the worker boundary already falls. That the
   existing split lands on a real constraint rather than on tidiness is evidence the
   decomposition wants to follow constraints too.

**The failure mode to design against.** Splitting into programs without DECLARING inputs and
outputs just distributes the naude bug: a producer stopped emitting `cli.cjs` and only a runtime
path check, two minutes in, noticed. More programs = more places for that. The value is in the
declaration; the program boundary is what makes the declaration checkable. Do not take the
boundary and skip the declaration.

**THE WINDOWS TAX — what is evidence, what is assumption.** Measured here, today:

    win32/.exe/windows mentions, build path:   build-tjs.cjs 26, clode-fuse.cjs 22,
                                               build-naude.mjs 15, platform-tag.cjs 11
    files carrying a #! shebang:               26   (inert on Windows — every call site must
                                                     name its interpreter, or the multi-call
                                                     binary makes the question moot)

A live Windows entry above says the worry is not superstition: the deadlock guard cannot get
scratch space on Windows runners (deferred 2026-08-31, still dark). A second one, the
Windows-path ratchet being blind on ~1335 lines of real code, was RESOLVED 2026-09-04 (phase 5,
task 9) — see the entry above. Anything that multiplies process boundaries multiplies the
surface the remaining one already fails on.

**But one measurement cuts the other way, and it is the most interesting number here:**

    libexec/quaude-fuse.js — the step that IS already a separate program:   0 win32 branches

The step with a real argv contract is the step with no Windows special-casing at all, because its
interface is "arguments in, file out" and it delegates path handling to the engine it runs under.
That is one data point, not a proof — it also happens to be the step that runs under tjs on every
platform. But it is the opposite of what "programs are annoying on Windows" predicts, and it is
worth knowing which way the effect actually runs before deciding.

**So the deciding measurement is nameable, and we should take it before committing** (this is a
claim about how Windows behaves, so per doctrine it gets measured, not assumed): on a Windows
runner, time N sequential spawns of a multi-call binary against the same N steps called
in-process. If per-spawn cost is trivial next to a 380s merge, the tax is imaginary and the
legibility is free. If it is not, the answer is probably "programs as the DECLARED unit, some of
them dispatched in-process" — which keeps both payoffs and pays the tax only where it is cheap.

**Cheap way in, no rewrite:** the spawn seam exists and is already injectable for tests. Lift one
step behind it (the merge), give it an argv contract like `quaude-fuse.js`'s, and see whether the
step list, the timing record, and the CMake edge all fall out of that one change. If they do, the
rest is the same move applied N times. If they don't, we learned it for the price of one refactor.

## ★★ SHIPPED ENGINE TEMPLATES PREDATE THE uid/gid FIX — cross-fused Linux quaude is DOA (2026-08-09)

**Every `clode build --target linux-*` produces a binary that cannot run on Linux
at all.** It dies before doing any work:

```
Temp directory /tmp/claude-1000 is owned by uid 0, expected 1000.
Refusing to use it — another user may have pre-created it.
```

The directory is genuinely owned by 1000 (`stat(1)` agrees). The bundle is told
0, so its tmpdir-ownership guard refuses and exits.

**Root cause: a STALE published engine, not a code defect.** The shim is already
correct — `libexec/node-shim/modules/fs.cjs` reads `raw.uid` and only falls back
to 0 when the ENGINE omits it, with a comment naming this exact failure. The fix
landed 2026-08-04 in 906af8b ("surface real uid/gid from FSS.stat"). But the
downloaded engine templates are all pinned `26.6.0-1a230d3`, built 2026-07-27 —
BEFORE that commit:

| engine | `__tjs_fs_sync.stat()` keys |
|---|---|
| template `tjs-linux-arm64-26.6.0-1a230d3` | `size, mode, mtimeMs, kind` — **no uid/gid** |
| built from current source on the VM | `size, mode, **uid, gid**, mtimeMs, kind` |

So the shim's fallback fires and reports uid 0. Proven from inside the fused
binary with `CLODE_PROBE`: `statSync uid=0`, `getuid=1000`, `raw engine
uid=undefined`.

**This hits the product's headline feature.** One-host-builds-all-quaudes goes
through `clode build --target`, which DOWNLOADS a template and OVERWRITES
`CLODE_TARGET_TEMPLATE` (clode-fuse.cjs:907) — so even an operator who builds a
correct engine locally and exports that variable is silently ignored. CI-built
release artifacts compile from source and are NOT affected; this is the
user-side cross-fuse path only.

**2026-08-24: I "corrected" this entry to say the released artifacts were affected too.
THAT CORRECTION WAS WRONG. The original scoping — user-side cross-fuse only — is
right.** Recording the mistake because the reasoning that produced it is a trap worth
naming.

I saw that the shipped shim hardcodes `this.uid = 0` (true: `git show
v0.20260801.2:libexec/node-shim/modules/fs.cjs`) and concluded every quaude it builds
must trip the tmpdir guard. I had not read the guard. It begins:

    let t = process.getuid?.();
    if (t === void 0) return;              // no getuid -> guard SKIPPED entirely
    ...
    let i = rV.fstatSync(o);
    if (i.uid !== t) throw Error(`Temp directory ... is owned by uid ${i.uid}, expected ${t}`)

**`process.getuid` did not exist in the released shim at all** — verified across every
file under `libexec/node-shim` at the tag. It arrived 2026-08-04 in d824f48, three days
AFTER v0.20260801.2 (tag 4881ca8, 2026-08-01). With no getuid the guard returns before
ever comparing, so a hardcoded `stat().uid = 0` was harmless. That is why quaude
daily-drove fine on NetBSD on earlier releases.

**The real mechanism, then.** Three commits landed the same day, 2026-08-04:
d824f48 added `process.getuid` (arming the guard), fabe404 corrected the primitive, and
906af8b made `stat()` surface the engine's real uid — its subject line says it exactly:
"closing the getuid/stat mismatch". So on main the window was hours, and it is closed.

What is left is precisely the cross-fuse path: a clode from main HAS getuid, and a
DOWNLOADED template engine omits uid, so the shim falls back to 0, the guard runs, and
it refuses. Native builds compile an engine that supplies uid and are fine. The
original entry had this right.

**Every template is from the same stale build** (all `1a230d3`, dated 2026-07-27),
so assume every cross-fuse target is affected, not just linux-arm64. The guard is
what makes it VISIBLE on Linux; other targets may be silently degraded wherever
stat().uid matters.

**RE-VERIFIED 2026-08-24, from the published artifact itself — this is not a stale
note.** Pulled the `linux-arm64` slice out of the v0.20260801.2 templates blob by its
manifest offset/length (sha256 matches the manifest exactly: 416cf3f7b933…), ran it on
a real Linux/arm64 box:

    published template engine:  keys = size, mode, mtimeMs, kind        <- no uid/gid
    engine from current source: keys = size, mode, uid, gid, mtimeMs, kind

So the defect is live and republishing genuinely fixes it. Timeline confirms the
mechanism: latest release v0.20260801.2 published 2026-08-02; the fix 906af8b landed
2026-08-04, two days later.

**The 2026-08-24 fetch-time recipe check does NOT cover this pack.** obtainEngine
refuses a pack whose recipe differs from the running clode's — but this manifest carries
NO recipe field (it predates the 4f86738 stamp), so the check reads "cannot check" and
declines rather than blocking. That is the correct behaviour for an unknown pack and it
means users on the CURRENT pack still get a silently-DOA binary. The protection begins
with the next published pack.

**Blocked on: haiku-x64.** It is `publish: true`, and both tiers strip `soft-fail` from
publishers, so it is a HARD gate — a release cannot succeed while it fails. See the
haiku-x64 entry: either master/beta6 ports resolve on the beta5 guest, or the leg is
demoted by dropping `publish`.

**Fix:** republish the engine templates from current sources. Then re-drive the
cross-fuse targets. Worth adding a tripwire: a template whose tjs pin predates a
known-required patch should fail the build loudly rather than fuse a binary that
cannot boot.

**Blocked on this:** `linux-arm64-glibc` floor rows. The VM-built engine works, but
`clode build --target` will not use it, so a good Linux quaude cannot currently be
produced from this host without bypassing the template path.

## ★ HANDOFF — operational state at 2026-08-22 (read this first)

Written at the end of a long session, for whoever picks this up. The durable
record is: this file, the commit messages (deliberately long), the memory notes,
and the tests. Anything below is the perishable part that lives nowhere else.

**Unpushed:** `195af60` (proxy fix). `origin/main` is at `0decc98`.

**THE OPEN QUESTION.** CI run **32573776213** (`ci` on `0decc98`) had 20 of 32 jobs
failing while still in progress — legs on linux, windows AND darwin. That is
AFTER the regression fix, so the first thing to establish is which of these it is:

- Is the leg failure the SAME `SIGINFO`-shaped compile error as before
  (`src/signals.c: 'X' undeclared`)? Then the guard fix is incomplete — look for
  another unguarded name, or a group whose names still come from the host.
- Is it a DIFFERENT error? Then the constants fix worked and this is new.
- Is it just slow/cold? `ed0d8ff` made the tjs cache key consume
  `scripts/engine-recipe.mjs`, so the key CHANGED ONCE and every leg rebuilds its
  engine from scratch on the first run after. Expected, and it is not a failure.

Do not guess between those three. Read the logs; `gh api
repos/schmonz/clode/actions/jobs/<id>/logs` and grep for `error:` — `gh run view
--log-failed` is drowned by git-config teardown noise in this repo.

**TWO ATTRIBUTION TRAPS, both live right now:**

1. `upstream-drift` run 32555253017 is RED, and that does NOT mean upstream broke
   us. It ran on `d4f831c7`, which had my constants regression; its `boots` job
   builds the musl leg and died on the same compile error. Re-run it against a
   green commit before believing anything it says. (This is exactly the misread
   that job's own header warns about, and I nearly made it.)
2. `tjs-legs` run 32555844772 (netbsd-arm64) is RED for the same reason — it was
   dispatched to prove the errno fix made that leg green, and it proved nothing.
   Re-dispatch: `gh workflow run tjs-legs.yml --field tier=release --field
   only=netbsd-arm64`.

**`templates-drift` is RED BY DESIGN** until a release is cut (published engines
are 3 weeks stale). Do not "fix" the check. Cutting a release is the remedy, and
the check will then go green as evidence rather than assumption. See the
templates section above — republishing WITHOUT the recipe stamp silently resets
the clock, so land the manifest `recipe` field with or before the republish.

**Renovate:** 8 open PRs are not stuck on Renovate. `automerge: true` with no
`ignoreTests` means they wait for a green base — a red main blocks all of them.
They should drain by themselves once main is green. Note that pushing to main
re-triggers all 8 (their merge commits are invalidated), which looks like CI
noise from a push and is not.

**Still open, with full diagnoses in the commit messages / sections above:**
`close()` while CONNECTING is ignored (pre-existing, may be reachable via the
bundle's connect-timeout path); the template cache dead-ends on a stale entry
with no re-fetch; `net.Socket` over `tjs.connect` is what real npm `ws` needs
(NOT `http.request`, which was already tried); glibc legs will report 55 fs
constants where node reports 57 until `_GNU_SOURCE` reaches the `tjs` target.

**The lesson worth carrying:** four separate times this session the INSTRUMENT was
wrong, not the thing measured — a mock's handshake GUID, a mock that never
answered a close frame, a fidelity test comparing both sides through JSON, and a
proxy mock that could not accept connections because it shared a process with a
`spawnSync`. Assert on what ARRIVED at the far end, always run the reference
implementation against the same mock, and prove a test fails before believing it
passes.

## Four small truths phase 2 found and did not fix (2026-09-02)

Filed here because they were found in phase 2's whole-branch review and recorded only
in that phase's working notes, which are gitignored. A deferral nobody else can read
is a silent loss, so they get a tracked home. Each is small; none blocks anything.

### 1. `MERGER_VERSION` is a hand-written literal, not a derived key

`libexec/scc-merge.cjs:36` — `var MERGER_VERSION = '12'`. The cyclic-merge cache is
keyed on it, so bumping it by hand is what invalidates the cache when the merger
changes. Two documents describe it as something it is not: the cross-build umbrella's
"keys are DERIVED by the runner from the content of the step's declared inputs. Keys
are never hand-written", and the phase-2 design's "a hash of the merger's own source".

The failure mode is the ordinary one for hand-maintained versions: change the merger,
forget the bump, and every machine with a warm cache silently serves output from the
OLD merger. That is the same shape as the two cache defects the umbrella already
catalogues (a linux carve served to a darwin build; a templates cache serving a sha256
mismatch), which is the argument for deriving it.

Not changed on the spot because it is a real design change: whatever the key becomes,
every existing cache entry is invalidated the day it lands, and the sequencing of that
belongs with the declared-inputs work, not with a test fix. See the umbrella's phase-4
scope correction.

### 2. `test/naude-assembler-closure.test.cjs` guards CLOSURE, not MEMBERSHIP (CORRECTED 2026-09-04)

`libexec/quaude-fuse.js` carries a list of libexec/scripts members that must be
materialized into a fused builder.

**The description this entry carried was wrong in both directions, and it had already been
copied into the umbrella spec before anyone re-ran it.** It said the test "does not guard
the carried-member list" and that removing any entry leaves it at 1 pass / 0 fail. Measured
2026-09-04 on current main, restoring the tree between runs and verifying it clean after:

| mutation to the `quaude-fuse.js:211` member list | verdict |
|---|---|
| remove `canonical-name.cjs` (required by `platform-tag.cjs`) | **RED** |
| remove `build-scratch.cjs` | **RED** |
| remove `build-naude.mjs` | **RED** |
| remove `merge-step.mjs` (leaf — nothing relatively requires it) | **GREEN — blind** |
| remove `sea-sign.cjs` (leaf) | **GREEN — blind** |

So it walks the list and catches an un-carried SIBLING REQUIRE. What it cannot see is a
dropped LEAF member — and that is the dangerous half, because phase 2 added
`scripts/merge-step.mjs` to exactly that list.

Why it matters here specifically: phase 2 added `scripts/merge-step.mjs` to that list,
and a missing entry does not fail a test — it fails a `--self`-fused build at
`tjs.spawn`, at which point the only signal is a build that dies in the field. This is
the same shape as the `clode-native` P0 recorded at `.github/workflows/ci.yml:487`,
where the tests proving the node-free builder worked were silently skipping and 13 CI
jobs broke at once while CI stayed green.

The fix is a test that mutates the list and asserts the closure check goes red — the
list is derivable from what the worker actually loads, so the stronger fix is to derive
it rather than declare it.

### 3. The trace log's `interpreter` field is a constant on the fused path

`libexec/clode-fuse.cjs` records `interpreter` on every build-trace line. Under a fused
clode that value comes from the node-shim's `process.version`, which is the hardcoded
string `'v24.0.0'` (`libexec/node-shim/modules/process.cjs:425`, with `process.release`
undefined) — a compatibility facade for a boot-time version gate, not a fact about the
running interpreter.

Live evidence, `~/.local/share/clode/build-trace.jsonl` at 117 runs:

```
 107 "interpreter":"node v26.3.0"
   9 "interpreter":"node v24.20.0"
   1 "interpreter":"node v24.0.0"     <- the fabricated one
```

The fabricated row is indistinguishable in shape from the nine genuine v24.x rows, so a
reader cannot tell which runs came from a fused builder. The phase-2 design singles this
field out as load-bearing rather than padding, precisely because comparing timings across
interpreters is the point of keeping the log. Fix: record the real interpreter identity
on the fused path, or record honestly that it is unknown — never a plausible-looking
constant.

### 4. `quaude-fuse.js`'s merge read-back parses unguarded

`libexec/quaude-fuse.js:339` does `JSON.parse(dec.decode(mergedRaw))` on the merged graph
with no try/catch, so a corrupt file surfaces as an unhandled rejection (exit 1 under tjs)
rather than a named error pointing at the file.

Low severity on purpose: `scripts/merge-step.mjs` writes that file atomically
(`.tmp-<pid>` then rename), so a truncated or out-of-space write leaves the temp behind
and never promotes it — the parent then fails on a MISSING file, which `mustRead` already
reports by name. The unguarded parse is only reachable if something else corrupts a
fully-renamed file. Worth a named error the next time that code is touched.

## 31 unreviewed Bun APIs the shim does not provide (2026-09-02)

`libexec/inspect-claude-bundle.cjs --strict` exits 1 against any current provider
bundle with 31 unreviewed upstream needs. Reproduce:

```
node libexec/inspect-claude-bundle.cjs \
  "$(node -e 'console.log(require("./test/provider-resolve.cjs").providerBin())')" \
  --shim libexec/bun-shim.cjs --node "$(command -v node)" --strict
```

The list, as of provider 2.1.252:

  Bun.$ (missing)
  Bun.Database (missing)
  Bun.FFI (missing)
  Bun.Glob (missing)
  Bun.Security (missing)
  Bun.cron (missing)
  Bun.dns (missing)
  Bun.enableANSIColors (missing)
  Bun.fetch (missing)
  Bun.fileURLToPath (missing)
  Bun.indexOfLine (missing)
  Bun.inspect (missing)
  Bun.isMainThread (missing)
  Bun.jest (missing)
  Bun.nanoseconds (missing)
  Bun.peek (missing)
  Bun.plugin (missing)
  Bun.readableStreamToArrayBuffer (missing)
  Bun.readableStreamToBlob (missing)
  Bun.readableStreamToBytes (missing)
  Bun.readableStreamToJSON (missing)
  Bun.readableStreamToText (missing)
  Bun.redis (missing)
  Bun.registerMacro (missing)
  Bun.resolve (missing)
  Bun.resolveSync (missing)
  Bun.s3 (missing)
  Bun.sleepSync (missing)
  Bun.sql (missing)
  Bun.udpSocket (missing)
  bun:sqlite (bun: module unhandled)

**Why nobody had seen this.** `test/inspect.test.cjs` hardcoded provider
`2.1.183` — a version that is on no current box and is not what `UPSTREAM_PIN`
names — and gated all three of its e2e tests on it with `{ skip: <boolean> }`, which
node:test renders as a bare `# SKIP` with no reason. So the gate was not skipping; it
was ABSENT, and silently. Fixed 2026-09-02: the file now resolves through
`test/provider-resolve.cjs` (which reads `UPSTREAM_PIN` rather than carrying a second
version string), and every skip states its reason.

**What each of the 31 needs** is the same judgement the `Bun.zstdDecompress` entry
above got, and it is a judgement, not a mechanical fix: does our tested traffic
actually REACH this API? The two-layer inventory answers "does upstream reach for it",
not "do we". Then either stub it in `libexec/bun-shim.cjs`, or add it to the
`ACCEPTED_*` lists with the reasoning written down.

Most look unreachable on our paths at a glance — `Bun.jest`, `Bun.FFI`, `Bun.s3`,
`Bun.sql`, `Bun.redis`, `Bun.Database`, `bun:sqlite` are not things an agentic CLI turn
touches — but "looks unreachable" is exactly the assumption this project keeps getting
burned by, so each gets checked rather than waved through. A wrong stub is worse than a
missing one: it turns a loud failure into a silent wrong answer.

**Deferred deliberately** (user, 2026-09-02), NOT dropped: the test skips with this
entry named in its skip reason, and the cross-build umbrella now cannot close until
every skip in the suite is understood and un-skipped where possible.

## Every skip is understood, and as many as possible are not skips (2026-09-02)

**A closure condition on the cross-build umbrella** (user, 2026-09-02), recorded here
because the umbrella spec lives under `docs/`, which is gitignored — a condition only
this session can read is not a condition.

The umbrella cannot be closed while the suite contains skips nobody has accounted for.

**Why this is not fussiness.** The suite went green on 2026-09-02 — 1691 pass, 0 fail —
and 84 skips that nobody had inventoried. The first pass over them found five that gave
NO reason at all, because node:test renders `{ skip: <boolean> }` as a bare `# SKIP`.
Fixing only those immediately exposed that `test/inspect.test.cjs` was pinned to
provider `2.1.183`, a version on no current box: three tests had not been skipping, they
had been ABSENT. Un-pinning them surfaced 31 unreviewed Bun APIs the shim does not
provide (filed above).

A green suite with an uninventoried skip list is the same lie as a green suite with
tolerated failures. This project has already paid for that once — a `clode-native` P0
broke 13 CI jobs at once while CI stayed green, because the only tests proving the
node-free builder worked were silently skipping (`.github/workflows/ci.yml:487`).

**The bar, concretely:**

1. Every skip states a reason, as a STRING, naming what it wanted and where it looked.
   Never `{ skip: true }`.
2. Each is classified: **opt-in** (expensive, or spawns a real bundle and touches the
   Keychain), **unavailable** (win32-only on a Mac, offline), or **DARK** — it could
   run here and does not.
3. Every DARK skip is either made to run, or deferred with a written entry someone with
   no context can act on.
4. The count and classification are recorded, so a later rise is visible rather than
   absorbed.

**Inventory: 84 skips -> 33, same day, suite still green.**

Plain `node test/run.mjs`, nothing exported: 1776 tests, 1742 pass, 0 fail, 33
skipped, exit 0. Was 1691 pass / 84 skipped.

What moved, and why it is worth reading rather than just counting:

| was | fix |
|---|---|
| 43 provider-gated | three unrelated causes fixed (zstd unreachable under a deliberately minimal PATH; an unbuilt naude bundle; residual `/$bunfs` chunk edges), then the provider wired into `test/run.mjs` AND `.github/workflows/suite.yml` |
| 4 `no engine: set CLODE_TJS` | `graph-runner.test.cjs` read one env var instead of asking `tjsPath()` like the rest of the suite. The engine was on the box. |
| 1 `set CLODE_TJSC` | same defect in `tjs-bytecode-regen.test.cjs` — the test that checks our MODEL of tjsc against the real tool |
| 3 in `inspect.test.cjs` | pinned to provider 2.1.183, which no box has: absent, not skipping |
| 5 with no reason at all | `{ skip: <boolean> }` renders as a bare `# SKIP`; they say why now |

**One defect, three places.** A gate keyed to an undocumented environment variable is
dark BY DEFAULT, and it reports that darkness in language ("no CLODE_PROVIDER_BIN",
"no engine", "set CLODE_TJSC") that reads like an honest unavailability. Worth
recognising on sight.

**The 33 that remain, all classified, all stating a reason:**

| count | category | verdict |
|---|---|---|
| 18 | opt-in (13 `CLODE_LIVE_RENDER` — spawns a real bundle, touches the Keychain; plus naude-smoke, oracle-binaries, live-roundtrip, cross-build) | legitimate: expensive or intrusive by nature |
| 8 | unavailable here (4 offline, 2 win32-only PATHEXT, 2 need a Windows PE on a real Windows kernel) | legitimate: cannot run on this host |
| 5 | need a built artifact (3 quaude, 1 naude, 1 darwin provider) | **the remaining candidates** — each needs a ~7min build, none is impossible |
| 2 | deferred with BACKLOG entries (the 31 Bun APIs; MCP-over-WebSocket under tjs) | tracked, named in the skip text itself |

**Still to do before the umbrella can close:** the 5 artifact-gated ones. Either build
the artifact in CI (other jobs already build a quaude, so the pieces exist) or write
the entry saying why not. Note the naude one already has the best skip message in the
repo — it probes three locations, names each, and prints the exact build command.

Read skip reasons with the TAP reporter — the default reporter hides them:

```
node --test --test-reporter=tap test/... 2>&1 | grep '# SKIP'
```

## MCP-over-WebSocket: quaude never connects on native (non-cosmo) darwin-arm64 tjs (2026-09-02)

Undarking the 43 provider-gated skips (above) required routing
`test/fidelity/agentic-{mcp-ws,tools,subagent-diff,workflow-complete}.test.cjs` and
`slash-command-diff.test.cjs` through clode's own staging (`libexec/clode-extract.cjs`,
which merges away the residual `/$bunfs/root/chunk-….js` cyclic edges) instead of the raw
extractor. That fix worked cleanly for four of the five: agentic-tools (5/5), 
agentic-workflow-complete (1/1), agentic-subagent-diff (1/1), slash-command-diff (1/1) all
went green. **agentic-mcp-ws.test.cjs did not** — it fails on a DIFFERENT, unrelated
defect this staging fix exposed rather than caused (it was previously unreachable: every
run before 2026-08-29 died on the chunk-resolve error before ever making an API call).

**Symptom.** `mcp.seen` (what the mock MCP-over-ws server observed) is `[]` — the ws
server never receives so much as a TCP connection. The bundle's own agentic loop still
completes: it synthesizes `<tool_use_error>Error: No such tool available:
mcp__mymock__echo_needle</tool_use_error>` and answers the turn, so the CLI exits 0 and
the ONLY visible signal is the assertion on `mcp.seen`.

**Eliminated, with evidence, not assumed:**
  - Not a race with the mock's instant reply: inserted an artificial 3000ms delay before
    the mock ever responds (real Anthropic-latency stand-in) — `mcp.seen` still `[]`.
  - Not a permission/approval gate: added `--dangerously-skip-permissions` — no change.
  - Not the config shape: `{mcpServers:{mymock:{type:"ws",url:...}}}` matches the
    extracted bundle's own transport-selection code verbatim
    (`t.type==="ws"` → `new globalThis.WebSocket(t.url,{protocols:["mcp"],...})`, found by
    grepping the staged `cli.cjs`) — this is the shape upstream 2.1.251 itself expects.
  - Not upstream/config-loading in general: **the identical mcp.json, identical argv,
    identical mock, run under naude (plain node cli.cjs, no shim/engine) instead of
    quaude (tjs+node-shim) gets all four expected MCP events — `initialize`,
    `notifications/initialized`, `tools/list`, `tools/call`** — and the mock tool result
    propagates end-to-end. Upstream's MCP-over-WS client works; node is a clean
    reference.
  - Not a dev-box config leak (this box's own `~/.claude` SessionStart hook, which
    otherwise pollutes the request stream with superpowers-skill text): reproduces
    identically with a fresh `HOME` + `CLAUDE_CONFIG_DIR`.

**Isolates to: quaude's own native-WS delegation** (the shim path this test's header
names: `new WebSocket(url,{protocols:["mcp"]})` → the engine's native WebSocket, per
`libexec/bun-shim.cjs`) on THIS box's tjs engine
(`tjs-macos-arm64-26.6.0-1a230d3`, Mach-O arm64, not cosmo). `--debug mcp` produced zero
MCP-related log lines even though the staged bundle plainly logs `Initializing WebSocket
transport to ${t.url}` on that path — consistent with a SILENT failure at the native
layer, the same shape as the cosmo bug this file already tracks two sections up
("MCP-over-WebSocket client never connects — FIXED (2026-07-30)"): libwebsockets' bundled
SHA-1 miscompiling under cosmo's undefined `BYTE_ORDER`/`LITTLE_ENDIAN`/`BIG_ENDIAN`
macros, breaking `Sec-WebSocket-Accept` and failing the handshake with no JS-visible
error. That fix was `__COSMOPOLITAN__`-gated; RESULTS.md's 2026-07-30 entry describes
NATIVE tjs (not cosmo) passing mcp-ws at parity at provider 2.1.218, so this is either a
regression since then (provider bump 2.1.218→2.1.251, or an engine/shim change) or a
second, non-cosmo instance of the same class of native-layer bug. Not chased further
here — it needs the cosmo fix's own tooling (`--strace`/`--ftrace` against a debug-symbol
tjs, or an engine rebuilt from current `main`) to find the native fault, which is beyond
this task's scope (undarking provider-gated tests, not engine C debugging).

**Disposition:** `test/fidelity/agentic-mcp-ws.test.cjs`'s one test is left skipping,
loudly, naming this entry — not silently reverted to failing, and not weakened to assert
less. Re-run the exact repro above (naude vs quaude, same mcp.json/mock/argv) once a
current-`main` tjs engine or `--strace` access is available.

## The last 5 skips: what it would take, and why they are not free (2026-09-02)

After 84 -> 33, five skips remain that are neither opt-in-by-nature nor impossible
here. Per the umbrella's closure condition they get an entry rather than a shrug.

**All five need a built artifact**, and that is the whole cost — a `clode build` is
~7 minutes.

| test(s) | needs | notes |
|---|---|---|
| `test/fidelity/update-notify.pty.test.cjs` ×3 | `CLODE_QUAUDE` — a real fused quaude | drives it through a PTY, types `/status`, reads the rendered notice |
| `test/naude-shim-boundary.test.cjs` ×1 | `CLODE_NAUDE_BIN` | the SHIPPED-BYTES half; the other half (markers, assembly contract, five red proofs) DOES run |
| a darwin-carve check ×1 | `CLODE_DARWIN_PROVIDER_BIN` | asserts a darwin-carved quaude takes the macOS `/Library` branch |

**Why not just build one in `npm test`.** That job now installs a provider, so adding
`clode build` is mechanically easy — and it would add ~7 minutes to every CI run, for
five tests. That is a real budget decision, not a detail to slip in; it needs an owner
who cares about CI wall-clock to say yes.

**CORRECTED 2026-09-03.** This entry first said PTY tests "CANNOT run on POSIX CI at
all" because of the Keychain modal. That is wrong, and the user caught it: **Linux has
no Keychain.** The claim was lifted from `.github/workflows/ci.yml`'s
`windows-amd64-tui` comment ("the reason POSIX CI can't run it") and repeated without
checking, which is how an imprecise comment becomes a false plan.

What the gate ACTUALLY says (`test/fidelity/interactive-live-turn.test.cjs` and
siblings) is a blanket opt-in with no platform condition at all:

```js
if (process.env.CLODE_LIVE_RENDER !== '1') { SKIP = 'live-render opt-in only …'; }
```

Its stated rationale is "touches the Keychain, may touch the network". Those are TWO
justifications with different scopes:
- **Keychain** — macOS only. On Linux the bundle takes the on-disk credentials path
  (that is the whole point of deleting the Keychain emulation, 2026-09-02), so there
  is no GUI modal to hang on.
- **network** — platform-independent, and the real remaining reason. Several of these
  tests already drive a mock Anthropic server, so it may not bind for all of them.

**So the opportunity is bigger than this entry first claimed.** It is not just the
three update-notify tests on Windows — it is potentially all 13 `CLODE_LIVE_RENDER`
skips plus these three, on a LINUX runner, which is where CI already runs `npm test`.
Nobody has tested that, so it is a hypothesis with a clear experiment, not a plan:

1. On Linux, build a quaude, set `CLODE_LIVE_RENDER=1`, and run one PTY test with a
   mock provider. `ultimate-hat` has Docker if a local Linux box is wanted.
2. If it renders, the gate should become platform-aware rather than blanket — macOS
   keeps the opt-in for the Keychain, Linux does not need it — and the network-touching
   subset stays opt-in on its own merits.
3. The Windows TUI job remains the right home for anything that genuinely needs a
   non-POSIX kernel, and it still does not `clode build` a quaude despite its header
   comment saying it does.

The cheap win is unchanged and unaffected: `CLODE_NAUDE_BIN` for the naude test, since
`build --naude` already happens elsewhere in CI.

**Recommended order** for whoever picks this up:
1. Build a quaude in `windows-amd64-tui` and set `CLODE_QUAUDE` — three tests, in the
   one place a PTY test can spawn a real bundle.
2. The naude one is cheapest of all: `build --naude` already happens elsewhere in CI;
   point `CLODE_NAUDE_BIN` at it.
3. The darwin-carve one needs a darwin-carved provider on a macOS runner — smallest
   payoff, do it last.

Until then all five state their reason, and the naude one is the model the others
should copy: it probes three locations, names each, and prints the exact build command.

## Two defects found while wiring the Linux PTY CI job (2026-09-03)

Both surfaced by making dark tests run. Neither is caused by that work.

### 1. `clode build --out DIR/name` fails when DIR does not exist (product bug)

Hit for real in a Linux container while reproducing the new CI job's literal command
sequence: `clode build --out /some/new/dir/quaude` fails rather than creating the
parent. The workaround is an explicit `mkdir -p` before the build, which the CI job now
does — but that is a workaround in a caller, not a fix.

**It is an asymmetry, which is the tell.** `scripts/build-naude.mjs:450` does
`fs.mkdirSync(path.dirname(bin), { recursive: true })`, so `clode build --naude --out
DIR/naude` creates its parent happily. The quaude path does not. Same flag, same user
expectation, two behaviours — and the one that works is the less-travelled one.

Fix: create the `--out` parent on the quaude path too, matching build-naude. Small, and
worth a test that runs `--out` into a non-existent directory on BOTH paths, since the
asymmetry is exactly what nobody noticed.

### 2. `test/e2e-doctor-parity.test.cjs` HARD-FAILS when its precondition is missing

Confirmed by running it: without a logged-in provider profile it does not skip, it
fails. That is why the new `linux-x64-pty` CI job deliberately excludes it — including
it would make the job permanently, meaninglessly red, which is how a job stops being
read.

This is the INVERSE of the silent-skip problem this repo has spent the day removing,
and it is just as damaging: a test that cannot distinguish "the thing I test is broken"
from "I was not given what I need" produces a red that carries no information. The
project's own rule (`any-ci-red-is-our-red`) only works if red means something.

Fix: give it a precondition guard that SKIPS with a reason naming what is missing — the
same shape everything else in the suite now uses — so it can be included in the Linux
PTY job and light up the moment a logged-in profile is available.

`test/fidelity/stale-frames.pty.test.cjs` needs the same profile but already skips
correctly on its own precondition; it is excluded from the job only for lack of the
profile, not for bad behaviour.

## RETRACTED: "make-min-provider cannot carve a Windows-built provider" (2026-09-03)

**This entry was wrong and is retracted the same day. Kept, rather than deleted, because
the way it was wrong is the useful part.**

The claim: `scripts/make-min-provider.cjs` cannot carve a windows-built provider, because
it failed with `no entrypoints/cli.js @bun-cjs block in C:\npm\prefix\claude (format
changed?)`. It was filed as a product gap and `test/make-min-provider.test.cjs` was
changed to skip win32 providers.

**The same CI run disproves it, in an earlier step of the same job:**

```
make-min-provider: 1793 modules + 173 text assets (104 zstd rows decompressed)
  -> ...\provider-min: 43859667 bytes (from 217360032)
make-min-provider: self-check ok (1793 modules, entry B:/~BUN/root/cli, platform win32)
```

It minimised a real 217MB win32 provider to 43MB and self-checked it. The script is
fine. What failed was minimising `C:\npm\prefix\claude` — on Windows, `npm i -g`
leaves an EXTENSIONLESS SHELL WRAPPER at `<prefix>/claude` beside the real executable.
The test was feeding the minimiser a shim.

**Two lessons, both cheap to state and both already paid for.**

1. *An error message about a FORMAT invites a conclusion about the FORMAT.* "no
   `entrypoints/cli.js @bun-cjs` block ... (format changed?)" reads as "this binary's
   format is unsupported". The actual condition was "this is not a binary". The script
   could say so: checking for the Bun trailer first and reporting "not a Bun container"
   would have made the real cause unmissable.
2. *The skip I added would have hidden a working path.* Gating on `platform === 'win32'`
   would have stopped exercising win32 minimisation everywhere — including where it
   demonstrably works — to avoid one bad input. **Skip on the actual precondition, never
   on a proxy for it.** The test now gates on `isBunContainer()` (a trailer check, in
   `test/provider-resolve.cjs`), which is the true condition and is platform-neutral.

**Still worth doing**, and the only real to-do left from this: make
`make-min-provider.cjs` check for the Bun trailer up front and fail with "not a Bun
container" rather than a format complaint. Same for any other tool that assumes its
input is a provider because of where it was found.

## RESOLVED: two full-suite flakes, two different causes (2026-09-03/04)

Both passed in isolation and failed only under a concurrent full-suite run. They looked
like one problem. They were two, and neither was where the symptom pointed.

### 1. `node-shim-child-process.test.cjs:569` — a race in the TEST's own child program

Symptom: `Unexpected end of JSON input`, roughly 1 run in 4.

Two hypotheses were disproven by measurement first: a shared oracle-stage race (the
pre-warm below did not stop it) and file-level concurrency (six parallel runs of the file
alone, all green). Then the test was changed to report WHICH side produced unparseable
output and to print the bytes — and the next occurrence, two runs later, gave it up:

    the node reference run produced unparseable stdout (Unexpected end of JSON input).
      stdout (0 bytes): ""

The NODE side, not tjs. The child program did:

    const c = cp.spawn('/bin/echo', ...);
    await fh.close();
    c.on('exit', () => { console.log(JSON.stringify(...)); });

`/bin/echo` is about as fast as a process gets. Under load the `await` outlasts it, the
child exits, `'exit'` is emitted with nobody listening, and node does not replay it for a
late listener — so the program printed NOTHING and exited 0. Fixed by attaching the
listener before the await, keeping the behaviour under test (the parent still drops its
fd right after spawn).

Verified: **8 cold-cache full runs, 8 green.** It had reproduced on run 2, twice.

**The lesson worth keeping:** a bare `Unexpected end of JSON input` names neither the
side nor the content, so two occurrences taught nothing. One occurrence with "which side,
and the bytes" solved it immediately. When a flake resists, instrument it before guessing
again — the third guess costs more than the diagnostic would have.

### 2. `agentic-subagent-diff.test.cjs:70` — a real shared-cache race

Symptom: `clode: graph-meta failed under <scratch>/tjs (exit 1)`.

`libexec/clode-extract.cjs`'s `extractIfNeeded` is not atomic: it mkdirs the shared,
provider-keyed cache dir and `writeFileSync`s straight into it, with no temp-and-rename.
Its cache-hit guard requires a matching signature, so on a COLD cache two concurrently
spawned test files both miss the guard and write the same paths.

`test/run.mjs` now pre-warms that stage once before spawning anything, serialising the
one write while keeping the cache's purpose (one extraction per provider per run). Not
seen again across 11 subsequent cold runs.

**Still open, product-side:** the non-atomic extraction itself. Two concurrent
`clode build`s would race the same way — the suite's half is fixed, the product's is not.
The fix is extract-to-temp-then-rename, and it belongs with phase 4's input-validation
work.

## Release acceptance: the checks only a human with credentials can run (2026-09-04)

**Decision (user, 2026-09-04):** the login-gated tests are not CI tests. They are aimed
at a human, locally, before cutting a release. That resolves them — they were being
counted as "dark" when they were really "unscheduled", and it avoids putting real
credentials in CI to satisfy a bookkeeping number.

This is written down because the ritual it describes previously existed only in the
maintainer's head and in one assistant's memory. A release gate nobody can read is not
a gate.

**Run all of these on a logged-in machine before tagging.** Each states what it proves,
because the point is to be able to tell which one failed and what that means.

### 0. FIRST: items 1 and 2 below are OBSOLETE — retire, do not re-anchor

**Settled 2026-09-04 by capturing the real screen** (native claude 2.1.260, under the
repo's own PTY harness, from a trusted cwd). `/doctor` IN A SESSION is no longer a
fixed-format report. It is an AGENT TURN:

    ❯ /doctor

    ⏺ I'll run the read-only checks first, then present a report before changing anything.

      Running 3 shell commands…
      ⎿  $ cd ~; echo "=== installMethod/autoUpdates/numStartups ==="; jq '{installMethod,
         autoUpdates, numStartups, hasCompletedOnboarding}' ~/.claude.json 2>&1; …

    ✻ Seasoning… (12s · ↓ 666 tokens)

A model runs shell commands and writes prose about what it found. There is no report
frame, no `Enter to close`, no `Installation warnings` section, no stable item list —
and the output is non-deterministic BY DESIGN, because it is generated. It also spends
tokens on every run.

**So `test/e2e-doctor-parity.test.cjs` is not stale-anchored, it is conceptually void.**
It diffs two model-authored turns and asserts they match modulo an allowlist. Two runs
of the SAME binary would not match. No amount of re-anchoring fixes that; the property
it was written to check no longer exists to be checked.

Note the CLI subcommand `claude doctor` IS still structured (`Running:`, `Platform:`,
`Path:`, `Config install method:`, … then `No installation issues found.`) — but its own
last line points at the in-session `/doctor` for the real checkup, and the labels have
drifted from the test's anyway (`Running:` where the test expects `Currently running:`).
If a doctor-parity check is ever wanted again, THAT is the surface to diff, and it is a
different, much simpler test: run two binaries non-interactively, compare stdout.

**Recommended:**
- RETIRE `test/e2e-doctor-parity.test.cjs`. It cannot be made to work.
- KEEP the `stale-frames` PROPERTY — "a finished full-screen command's frame is erased
  on repaint" — but re-express it against a command that still IS a full-screen frame
  with a stable footer. `/doctor` no longer is one, which is why that test waits forever
  for a footer that is never drawn.
- If doctor parity is still wanted: write a small new test over `claude doctor` vs
  `quaude doctor`, structured and deterministic, with none of the PTY machinery.

Cost of finding this: one PTY capture, ~666 tokens, no Keychain modal. Cost of NOT
finding it: two tests carried in the release ritual that could never have passed.

### 1. Doctor parity vs native — `test/e2e-doctor-parity.test.cjs` (2 tests) — SEE ITEM 0

    CLODE_LIVE_RENDER=1 node --test test/e2e-doctor-parity.test.cjs

Drives a real quaude under a PTY, types `/doctor`, and diffs the rendered report against
NATIVE Claude Code. Needs a native `claude` on PATH AND a logged-in profile, since
`/doctor` reports auth state. Proves: our TUI renders what upstream's does, on the one
screen that summarises everything.

**Known defect, FIXED 2026-09-04 (phase 5, task 13):** it HARD-FAILED rather than
skipping when its preconditions were absent (see "Two defects found while wiring the
Linux PTY CI job") — every environmental precondition above was checked, but neither
"did the native capture actually show the report" nor "did quaude's" was, so a
logged-out profile — or, per item 0's later finding the same day, ANY current native
build, since `/doctor` in a session no longer renders a fixed footer at all — hard-failed
`assert.match(NATIVE, /Enter to close/)` instead of skipping. Same fix shape as
`test/fidelity/stale-frames.pty.test.cjs`'s `REPORT_OK` precondition check, applied one
file over: the first test now skips, naming which side never showed the footer, before
asserting on it. This does NOT re-open item 0's retirement recommendation — the strict
parity test below stays `t.skip`'d WIP regardless, and given `/doctor`'s render shape has
moved on, this first test will now skip UNCONDITIONALLY on any current native build. That
is the honest state of the world, not a new gap: full retirement (item 0) remains the
still-open, separate, larger call.

### 2. Stale frames — `test/fidelity/stale-frames.pty.test.cjs` (2 tests)

    CLODE_LIVE_RENDER=1 node --test test/fidelity/stale-frames.pty.test.cjs

RECIPE row F3, a captured rendering bug: open `/doctor`, close it, assert the finished
frame was actually ERASED rather than lingering under the live prompt. Proves: repaint
does not leave ghosts — the kind of thing only a human eye or a PTY capture catches.

### 3. Live streamed render — `test/fidelity/interactive-live-turn.test.cjs` (2 tests)

    CLODE_LIVE_ONLINE=1 node --test test/fidelity/interactive-live-turn.test.cjs

Real credentials, real tokens, real streaming, both native and quaude. Proves: a live
model response renders in the TUI. This is the standing "live TUI turn is the
acceptance" gate — `--version`, `--help`, and a mock PONG have each certified a broken
build before.

### 4. Live print round-trip — `test/e2e-print.test.cjs`, `e2e-tools.test.cjs`, `e2e-assets.test.cjs`

    CLODE_LIVE_ONLINE=1 node --test test/e2e-print.test.cjs test/e2e-tools.test.cjs test/e2e-assets.test.cjs

`-p` reaches a real model; the Bash tool round-trips end to end; the embedded-asset shim
raises no consumer errors on a real turn. Proves the non-interactive path, which the
mock cannot fully stand in for.

### 5. Real naude build+boot — `test/naude-smoke.test.cjs` (2 tests)

    CLODE_NAUDE_SMOKE=1 node --test test/naude-smoke.test.cjs

Builds a REAL Node SEA and boots it. Costs minutes, needs no credentials — so this one
could equally be a nightly CI job; it is here because it is a build-acceptance property
and a release is when you most want it. Measured 2026-09-04 on macOS 26 / node 26.3.0:
2 pass, 0 fail.

**Why not just put credentials in CI.** Tokens in CI spend money on every push, leak
into logs, and turn a rendering regression into an auth outage at 3am. These checks are
cheap for a human at release time and expensive as a robot on every commit. The trade is
deliberate: CI proves the build, a human proves the product.

**MEASURED 2026-09-04 (phase 5, task 13): items 2, 4, and 5 already skip honestly.**
Read (not assumed) before touching anything: item 2
(`test/fidelity/stale-frames.pty.test.cjs`) already gates both its tests on a
`REPORT_OK` precondition check before any assertion — the "Two defects" entry itself
already noted this ("needs the same profile but already skips correctly on its own
precondition"). Item 4's three files (`e2e-print`, `e2e-tools`, `e2e-assets.test.cjs`)
each check `CLODE_LIVE_ONLINE`/`providerSkipReason()` and `t.skip()` before any assertion
that could otherwise reach a real network or a missing provider. Item 5
(`test/naude-smoke.test.cjs`) computes a single `skipReason()` (opt-in flag, Node
version, provider presence) before anything else runs. Only item 1 (above) had the
hard-fail defect; it is now fixed the same way.

**Ambient hazard found while measuring, NOT fixed here, NOT introduced by this task:**
any test that resolves a provider via `test/oracle-models.cjs`'s default
`resolveProviderBin()` (no explicit `CLODE_PROVIDER_BIN`) — including item 3's oracle
machinery and the new item-2-of-the-auth-gate `test/credential-store-attempted.test.cjs`
above — falls through, under a FRESH `CLODE_STATE_ROOT` with no provider cached there, to
`~/.local/bin/claude` on the bare host. On this box that now resolves to native Claude
Code 2.1.261 (auto-updated past `UPSTREAM_PIN`'s 2.1.251), which our extractor cannot
stage into a runnable `cli.cjs` (`clode graph: compiling /$bunfs/root/__clode-scc-2.js
failed: invalid property name` — the same SCC-merge incompatibility "Upstream pinned to
2.1.251" already names for 2.1.257+). Reproduced identically against an UNMODIFIED file,
`test/node-shim-roundtrip-oracle.test.cjs`, under the same bare `CLODE_STATE_ROOT=$(mktemp
-d)` with no other env set — so this is a pre-existing property of this box's drifted
native install, not a defect in either file. `test/run.mjs` already avoids it by resolving
and exporting a PINNED `CLODE_PROVIDER_BIN` once, centrally, before any test file loads
(see its own "A provider and an engine, resolved ONCE for the whole suite" comment) — so
the real suite, run the way it is meant to be run, never hits this. Confirmed: with
`CLODE_PROVIDER_BIN` set to the pinned 2.1.251 store path (matching what `run.mjs` sets),
`test/credential-store-attempted.test.cjs` gives IDENTICAL results with and without a
fresh `CLODE_STATE_ROOT`. Filed here rather than fixed because the real fix (bump the
pin, or teach the extractor/oracle helpers to detect+skip an incompatible carve before
running it) is a separate, larger call this task's brief did not ask for.

## P1: a quaude built from a foreign-carved provider LIES about its platform (2026-09-04)

    $ quaude doctor
    Platform: linux-x64          <- on a darwin-arm64 Mac

Found by the new `test/doctor-cli-parity.test.cjs` on its first run, comparing
`claude doctor` against `quaude doctor`. The structure matched; exactly one value did
not, and it was this one.

**Why.** Bun constant-folds `process.platform`/`process.arch` at CARVE time
([[carve-platform-constant-folding]]), so the platform a quaude reports is the platform
of the PROVIDER IT WAS BUILT FROM, not the machine it runs on. This box's pinned
`2.1.251` provider is a **linux** carve — because the store is
`providers/<version>/claude`, keyed by version alone, so a foreign carve sits happily at
the pinned path (see the phase-4 note in the umbrella).

**The part that makes it a P1 rather than a curiosity:** `clode build` assembled a
darwin quaude from a linux-carved provider WITHOUT COMPLAINT. That directly contradicts
[[target-matched-assembly]] — "clode must assemble quaude from TARGET-matching inputs".
The build had everything it needed to refuse: `providerPlatformOf()` exists, and a darwin
carve of 2.1.250 was sitting in the same store.

So anyone building a quaude on this box right now gets one that believes it is on Linux.
What else that mis-belief reaches is unmeasured — `process.platform` gates path handling,
spawn behaviour, and the managed-settings location, so "it prints the wrong OS in doctor"
is the symptom we happened to look at, not the extent.

**Fix, in order:**
1. `clode build` REFUSES a provider whose carve does not match the build target, naming
   both. Cheap, and turns a silent wrong answer into a loud one.
2. Key the provider store by platform (and arch), so a foreign carve cannot occupy the
   pinned path. That is the phase-4 derived-key work.
3. Then re-run `test/doctor-cli-parity.test.cjs` — it asserts the invariant directly.

**How it stayed invisible:** `--version` matches, PONG round-trips, attest passes, the
smoke test is green. Every existing acceptance check is satisfied by a quaude that thinks
it is running on the wrong operating system. The one surface that says otherwise is a
diagnostic nobody was diffing.

## WHERE THE CROSS-BUILD UMBRELLA STANDS (2026-09-04) — read this first

The umbrella spec itself lives at `docs/superpowers/specs/2026-09-01-clean-cross-build-umbrella.md`,
which is **gitignored by project convention** (superpowers working docs are not part of the
project). So this section carries the DECISIONS, which are project decisions rather than
planning scratch. Anyone picking this up on a fresh clone starts here.

### Phase order (changed from the original, deliberately)

    1 → 2 → 2.5 → 5 → 5b → 3 → 4 → 6

**PHASE 3 IS NEXT.** Everything to its left is DONE and shipped; the notes below record what
each one delivered and, for 5 and 5b, why they were inserted ahead of 3 at all.

**Phases 1 and 2 are DONE and shipped.** Out-of-tree builds with a tree-immutability gate;
the step-reporting protocol (`libexec/build-report.cjs`, `build-compose.cjs`,
`build-trace.cjs`), mismatch enforcement, and the first real extraction
(`scripts/merge-step.mjs`, the cyclic merge as its own process with an argv contract).

**Phase 2.5 (finish the skips) is DONE.** Skips 84 → 33, every one classified as opt-in,
host-unavailable, or deferred-with-an-entry; both full-suite flakes root-caused and fixed
(8 consecutive cold-cache green runs); a new Linux PTY CI job runs 16 tests that had never
run in CI.

**Phase 5 (gates that can fail) is DONE** (2026-09-05, `ae33a49..76ee5b0`), **and so is phase
5b (the build's own gates), 2026-09-12, `3051c35..36fa968`** — see "Phase 5b CLOSED" below for
what 5b measured but did not control. 5 was moved ahead of 3 for this argument, from what phase
2 cost: nearly every defect found while finishing it was hidden by a guard that could not
fail — an allow-list entry added before the writer it exempted existed; a test whose regex
matched its own header comment; `naude-assembler-closure` blind to a dropped LEAF member (and
its own entry above was wrong in both directions until it was re-measured 2026-09-04, having
already been copied into the umbrella); five skips that could not say why; `apicheck.mjs`
falling past `if (!staged)` on a truthy error object. Phases 3, 4 and 6 all add machinery those same guards would verify, and
phase 6 is a differential whose entire output is a comparison — a wrong instrument there is
worse than no answer.

Phase 5 also owned two things measured in that session: `cancel-in-progress` destroyed SIX CI
runs in one night (the jobs behind a long matrix are the most likely to be cancelled and the
least likely to be re-run deliberately), and the `_doctor`-era discovery that a red which
cannot distinguish "broken" from "not given what I need" carries no information.

**Phase 3** additionally owns the CLI/subcommand rationalisation (folded in 2026-09-03: once
products are first-class in the build target, `--naude` as a flag stops making sense) and, at
its tail, expressing the release ritual as declared steps rather than prose.

**Phase 4** additionally owns: the provider store's key missing platform and arch (one binary
per version, first fetch wins — see the P1 above), the stale/incapable engine check, and
`extractIfNeeded`'s non-atomic write. All three are the same defect — the build does not
check its inputs — and the carve guard shipped 2026-09-04 is the first of them.

**Phase 6** cannot start until phase 4 delivers derived content keys; the umbrella's own
argument is that those keys ARE the layered differential.

### Standing conditions

- **Every skip is understood** (invariant 7, user 2026-09-03): the umbrella cannot close
  while the suite holds skips nobody has accounted for. See the inventory entry above.
- **The suite tests the PINNED provider** (`UPSTREAM_PIN`), exactly, or says why it cannot.
- Upstream is pinned at 2.1.251 on purpose; absorbing 2.1.257 is the first test of the
  rejiggered build system, not a fix to rush.

### The Windows spawn number — MEASURED 2026-09-04, phase 2's last open acceptance

`scripts/spawn-cost-probe.mjs` runs on every Windows build leg (reports only, `|| true`,
gates nothing). It spawns ITSELF via `--worker <units>`, so it measures the multi-call-binary
shape a real extracted step would use, not a `cmd /c echo` microbenchmark.

| host | in-process | spawned | ratio | overhead/call |
|---|---|---|---|---|
| windows-amd64 (10.0.26100, 4 cpu, node 24.20) | 339.2 ms/op | 446.2 ms/op | 1.32x | **~107 ms** |
| windows-arm64 (10.0.26200, 4 cpu, node 24.20) | 312.0 ms/op | 431.2 ms/op | 1.38x | **~119 ms** |
| darwin-arm64 (local, 8 cpu, node 26.3) | — | — | — | ~36 ms |

**Windows costs ~3x what the cheap platform costs per spawn**, and the phase-2 spec measured
one compile step at ~118 ms/module. So a process boundary drawn per MODULE would roughly
DOUBLE the Windows build; drawn per PHASE (what `scripts/merge-step.mjs` actually does — one
spawn for the whole merge, seconds of work behind it) it is noise.

**What it decides, and what it does not.** Per the phase-2 design's §2, this decides
PLACEMENT only, never description: a component reports its own steps, so the same protocol
serves in-process and spawned alike, and the boundary is a deployment choice. The ruling it
supports: **extract a step into its own program when the work behind it is measured in
seconds; keep fine-grained steps in-process.** No existing extraction violates that.

Two reasons the figure is a FLOOR, not a ceiling — both push the true cost up, so they cannot
weaken a "spawning is expensive" reading, only a "spawning is cheap" one:

1. The spawned arm pays NODE's startup per call (`process.execPath`). A real dispatch would
   pay the fused clode's boot instead, which is a different number and has NOT been measured
   here.
2. `stdio: 'ignore'`. Real steps carry protocol lines on stdout, so a real spawn also pays
   pipe setup plus the parent's parse. Not modelled.

The harness's positive control was run before any number was trusted: trivial work → 3409.96x
ratio (overhead dominates), heavy work → 1.03x (overhead vanishes). It responds to the thing
it claims to measure, which was the one failure mode that would have made the exercise
worthless.

**Phase 2 is now COMPLETE on all five acceptance criteria.**

## scc-merge.cjs's lexicalCodeMask has the same check-ordering defect just fixed next door, unproven in the wild (2026-09-04)

**SUPERSEDED — proven live and FIXED 2026-09-12; see "`lexicalCodeMask` phantom-comment
defect: FIXED (phase 5b, task 1, fix round 1, 2026-09-12)" further down this file. Every
"not fixed here, deliberately" / "unproven in the wild" / "treat it as a live risk" below
was accurate when written and is no longer: phase 5b task 1 built the control, the control
fired on the REAL pinned corpus, and the ordering was fixed. Kept, not deleted, because it
is the prediction the fix vindicated.**

Task 9 fixed a CRITICAL in `test/windows-path-ratchet.test.cjs`'s tokenizer (see the
"RESOLVED 2026-09-04" entry above): its `/*` branch checked unconditionally, before the
regex-literal branch, so a genuine regex literal misjudged as division (the inherent
ambiguity after `)`, `]`, or an identifier — ONE example: `fn() /[/*]/.test(x)`, where `)`
makes the heuristic read the next `/` as division, so the SECOND `/` of the char class
`[/*]` reads as a bare `/*` and runs away, deleting every real line after it) destroyed
real code. Verified by execution: `fn() /[/*]/.test(x);\nprocess.env.PATH = 'real site';\n`
stripped to nothing after the first line — the `process.env.PATH` site did not survive.

`libexec/scc-merge.cjs`'s `lexicalCodeMask` (the real SCC-group merger's own lexer, used
to protect string/template/regex/comment bytes from identifier renaming) has the IDENTICAL
ordering: its `//` check is at line 150, its `/*` check at line 154 — both unconditional,
both checked BEFORE the regex-literal branch at line 173 (`if (c === 47 &&
regexAllowed(prevTok))`), and its `/*` scan (line 156: `while (i < n && !(charCodeAt(i)
=== 42 && charCodeAt(i+1) === 47)) i++;`) has no EOF guard either — reaching end-of-source
without a closing `*/` still just clamps `i` to `n` and continues, exactly like
`stripComments()` did before this task's fix. `lexicalCodeMask` is called from inside the
real merger at lines 623, 655, and 714 (`mergeGroup()`'s renaming passes) — this is BUILD
PATH product code, not a test.

If a source module folded into an SCC merge group contains a genuine regex literal shaped
like the one above (a char class or escaped slash immediately after `)`/`]`/an identifier,
with a `*` right after the misjudged `/`), a stray "comment" region gets masked as
non-code. Masked bytes are `mask[i] = 0` ("leave verbatim, do not touch") — so the
practical effect would be a real code span skipping identifier renaming it needed, which
`assertNoRenamedFixedNames()` (scc-merge.cjs) might or might not catch depending on
whether the skipped span happened to contain a colliding name; worst case is a corrupt
merged bundle that is NOT caught until (or unless) something downstream breaks.

**Not fixed here, deliberately.** This review was scoped to `windows-path-ratchet.test.cjs`'s
tokenizer; the merger is real build-path product code, and a change to it needs its own
task, its own regression tests against `test/scc-merge.test.cjs`'s corpus, and its own
review — not a drive-by inside a review of an unrelated test file.

**Unproven in the wild.** `lexicalCodeMask` is not exported from `scc-merge.cjs` (no
`module.exports` entry names it), so it cannot be probed directly the way
`stripComments()` was — proving this fires for real would mean either extracting the
function into a throwaway harness or finding/constructing an actual upstream module whose
minified source happens to contain the trigger shape. Neither was attempted here. This is
structurally IDENTICAL to a defect just confirmed by execution next door, not a fixed
finding — treat it as a live risk in the merger until someone either proves it fires on a
real SCC group or fixes the ordering preemptively.

## Three gates have now scanned an UNPINNED provider — the condition needs a mechanism (2026-09-04)

The standing condition says: **the suite tests the PINNED provider, exactly, or says why it
cannot.** Phase 5 found three separate gates violating it, none of which knew:

1. `test/node-shim-wall-tripwires.test.cjs` — with `CLODE_PROVIDER_BIN` unset it fell through to
   an uncapped resolver, scanned a different carve (`examined 1684` rather than 1839), and
   reported a **VIOLATION** — accusing upstream of reaching a wall it never reached. FIXED: it
   now reads the pin via `pinnedVersion()` and SKIPS on a mismatch, naming both versions.
2. `test/guard-subcommands-gate.test.cjs` — selected the **highest cached** version, not the
   pinned one. On this box that meant checking our `SUBCOMMANDS` list against 2.1.252 while
   `UPSTREAM_PIN` said 2.1.251. Worse, CI's new seed populates the pin, so CI and a dev box
   would have reported on different bundles with nothing saying so. FIXED the same way.
3. `test/dep-closure.test.cjs` — its integration test is **still not pin-locked**; it scans
   whatever provider resolution hands it. NOT fixed (phase 5 pinned `CLODE_PROVIDER_BIN` for one
   deterministic comparison rather than redesigning the gate mid-round).

**Why this is an entry and not three fixes.** Each was found by accident, while doing something
else, and each looked fine until someone asked which artifact it actually read. The versions on
a dev box drift constantly — this machine's cache holds 2.1.246/.250/.251/.252/.257 and its
native Claude Code auto-updated 2.1.257 → .261 *during* this session. So "whatever resolution
hands me" is a different bundle on every box and every week, and a gate that does not name its
input is reporting on something nobody can reproduce.

**The mechanism worth building** (phase 4 owns provider-store keying, which is the natural
home): make pin-resolution the only way a test can obtain a provider — a shared helper that
returns the pinned carve or a SKIP with both versions named — so a gate cannot silently scan
something else. Until then, every new gate that reads a carve is a fourth instance waiting to
happen. `test/provider-resolve.cjs`'s `pinnedVersion()` is the existing half; what is missing is
making it the ONLY door.

## Item 6's coverage half waits on phase 4's declared edges (2026-09-04)

Phase 5's item 6 (`test/tjs-legs.test.cjs`'s `'every leg that carves inside a guest VM
accounts for its zstd'`) now has a can-it-fail control: `'zstd-row accounting mechanism: the
"minimised" check fires when the row is ABSENT or WRONG'`, in the same file, proves the
`ZSTD_INFLATE_CALL` pattern the gate depends on actually discriminates — it goes red against
synthetic source with the decompression call removed, and again against a same-function
different-argument near-miss. That is the WHOLE of what phase 5 owns for this item.

**What is deliberately still missing: the coverage half — an actual in-guest carve that
exercises this for real**, the way CI run 33241941716 caught the original haiku-x64/
netbsd-sparc breaks. Today's control proves the SOURCE-TEXT SCAN can fail; it does not run a
guest VM, and this file's own earlier entry ("No CI leg carves a zstd row in a guest any
more", 2026-08-29) already recorded why: since `scripts/make-min-provider.cjs` decompresses
zstd rows on the runner, no CI leg carves a compressed row inside a guest at all, so there is
nowhere left for an in-guest exercise to run against today's shape.

**This is a dependency, not a budget deferral.** The in-guest carve this coverage half needs
rides on `stage-provider.mjs`'s minimisation, which **phase 4's declared-edges work
reworks**. Building an in-guest exercise against today's `stage-provider.mjs` would mean
writing it again the moment phase 4 lands — the one deferral reason this project accepts.
Phase 4 is where this waits: once declared edges reshape minimisation, re-examine whether a
guest-carve exercise belongs beside `ZSTD_SOURCE`'s 'minimised' entries, or whether the
reshaped edges make the question moot a different way.

## Item 7's coverage half waits on phase 6's control-free comparison (2026-09-04)

Phase 5's item 7 (`test/fidelity/interactive-live-turn.test.cjs`, "the standing 'live TUI
turn is the acceptance' gate") had a real honesty bug: its own header comment already said
"If native cannot complete the turn (logged out, offline, model non-compliant) BOTH tests
skip rather than fail" — but the code only implemented that for the first test
('native renders a live streamed response'). The second test ('quaude renders the live
streamed model response in the TUI') checked only the coarse `SKIP` (no CLODE_LIVE_ONLINE
opt-in / no render gate / no tjs binary / no provider / build failure), so a missing or
logged-out native reference produced a HARD FAILURE on quaude's own login check — a red
indistinguishable from quaude actually breaking Keychain parity (the exact P0 this test was
built to catch; see `quaude-never-reads-keychain.md`). Fixed by adding `NO_REFERENCE_SKIP`,
the strict subset of the existing `NATIVE_SKIP` that means "a reference COULD have been
established but wasn't" (native didn't run, version drift, or it couldn't complete the live
turn) — as distinct from "no native binary exists on this platform at all" (NetBSD, the
BSDs, …), which by design still lets quaude's own turn stand on its own. Only the former now
also skips the quaude test. Preconditions (native on PATH, a logged-in profile) now produce a
SKIP naming the reason; the P0 detection itself — quaude failing to authenticate while a
CONFIRMED-GOOD native reference succeeded — still hard-fails, unchanged.

**What is deliberately still missing: the coverage half — a control-free variant that runs
where there is no native reference at all.** The spec (`docs/superpowers/specs/
2026-09-04-phase5-gates-that-can-fail-design.md`, §3.7 item 7) names this directly: native
Claude Code structurally cannot run on NetBSD, Mavericks, Haiku, illumos or sparc — the
platforms whose mechanisms differ most from macOS/Linux, and exactly where a rendering
regression is likeliest to hide. Today, on those platforms, the quaude test still runs and
is judged on its own merits (renders 42, is logged in, shows no shim-error markers) — but
that is answer-shaped judgement already built into this file, not a general mechanism.

**This is a dependency, not a budget deferral.** Making that judgement rigorous — reliably
asserting the target renders an answer that is provably absent from the prompt, without a
reference host to diff against — is an acceptance-test DESIGN problem, and it lands with
**phase 6**, whose whole business is comparisons that work without a reference host. Phase 5
does not own comparison-design; it owns whether a gate can fail, and the answer for this
gate — now — is yes, honestly.

## Guard migration is proven per-FILE; the individual claims inside are not (2026-09-05, final whole-branch review of phase 5)

`defineGuard`/`guardTests` (`test/guard.cjs`) and the population sweep that ratchets what has
NOT been migrated onto it (`test/guards-population.cjs`, `UNMIGRATED_BASELINE`) both operate
at the granularity of a FILE: a `*.test.cjs` file counts as "migrated" the moment it contains
one `defineGuard()` call anywhere in it, and `guards-population.cjs`'s sweep then stops
looking at that file's OTHER `test(...)` bodies entirely — they are exempted by the file
having a guard in it, not by having been individually wired through `checkControl`/
`checkGate` themselves.

**The worked example, found while fixing this phase's own review findings:**
`test/release-gate-globs.test.cjs` registers the `release-gate-globs` guard (migrated, one of
the six-then-more this phase counted as done) — and, in the SAME file, ships a second test,
`'the release job gates on the full suite, and both workflows share ONE definition'`
(lines 203-219), asserting FOUR separate `assert.match`/`assert.ok(!...test(...))` regex
checks against `release.yml`/`ci.yml`/`suite.yml` with no `defineGuard`, no `control()`, and
no floor. Every property phase 5 exists to guarantee — "this check has a proven positive
control", "zero is BROKEN, not a pass" — is simply absent for those four assertions. They are
invisible to `guards-population.cjs`'s ratchet not because they are safe, but because the
FILE they live in already contains an unrelated migrated guard.

**So the phase's own headline number overstates what it proved.** "102 → 82 unmigrated"
counts files, and a file this project can point to right now (release-gate-globs.test.cjs)
demonstrates that "migrated" and "every scanner-shaped assertion in this file has a proven
control" are different claims — the sweep can only ever prove the first. This is not
specific to that one file; it is a property of doing migration at file granularity at all,
and it should be read as a caveat on the whole phase's reported progress, not a defect in
one test.

**Not fixed here, deliberately** (documentation, per the final review's own instruction) —
fixing it for real means either (a) migrating every individually-scanner-shaped assertion
onto its own `defineGuard`, one guard per property rather than one per file (a large,
mechanical but not hard follow-up), or (b) teaching `guards-population.cjs`'s classifier to
work at the `test(...)`-body granularity instead of the file granularity, which is a real
redesign of the sweep's own unit of measure. Either is its own task; recorded here so the
gap is legible to whoever reads this phase's numbers next, rather than re-discovered by
someone assuming "migrated file" already meant "every claim in it is proven".

## The real build-path gates have no floor, no control, and no verdict vocabulary — phase 5's natural successor (2026-09-05, final whole-branch review of phase 5)

Phase 5 built `defineGuard`/`guardTests` and made it structurally hard to add a NEW
unaccountable guard — but only inside `test/`. `guards-population.cjs`'s migration sweep
walks `test/**/*.test.cjs` exclusively (`discoverTestFiles`, `TEST_DIR = __dirname`), because
that is where `node:test` lives and that is what a `*.test.cjs` file even means. Nothing in
phase 5 reaches the gates that run for real, at build time, inside `clode build` itself:

- `assertNoUnknownBareSpecifiers` (the dep-closure gate, `libexec/clode-fuse.cjs`) — the
  exact mechanism whose escape-blindness shipped a P0 twice before this phase started
  (`upstream-deps-become-our-deps.md`, `dep-closure-derived-not-declared.md`).
- `libexec/scc-merge.cjs` — the cyclic-group merger itself, whose `lexicalCodeMask` has the
  IDENTICAL check-ordering defect just fixed in `windows-path-ratchet.test.cjs`'s tokenizer,
  unproven in the wild (see "scc-merge.cjs's lexicalCodeMask..." above, this same file).
- `libexec/host-provision.cjs` — decides what gets fetched/verified onto a host and how; the
  origin of the "hang writing to disk" P0 traced to a silent pure-JS SHA-256 verify under tjs
  (`clode-fetch-verify-extdep.md`).
- `libexec/target-update-check.cjs` — the gate a stale engine template needs to refuse a
  build with (`stale-engine-template-breaks-builds.md`).

Every one of these is a scanner: it reads an artifact, derives a finding, and reports pass or
fail — the exact shape `defineGuard` exists to discipline. None of them has a recorded
positive control, a floor, or phase 5's OK/VIOLATION/BROKEN/CANNOT_FAIL/SKIP vocabulary; each
reports through its own ad hoc pass/throw, the same "many gates, and nothing gates the gates"
shape the ★★★ entry above named for the TEST suite, one layer under it, sitting exactly where
the shipped harm actually lands — a broken `clode build`, not a red `npm test`. This is the
natural successor to phase 5, not a fix folded into it: `defineGuard`'s registry, its
`checkControl`/`checkGate` verdicts, and a population sweep for it all assume `node:test` as
the harness (`guardTests()` calls `require('node:test').test`), which a build-time gate
running inside `clode build` does not have — bringing these gates under the same discipline
means either giving `defineGuard` a harness-agnostic verdict path (usable from both
`node:test` and a plain build-time assertion) or building its equivalent for the build path
specifically. Sized and scoped like its own phase, not a task inside this one; recorded here
so it is not lost the way the umbrella phase-list (`### Phase order`, above) would otherwise
make it look like phase 5 already covers "gates that can fail" in full.

### Phase 5b CLOSED — and what it measured but did not control (task 5, 2026-09-12)

Four of the gates named above now have a registered guard under `test/build-gates/`
(`lexical-code-mask`, the `dep-closure-*` family, `host-provision-*`, `target-update-*`), and
two of them found a live defect the moment they were controlled. Task 5 closed the
population so the FIFTH is not found by accident: `test/guards-population.cjs` now carries a
**production-gate sweep** over `libexec/` + `scripts/` alongside the existing test sweep. It
classifies a file as a build gate when it derives a verdict from text AND refuses (throws, or
exits with a non-zero ARGUMENT), derives "which guard controls which gate" from the literal
`require('../../libexec/x.cjs')` in each registered `test/build-gates/` guard, and ratchets on
`UNCONTROLLED_GATE_BASELINE` — plus `GATE_SHAPED_FLOOR`, so a FALL in the uncontrolled count
cannot be reported as progress when the real cause is the classifier going partly blind.

**SPEC ERRATUM, for anyone reading the phase-5b spec.** Its §3 says "Registration puts them
in the population sweep automatically; Task 11 already extended it to walk `libexec/` and
`scripts/`." That conflates two sweeps. Task 11 extended `discoverCliQuoteScanFiles()`, which
feeds ONLY the escape-blind CLI-quote detector; the MIGRATED/`UNMIGRATED_BASELINE` sweep runs
off `discoverTestFiles()` and is scoped to `test/*.test.cjs` by design. Before task 5, a
brand-new un-controlled build gate under `libexec/` was reported by nothing at all.

**MEASURED, not controlled — the standing to-do.** 76 production files in scope, **34
gate-shaped, 4 controlled, 30 uncontrolled** (2026-09-12, after fix round 2). That number is a
floor under "no NEW gate appears unseen", NOT a to-do list of 30 guards to write: the
classifier has no input half (see below), so some of the 30 are false positives that become
`PRODUCTION_GATE_EXCLUSIONS` entries, with a reason, as each is checked by hand. The
biggest-consequence names in the list, for whoever picks this up: `libexec/clode-fuse.cjs`
is already controlled, but `scripts/apicheck.mjs` (the API-surface gate),
`libexec/extract-claude-js.cjs`, `libexec/bun-shim.cjs`, `scripts/build-tjs.cjs`,
`scripts/bundle-shape.mjs`, `scripts/templates-drift.mjs` and `scripts/upstream-drift-check.mjs`
all refuse builds today with no positive control.

**WHAT "4 CONTROLLED" MEANS — the granularity, stated so the successor inherits the right
claim (fix round 2, 2026-09-12).** It means **4 FILES HAVE AT LEAST ONE CONTROLLED GATE**. It
does NOT mean 4 gates are controlled, and it does not mean those files' other refusals are
proven able to fail. The unit of control is a FILE; the unit of a gate is a THROW-SITE.
Measured 2026-09-12 (`grep -c 'throw new Error(' libexec/clode-fuse.cjs libexec/scc-merge.cjs`
plus a per-function attribution): `libexec/clode-fuse.cjs` has **17** throw-sites and
`libexec/scc-merge.cjs` **7**; of those 24, exactly **3** are tripped by a registered guard's
control — `computeDepClosure`'s missing-package throw, `assertClosureMatchesLockfile`'s
version-mismatch throw, and `assertNoUnknownBareSpecifiers`' unknown-specifier throw, all in
`clode-fuse.cjs`. **21 of the 24 remain uncontrolled.** `scc-merge.cjs`'s controlled gate is
`lexicalCodeMask`, which refuses by RETURNING a mask its caller acts on rather than by
throwing, so NONE of its 7 throw-sites has a `defineGuard` control — including
`assertNoRenamedFixedNames`, which that file's own comment calls **"THE RATCHET"** and records
as having caught a shipped merge that renamed 336 property keys. (It is exercised with a real
`assert.throws` by `test/scc-merge.test.cjs:577-583`; it is simply not a control in the phase-5
sense, so `checkControl`'s "can this fail" question is never asked of it. That is the most
consequential single site on the uncontrolled list.)

**Two derivation fixes from round 2, so the numbers above mean what they say.** (1)
"Controlled" was derived from a `require()` literal ALONE, which proves a guard LOADS a module,
not that it CONTROLS it: `test/build-gates/host-provision-gates.test.cjs` requires
`libexec/clode-hosttools.cjs` only to borrow `hosttools.findTool` as a fixture, and that made
it "controlled". It moved no count only because `clode-hosttools.cjs` is not gate-shaped — add
one `throw new Error(` to it (demonstrated) and it becomes gate-shaped AND "controlled" in the
same instant, and the ratchet reports a clean run for a NEW uncontrolled gate. The derivation
is now **named AND itself gate-shaped**, and the controlled set is PINNED to exactly those four
modules by a test, so a fifth one goes red and a human decides which it is. (2)
`GATE_SHAPED_FLOOR` was set to 28 against a measured 34 — a "cushion" that caught the
catastrophe (34 -> 8) and missed the EROSION (34 -> 29, e.g. losing `.matchAll(` from
`PRODUCTION_VERDICT_EXTRA`), which is the shape regressions actually arrive in. It is now the
measured 34, per the phase's own Global Constraint that a floor equals the measured count.

**TWO BLIND SPOTS, stated rather than discovered later.**
1. *No input half, on purpose.* Reusing `readsArtifact()` (READ_CALLS && REPO_ROOTED) was
   tried and measured: it does not see `libexec/scc-merge.cjs` (its artifact is a caller-
   supplied source string) or `libexec/target-update-check.cjs` (its artifact is an HTTP
   response) — two of the four gates phase 5b already controls. A production gate's artifact
   can be a file, a network response, a subprocess's output, or a blob its caller already
   read, and the last is not distinguishable from any pure function by source text. So the
   classifier keys on "derives a verdict AND refuses" and pays the cost in false positives.
2. *A gate whose refusal happens in ANOTHER file is invisible.* `GATE_REFUSES` matches
   `throw new Error(` and a `process.exit`/`process.exitCode` whose argument is not literally
   `0` (or absent). A module that only RETURNS a verdict, with the caller that acts on it in a
   different file, is not followed across that `require()` edge — the same limitation the
   escape-blind detector records for its `ALREADY_FIXED` exemption. **The first cut of this
   entry claimed "nothing in libexec/ or scripts/ has that shape today"; that was a claim, not
   a measurement, and the reviewer found a live counterexample within the file:**
   `scripts/apicheck.mjs` refused with `process.exit(runGate())` — a COMPUTED status — and the
   classifier reported `"pattern-matches but never refuses"`, which was factually wrong about a
   file whose own header calls itself a gate. Fixed by widening to a non-zero exit ARGUMENT
   (cost: exactly 2 files, `apicheck.mjs` + `libexec/naude-entry.cjs`). No SPLIT gate
   (return-here, refuse-there) has been found — but "not found" is where the search stopped,
   not proof of absence.

**Extensions:** the walk covers `.cjs`, `.mjs` AND `.js`. The first cut omitted `.js`, which
put `libexec/quaude-fuse.js` (the fuse worker `libexec/clode-fuse.cjs` spawns) and
`libexec/graph-meta.js` (spawned from `libexec/clode-extract.cjs`) in NO bucket at all — not
gate-shaped, not excluded, not counted. Neither is gate-shaped today, which cost zero gates and
is exactly why the hole was invisible.

**The split point, recorded and deliberately NOT taken:** `test/guards-population.cjs` is now
~870 lines carrying two sweeps. Splitting it today would either duplicate the shared vocabulary
(`PATTERN_MATCHES`, `isMigratedSource`, `REPO`) or invert the dependency, so the reviewer
recommended against it. **Do it when a THIRD sweep arrives**, not before. (Fix round 2 did take
the ONE mechanical part: `stripLineComments` and `discoverFilesByExt` were duplicated verbatim
across this file and two `test/build-gates/` guards, and now live once in
`test/source-scan.cjs` — the `test/throws-as-findings.cjs` precedent. Three copies of an
approximation is three places for it to drift apart silently.)

**Scope skip, not an exclusion:** `libexec/node-shim/` is walked past. It is the TARGET's
Node-API emulation — fused into quaude, run on the end user's machine, never a gate during
`clode build` — and its 8 gate-shaped files are all `throw new Error('ENOENT...')`-style
Node-semantics emulation, one fact about a directory rather than eight about eight files.


## "Required gate" does NOT mean branch protection here (user, 2026-09-05)

Phase 5's item 4 asked to make `native-builder-oracle` "a REQUIRED gate whose failure says the
SHIPPED ARTIFACT is broken". Implementing it surfaced that `main` has **no branch protection and
no rulesets** — `gh api .../branches/main/protection` returns 404, `.../rulesets` returns `[]` —
so no CI check on this repo is required, for any job.

**Decision: that is intentional and stays.** The user works push-to-main wherever that is
possible, and branch protection would take that away to buy a property this project does not
need. So "required" in item 4 never meant GitHub-required, and nobody should re-derive that
conclusion from the word.

**What item 4 actually wanted, and now has:** a failure of that job must SAY what it means. It
had been sitting as one anonymous red among twenty-two, which is how the zstd carve break went
unread for a day. It now emits `::error title=SHIPPED ARTIFACT BROKEN::` plus a step-summary
banner — but only when the `build` or `oracle` step itself failed. Any other failure (checkout,
artifact download, a dep install) emits a quieter `::warning:: could not verify the shipped
artifact`, because a banner that cries wolf on an npm timeout trains people to ignore the one
signal the item exists to make loud.

If a future reader wants a check that genuinely cannot be merged past, that is a different
request with a real cost (no more push-to-main) and needs asking, not assuming.


## Full local cross builds — the umbrella's postscript (user, 2026-09-05)

**Direction:** full local cross builds are the next big thing AFTER the cross-build umbrella
closes, not a phase inside it. Recorded so it is not smuggled into a phase and not lost.

**Why it matters, in the user's framing:** in the absence of full local cross builds, CI is our
most thorough feedback loop — so it earns real effort on latency, and every second shaved off
it is bought back on every push. That is the standing justification for the CI-ordering work
being done now (the tjs matrix split, and the engine-artifact/smoke split below), which would
otherwise look like polish.

**What we learned today that bears on it:** measured on this box, the suite is NOT
NFS-read-bound — two runs from a local-disk copy landed at 382s and 391s against an 18-run NFS
distribution of min 350 / median 367 / mean 386. NFS metadata cost is real and brutal (300
creates: 44,305ms NFS vs 106ms local, 418x) but the suite reads a small working set repeatedly
and the client caches it. So a local-materialisation path should NOT be built on the suite's
account. `clode build` is a different question — it is create-heavy, which is exactly where the
418x lives — and deserves its own measurement before anyone assumes either way.


## SETTLED: cancellation follows the ModernMavericks family rule (2026-09-12)

**Supersedes "REOPENED: never-cancel-on-main may not be the right trade" (user, 2026-09-05).**
The user's direction: this decision should match what `../mavericks-shipyard` prescribes. It
now does, in both halves.

**The family rule, stated by the same maintainer in shipyard's release-concurrency design and
enforced by `scripts/check-family-conventions.sh` check 1b:**

> Push-to-main builds should override each other. Release builds should not. Every release
> build that succeeds should publish.

Its reasoning, which is what makes it transfer rather than just being a setting to copy: a
push run is **build feedback**, and only the newest commit's feedback is worth having; a
publishing run is **work that cannot be recreated by pushing again**, so it must never be
discarded.

**How it lands here, and why the two files get opposite answers.** clode's split is cleaner
than the family's: `ci.yml` cannot publish at all (it runs on push/PR/dispatch), and
`release.yml` publishes only from a `v*` tag or a dispatch. So:

- `ci.yml` — `cancel-in-progress: true`, unconditional. It is the feedback half, on `main` as
  much as on a PR branch. This REPLACES `${{ github.ref != 'refs/heads/main' }}` (2026-09-04).
- `release.yml` — `group: release-${{ pull_request && github.ref || github.run_id }}`,
  `cancel-in-progress: ${{ pull_request }}`: every tag push and every dispatch is alone in its
  group, so it is never queued behind a sibling and therefore never evictable. It previously
  declared NO `concurrency:` at all — which behaves correctly today by default, but states no
  property and survives no edit. The `pull_request` arm is unreachable in this repo and is
  kept verbatim anyway, so the shape stays the family's rather than a local re-derivation.

**Why the 2026-09-04 evidence no longer decides it.** That evidence was real and is not being
denied: `194e237`, a BACKLOG.md-only commit, cancelled the run carrying `06c6c96`, a real test
fix. What changed is both sides of the scale. A cancelled run now loses far less — after the
fast/slow matrix split and the full-smoke decoupling the suite reports at ~1-3 min and the
fast legs at ~6, against a 113-minute time-to-oracle before. And never-cancel turned out to
have a measured cost of its own: consecutive pushes queue behind each other's 22 qemu legs —
run `33970393353` sat `pending` until `33966318977` was cancelled by hand (2026-09-05).

**KNOWN RESIDUAL — recorded, not papered over.** `concurrency` is resolved at RUN level,
before the `changes` gatekeeper can see the diff. So a docs-only push still cancels a code
run, and because it then skips the heavy matrix, the run that replaces it carries LESS signal.
That is the one place the family rule's premise — "the newer run reproduces the feedback" —
is false here, and it is exactly the 2026-09-04 case. Recovery is `gh run rerun <id>`.

**The fix that would remove the residual, and why it is NOT taken.** Workflow-level
`paths-ignore`: a docs-only push then creates no run, so there is nothing to cancel. It is
rejected on this repo's own doctrine, not on the weak objection recorded on 2026-09-05 ("main's
head would have no CI result" — weak, because a docs push does not change the code). The real
objection is the failure mode: `paths-ignore` is a DECLARED path list, and a wrong entry means
a CODE push creates no run at all, silently. `changes` is the derived, fail-open equivalent
(`code=true` on any error, in two independent layers) and defaults to RUNNING the matrix.
Trading a fail-open classifier for a fail-silent list is the wrong direction, and
`dep-closure-derived-not-declared` / `ci-job-is-to-tell-the-truth` both say so.

**What would re-open this:** observing the residual bite — a docs-only push killing a code
run's matrix signal in practice. The answer then is not `paths-ignore` but a derived group
(the classification would have to be available at run level, which today it is not), or
accepting the manual re-run as the cost.

## `lexicalCodeMask` phantom-comment defect: FIXED (phase 5b, task 1, fix round 1, 2026-09-12)

`libexec/scc-merge.cjs`'s `lexicalCodeMask` — the merger's own lexer, deciding which bytes
are a real, renameable binding vs. a string/template/regex/comment body — had the SAME
defect shape phase 5 fixed in `windows-path-ratchet`'s tokenizer: its `/*` branch was checked
UNCONDITIONALLY, before the regex-literal branch, so a regex literal misjudged as division
(`regexAllowed(prevTok)` false — e.g. immediately after `)`/`]`/most identifiers) whose body
contains `/` immediately followed by `*` opened a phantom block comment that ran to the next
real `*/` or EOF, masking real code as non-code. Three call sites, unchanged by the fix:
`libexec/scc-merge.cjs:663`, `:695`, `:754` (originally `:623`/`:655`/`:714` before this
fix's own comment block shifted every later line down by 40).

**Confirmed LIVE before the fix** (`/opt/pkg/bin/node --test test/build-gates/lexical-code-mask.test.cjs`,
2026-09-12): `lexicalCodeMask('fn() /[/*]/.test(x);\nvar realName = 1;\n')` masked the
`realName` identifier as 0 (non-code), not 1. In the merger this was worse than a blind test:
a colliding name inside the masked region would be renamed with no error, which can emit a
corrupt merged bundle.

**FIXED**: the same EOF-backoff `test/windows-path-ratchet.test.cjs`'s `stripComments()`
applies at its own `/*` branch — when no closing `*/` is found before EOF, back off and treat
the single `/` as ordinary punctuation instead of committing to a comment (every source this
masks is syntactically valid JS, so a genuine unterminated block comment cannot occur —
reaching EOF unclosed is proof the `/*` was inside a misjudged regex literal, not a real
comment). `MERGER_VERSION` bumped `12` -> `13` (a cache entry from before this fix must be
recomputed, on principle — see the comment at that constant for why the corpus-invariance
proof below does not make the bump optional). `test/scc-merge.test.cjs` re-run: 37/37 pass.
`test/quaude-fuse-merge-apply.test.cjs` SKIPS on this box for want of a tjs binary (named
here, not glossed) — that gap is covered by the tjs-engine CI legs this phase's acceptance 6
requires, not by anything run locally for this fix.

**RESIDUAL, not closed by this fix** (same shape as `windows-path-ratchet`'s own admitted
one): if a REAL, unrelated `*/` exists LATER in the same source, the phantom still pairs
with THAT instead of backing off at EOF, and the EOF-backoff alone cannot tell the
difference. `windows-path-ratchet` closes the equivalent gap with a second guard
(`windows-path-ratchet-regex-division-ambiguity`); `lexical-code-mask-phantom-comment`
(below) plays that role here, and is not gated on finding a well-formed regex-literal close
— it flags any `/` lexicalCodeMask reads as ordinary code that is followed by a raw `/*`
before the next real closing `/`/newline/EOF, matching `windows-path-ratchet`'s own
`onAmbiguousSlash` hook (which does the same, for the same false-negative reason).

**The corpus-invariance proof (the load-bearing check for this fix):** `lexicalCodeMask`
was run over every one of the pinned claude-code 2.1.251 carve's 1,839 real module sources
(`~/.cache/clode/2.1.251/graph.json`) TWICE — once against the pre-fix function (recovered
via `git show`), once against the post-fix one — and the resulting `Uint8Array` masks were
compared byte-for-byte. Result: **1,839/1,839 identical, 0 differing.** This is expected
(the earlier "zero of 1,839 trigger this shape" measurement predicted it) and is the actual
evidence, not an assumption, that the fix changes nothing observable about today's real
bundle while closing the defect for any input that does hit the shape (in the corpus or
not). The `lexical-code-mask-phantom-comment` guard
(`test/build-gates/lexical-code-mask.test.cjs`) makes the "0 across 1,839" half of that a
standing, re-checked-every-run measurement, with a control proving it CAN detect the shape
and `floor: 1839` (today's real module count) so a future upstream bump that shrinks the
corpus is itself visible.

**The repro** (`test/build-gates/lexical-code-mask.test.cjs`) is now a plain, green
regression test — not a `todo` marker — and goes red again if the EOF-backoff is ever
removed or narrowed.

## `lexicalCodeMask`'s EOF-backoff is O(m·n) on a pathological input — filed, deliberately NOT fixed (2026-09-12, final whole-branch review of phase 5b)

`libexec/scc-merge.cjs:163` — the `/*` branch's EOF-backoff (added by phase 5b task 1's fix
round 1, and correct: it is what closes the phantom-comment defect) scans forward to a real
`*/` and, on failing to find one, treats the `/*` as ordinary code and backs off ONE character.
So every `/*`-looking pair AFTER the file's last real `*/` rescans the whole tail: m such
occurrences cost O(m·n).

**Why it is filed and not fixed.** Zero firings on the real corpus — proven, not assumed: the
masks before and after the fix are byte-identical on the pinned carve, so the backoff never
runs today. Against that, this loop is exactly the one the file's own header records as having
been hand-optimised to `charCodeAt` arithmetic because it once took two minutes under `tjs`,
and this fix wave is test-side and documentation only. Changing the REAL MERGER for no
measurable benefit at the end of a phase is the trade the phase's own doctrine refuses.

**The fix when someone wants it**, so it need not be re-derived: memoise the position of the
last real `*/` (a single `lastIndexOf('*/')`, or a one-time scan recording it) and, once `i`
is past that point, skip the forward scan entirely — every subsequent `/*` is known to be
unterminated. That makes the whole pass linear again and does not change a single verdict.
The covering regression test (`test/build-gates/lexical-code-mask.test.cjs`) already goes red
if the backoff is removed or narrowed, so this refactor has its control waiting for it.

## The production-gate sweep's walk→classify→map→ratchet path is proven only by a one-off demonstration — the successor's first item (2026-09-12, final whole-branch review of phase 5b)

`test/guards-population.cjs`'s production sweep is tested in pieces: `ratchetUncontrolledGates`
against synthetic counts, `classifyProductionFile` against synthetic source strings,
`modulesNamedByGuard` against a synthetic guard body. What is NOT a standing test is the whole
path end to end — walk the tree, classify each file, map the controls, run the ratchet — on a
tree that actually contains an offender. That was proven ONCE, by hand, during task 5 (the
synthetic-offender demonstration, which is also what found the hoisted-regex blind spot in
`PRODUCTION_VERDICT_EXTRA`), and a demonstration that ran once is not a regression test. The
same hole, in the same words, that phase 5 closed for the guards it migrated.

**What it needs:** parameterise `discoverProductionFiles(root)` and
`sweepProductionGates({ root })` — both hard-code `REPO` today — so a `fs.mkdtemp` fixture can
plant a realistic un-controlled gate (a hoisted-const regex plus a `throw new Error(`) in a
temp `libexec/`, run the sweep against THAT root, and assert the ratchet reports it ABOVE
baseline. No write into the real `libexec/` ever happens, and the demonstration becomes
permanent. Do it before writing the fifth control, not after: it is the mechanism that says
whether the fifth one was counted.


## The daily drift job cannot see the thing that is actually broken (2026-09-12)

**What prompted this (user):** "If we bump the drift pin does that maybe make us forget we are
completely unable to carve recent Claude Code?" The answer was yes, and worse than the question
assumed — so the near half was fixed the same day and the far half is filed here.

**Fixed 2026-09-12, so it is not what this entry is asking for:**
- The Remote Control gate anchor was re-pinned for upstream's 2.1.270 shape, where every reason
  is wrapped by a local `(e)=>({reason:e,orgPolicyDenied:!1})` helper. **The regex was the small
  half; the injected VALUE was the load-bearing half.** The consumers are now
  `(await gate())?.reason ?? null` and `if(C.orgPolicyDenied)…{message:C.reason}`, so the old
  bare-string gate-off would have been truthy with an undefined `.reason` — the notice vanishes
  and Remote Control reads as AVAILABLE. A regex-only re-pin would have turned the job green
  while shipping exactly the silent no-op the anchor exists to prevent. Proven both ways against
  the real 2.1.270 darwin-arm64 bundle and the pinned 2.1.251.
- `upstream-drift.yml`'s `boots` job said "does a quaude built from the newest bundle still
  BOOT?" — but `build-leg` installs `@anthropic-ai/claude-code@$(cat UPSTREAM_PIN)`, so since
  2026-09-01 it has been booting the PIN. The comment was corrected rather than the behaviour,
  for the reason in the next paragraph.
- Every green drift run now prints what it does NOT prove (`scripts/lib/carve-gap-note.mjs`,
  pinned by `test/carve-gap-note.test.cjs`), and `UPSTREAM_PIN` carries the measured evidence
  per version instead of a one-line assertion.

**STILL OPEN — the engine-backed carve probe.** Nothing in CI asks "can `clode build` carve
newer than the pin yet?", and that is the question whose answer decides when the umbrella's
"absorb 2.1.257 as the first test of the rejiggered build system" can begin. It cannot simply
be the `boots` leg pointed at `next`: that leg would be red from birth, which
`upstream-drift-check.mjs`'s own header already rejects as the reason `--strict` is not the
check there.

**The shape it wants, from the Haiku probe in the same workflow** ("Green means 'nothing we
could do about Haiku today', NOT 'Haiku is fine'… Red means an action just became possible"):

- attempt a real carve+merge of `next` using an engine — the `boots` leg already builds one and
  publishes it, so a `needs: boots` job can consume the artifact rather than pay for a second
  engine build;
- assert the KNOWN-BLOCKED state: green when it still fails **at the recorded site for the
  recorded reason** (the SCC merge, QuickJS "invalid property name");
- red on EITHER change — it started working (absorb now) or it fails somewhere new (fresh
  breakage). Distinguish "the build step ran and failed" from "the job never reached the build
  step", or infra flake will read as "still blocked" and the day it starts working will pass
  unnoticed — the same green-that-hides shape this whole entry is about.

**Why it was filed rather than built:** the wiring cannot be proven locally (no engine on the dev
box; `engine=unknown` in every suite stamp here), and shipping an unverifiable CI job that
reports a comforting green is precisely the defect being fixed. It wants a runner to develop
against, which makes it its own piece of work rather than a tail on this one.


## PHASE 3 DECIDED — the surface, the vocabulary, and what is out (user, 2026-09-12)

Spec: `docs/superpowers/specs/2026-09-12-phase3-one-entry-point-design.md` (gitignored by
project convention, so the DECISIONS live here). Phase order is now
**1 → 2 → 2.5 → 5 → 5b → 3 → 4 → 6**, and this is phase 3.

### The surface

    clode build [quaude | naude]          [--target P] [--out PATH]
    clode fetch [claude | node]           [--target P]
    clode read-anthropic-tea-leaves
    clode --version | --help

    node scripts/stage0.mjs bootstrap     [--target P] [--out PATH]   # checkout only

`--target` means ONE thing in every line. `--naude` and `--self` are gone. Two classes, and
every positional is drawn from exactly one: **products** (what clode builds) and
**ingredients** (what clode fetches).

### The vocabulary, and why each word

- **`ingredient`** replaces the invented `provider`. NOT coined here:
  `mavericks-shipyard/INGREDIENTS.md` already means exactly this class — "everything baked
  into what shipyard ships … the things its scripts fetch on a consumer's behalf", one pin
  and one bump story per row. The two repos now share a word instead of each keeping a
  private one. The ingredients are `claude` (what quaude is built from) and `node` (the
  pinned runtime naude additionally embeds).
- **`blobulate`** replaces `fuse`, for BOTH products, and the reason is measured rather than
  aesthetic: **`fuse` is Node SEA's word for a sentinel MARKER, not an operation.**
  `scripts/build-naude.mjs:471` calls
  `postject.inject(bin, 'NODE_SEA_BLOB', blob, { sentinelFuse: 'NODE_SEA_FUSE_fce680…' })`.
  We promoted a flag's name to the name of the whole step, which is why it never explained
  itself to anyone. The two products share no mechanism — postject INJECTS naude's blob,
  quaude's is APPENDED as a canonical-LE trailer — so the general word has to cover both,
  and what they genuinely share is that each produces a payload blob. It also greps clean,
  which no English candidate does. Mechanism words stay true where used: inject/blob on the
  naude path, append/trailer on the quaude path.
- **`read-anthropic-tea-leaves`** replaces `watch` (and beat the vaguer `check`, which the
  user rejected: "way vague"). The command greps a changelog for phrases like "requires the
  native binary" and infers Anthropic's direction of travel — warn-only, never
  authoritative, never downloads the ~240MB binary. `check` implies a yes/no answer from a
  source of truth; this name states the actual epistemic status, and being a sentence among
  terse verbs is a feature: it differs in kind.

File renames: `libexec/clode-fuse.cjs` → `clode-build.cjs` **plus an extracted
`libexec/clode-blobulate.cjs`** (user, 2026-09-12: the orchestrator keeps `build`, and the
step comes out into its own module, so the coined word names a module whose whole job it is
rather than surviving only in prose), `libexec/quaude-fuse.js` → `quaude-blobulate.js` (its
header is the canonical definition of the coined word), `.github/actions/cross-fuse/` →
`cross-blobulate/`, four tests + one Dockerfile follow.

**Where the seam is, measured:** `clode-fuse.cjs` is 2,068 lines doing at least five jobs —
the dep-closure gate family (`:104-584`), target smoke/attest/sign (`:642-875`), argv parsing
(`:901-961`), manifest/engine resolution (`:962-1055`), and `clodeBuild` (`:1056-2060`, ~1,000
lines). Blobulate = `materializeFusedPayload` (`:73`) plus the part of `clodeBuild` that
attaches a payload to an engine image (the quaude worker spawn, the naude postject path).
RECORDED AND NOT SCHEDULED: the dep-closure family is ~480 cohesive lines with four exported
entry points phase 5b just built controls for, so `clode-dep-closure.cjs` would be a clean
module with a tested surface — not needed for this phase, noted so nobody re-derives it.

**What the rename breaks:** 55 files reference `clode-fuse` by name, 41 reference
`quaude-fuse`, and two of those references do not behave like text. (1)
`test/build-gates/dep-closure-gates.test.cjs` requires its production module by a LITERAL
relative path because phase 5b's sweep derives "controlled" from that literal — rename
without updating it and the gate silently becomes UNCONTROLLED, raising
`UNCONTROLLED_GATE_BASELINE` and going red for a reason that reads like a regression. (2)
`quaude-fuse.js` has NO module resolver (its `require` is a loud stub; siblings load via
`loadLibexecCjs`), so its rename and any new sibling must keep that loading contract.

### Bootstrap is not a product

`clode-main.cjs` already said so: "`--self` fuses the BUILDER, not a Claude Code target … it
is release bootstrap (CI legs, cross-fuse guests) rather than a user invocation", and it was
dropped from the help for that reason. Every call site is the checkout's Node clode
(`cross-fuse/action.yml:43`, `build-leg:935`, `build-leg:1008`, `release.yml:232`), and full
cross builds are the checkout's clode plus a foreign-arch target engine template — never
clode-builds-clode. So bootstrap is a verb on the CHECKOUT entry point only, the shipped
binary's table does not carry it, and a shipped clode asked to bootstrap refuses with a
reason. If phase 6's differential ever wants a builder built BY a builder, that is the line
to revisit.

### Policy

- **Hard break.** Old spellings stop working the day the new ones land; the same commit
  updates every in-repo caller. No aliases, no deprecation period — a translation layer
  between two vocabularies is a fact stored in two places, the argument that killed the
  fuse/build mapping.
- **A removed spelling gets a generic usage message**, not a mapping to the new form. The
  user's reasoning: with a tight enough vocabulary there are not enough choices to merit
  more. Three verbs and four positionals is tight enough.
- **Surface as DATA**: `libexec/cli-surface.cjs` holds one literal; help, dispatch and a
  surface test all read it. Today's 213-line if-chain over `args[0]` with inline flag
  sniffing is how `--target` acquired a second meaning without anyone deciding it should.

### Env vars

All 51 `CLODE_*` names read by shipped code get a verdict. **Absorbed** when the value
changes WHAT GETS BUILT (target, product, output path, which ingredient); **env-only** when
it changes how the build is OBSERVED or PLUMBED (test seams, CI wiring, cache/state roots);
**dead** when its only caller is a test. Absorbed names land in the table, so there is one
input surface rather than two. The rest ship with their verdict recorded.

### MEASURED 2026-09-12, and it settles the built-binary rule

    cold engine build (scripts/build-tjs.cjs)        60s
    warm self-build, engine cached                   14s  -> 27.7MB builder, smoke passed
    suite WITH an engine present      1955 tests / 1920 pass / 0 fail /  34 skipped
    suite with NO engine              1955 tests / 1577 pass / 0 fail / 377 skipped

The fast path the umbrella demanded already existed and simply was not being used; 14s
amortised across 1955 tests is noise, so the suite can build the product once per run and
exec it, with every exception named. The 343-test swing is its own finding: **a dev box
without an engine hides a fifth of the suite, and nothing said so.**

### Scope

IN: the rename (first, no behaviour change), the CLI break, the env classification, the
entry-point move (`bin/clode` → `scripts/stage0.mjs`; `bin/` holds a built binary or
nothing) with tests driving the built product, and one target building both products (the
oracle becomes a product, artifact names carry the bundle version).

OUT, each its own piece: the naude/quaude parity audit, and release as a declared step list
(which wanted to reuse whatever this CLI became, and now can).


## The unpinned-provider pattern has a MECHANISM now: two resolvers, one pinned (2026-09-13)

Found while triaging a red that a phase-3a implementer reported as "pre-existing and
unrelated". It is unrelated to that task — and it is ours, so it got measured rather than
relayed.

**The measurements, all on this box today:**

    UPSTREAM_PIN                          2.1.251
    ~/.local/share/clode/providers/current (a pointer FILE, not a symlink)   2.1.252
    ~/.local/bin/claude -> versions/2.1.270   the operator's native daily driver

    test/shim-surface.test.cjs, CLODE_PROVIDER_BIN=<pinned 2.1.251>   3/3 PASS
    test/shim-surface.test.cjs, CLODE_PROVIDER_BIN=<2.1.252>          PASS
    test/shim-surface.test.cjs, no override                            FAIL
    test/shim-surface.test.cjs, CLODE_PROVIDER_BIN=~/.local/bin/claude FAIL, identically

So a bare run stages neither the pin nor `current`: it stages **the Claude Code the operator
is running today**, and the confirming experiment above pins that to 2.1.270.

**The mechanism, which the earlier entry ("Three gates have now scanned an UNPINNED provider
— the condition needs a mechanism") said was missing. There are TWO resolvers and only one
is pin-capped:**

- `test/provider-resolve.cjs`'s `providers()` — CORRECT. Its own comment says it: "THE
  PINNED VERSION, EXACTLY. Not 'the newest at or below the pin'." Order is
  `CLODE_PROVIDER_BIN` → `CLODE_CLAUDE_BIN` → `<store>/<pin>/claude`. No `current`, no
  newest-fallback. This is where the interim mitigation was applied.
- `test/oracle-models.cjs:108`'s `resolveProviderBin()` — NOT pin-capped. It takes
  `CLODE_PROVIDER_BIN` if set and otherwise delegates to PRODUCTION's resolver,
  `libexec/clode-resolve.cjs`'s `resolveClaudeBin()`, whose documented order (`:93`) is
  `CLODE_CLAUDE_BIN > CLODE_VERSION_DIR > provider current` plus the native install. It never
  calls `pinnedVersion()`. Every gate that stages through `stageProviderCli()` — shim-surface
  among them — inherits that.

Production resolving "the claude to run" from the operator's machine is CORRECT for
production. Borrowing that resolver for a GATE is what makes the gate answer a question about
the wrong artifact. The fix is one line of intent: `resolveProviderBin` should prefer the pin
exactly, the way `provider-resolve.cjs` already does, and say why it cannot when it cannot.

**Why this keeps costing rounds:** it presents as a code regression. The red says the golden
Bun-surface map drifted, which reads as "our shim is wrong", when the true statement is "you
measured a different bundle than the one this repo pins". Two agents have now reported it as
pre-existing-and-unrelated rather than as a defect, which is accurate about blame and wrong
about ownership.

## Unreviewed golden drift at 2.1.270: `Bun.Image`, `Bun.unsafe` (2026-09-13)

A free by-product of the triage above, and the first look at 2.1.270's shim surface:
`layer1_bun_props_missing` gains exactly two entries against the golden map —
**`Bun.Image`** and **`Bun.unsafe`** — reproduced twice (bare run, and explicitly against
`~/.local/bin/claude`).

Same class as the `Bun.zstdDecompress`/`Bun.zstdDecompressSync` pair already filed above, and
the same rule applies: **do not add either to `golden.json` or stub it in `bun-shim.cjs`
without doing the reachability work first.** Nothing here says whether clode's tested traffic
reaches them; it says upstream now references them. `Bun.unsafe` in particular is a namespace
(`Bun.unsafe.arrayBufferToString` and friends upstream), so "one property" may be a family.

Note the pin is deliberately at 2.1.251 and `clode build` cannot carve 2.1.257+ at all, so
this is not a to-do for today — it is inventory for whoever absorbs the newer bundle, taken
while the evidence was free.


## The production-gate classifier reads COMMENTS as code shape (2026-09-13)

Found in phase 3a: `libexec/cli-surface.cjs` — a pure data module with no filesystem access and
no verdict of any kind — was classified as a gate-shaped production file and pushed the
uncontrolled count from 30 to 31.

**Why, measured to the line.** `classifyProductionFile()` (`test/guards-population.cjs:646-649`)
runs its regexes over RAW source. The verdict half's only hit in that file is `.includes('` at
line 11 — inside a comment quoting the old dispatch it replaced, `args.slice(1).includes('--naude')`
— and it becomes `false` as soon as full-line `//` comments are stripped. The refuse half is a
real `throw new Error(` at line 121, in `surfaceFor()`'s unknown-kind guard, which is argument
validation rather than a build gate refusing an artifact.

**What was done, and why it is not the fix.** A measured `PRODUCTION_GATE_EXCLUSIONS` entry with
a reason. That IS the sanctioned response — phase 5's tuning rule says false positives are the
safe side, "a false positive costs one migration or one recorded exclusion with a reason", and
the sweep's own failure message offers an exclusion as one of two remedies. Verified load-bearing
rather than cosmetic: removing the entry gives "31 … ABOVE the recorded baseline of 30", restoring
it gives 30, and `UNCONTROLLED_GATE_BASELINE` was never touched.

**Why it still wants fixing.** This is a false-positive GENERATOR whose only outlet erodes the
ratchet one exclusion at a time, and nothing pins the SIZE of `PRODUCTION_GATE_EXCLUSIONS` — the
only assertion on it is that each `because` is non-empty (`test/guards-population.test.cjs:429`).
So the sweep's headline number degrades quietly as exclusions accumulate, each individually
justified. The fix is the comment-stripper the same file already owns for other rules: strip
full-line `//` comments before classifying, then re-measure and drop whichever exclusions stop
being needed.

Same defect class as two others this project has now hit: the phase-5b `no-fuse` gate matching
the word inside its OWN header, and `test/merge-step.test.cjs` (phase 2) asserting against text
that matched inside its own file's header comment. A scanner that cannot tell code from prose
about code will keep finding itself.


## The env-var population is 65, not 51 — and it is not ONE population (measured 2026-09-13)

Phase 3b inherits "51 `CLODE_*` names are read by shipped code, 0 documented, against 4 flags"
from the 2026-08-25 entry, and the phase-3 spec repeats it. **Re-measured before designing
anything on top of it, and both halves of that sentence have moved.**

**What a single-pass index over `libexec/`, `scripts/` and `test/` actually finds** (matching
real environment READS — `env.X`, `process.env.X`, `env['X']` — not every `CLODE_*` token,
which would also sweep in esbuild defines like `__CLODE_BUNDLE_VERSION__`):

    65   names read as env by SHIPPED code      (the "51" is stale by 14)
    29   more read as env only under test/
    55   of the 65 are read by exactly ONE shipped file
    141  distinct CLODE_* tokens overall, if you count build-time defines too

And the "0 documented" half is already false as of phase 3a: nine names are now declared in
`libexec/cli-surface.cjs` and rendered into `--help`.

**The structural finding, which matters more than the count: these are at least four
populations, and one of them is not phase 3b's business at all.**

    20  scripts/build-tjs.cjs      ENGINE-BUILD KNOBS — CLODE_TJS_* plus CLODE_COSMOCC
    11  libexec/clode-build.cjs    build inputs proper
     7  libexec/clode-paths.cjs    store/path plumbing
     4  libexec/clode-watch.cjs    the tea-leaves reader
     4  libexec/clode-update.cjs   ingredient fetch
     3  libexec/bun-shim.cjs       applet resolution
     3  libexec/node-shim/loader.cjs  shim diagnostics

- **Engine-build knobs (~20)** — `CLODE_TJS_STATIC`, `_WASM`, `_FFI`, `_MIMALLOC`,
  `_MACOS_SDK`, `_CROSS_FILE`, `CLODE_COSMOCC`… all read by `scripts/build-tjs.cjs` alone.
  The umbrella gives the engine build to **phase 4** (cmake owns that graph). Absorbing these
  into `clode build`'s flag surface would be actively wrong: `clode build` requires no
  compiler and no cmake, and these names exist for the build that does. They want cmake
  options or a recipe file, not CLI flags.
- **Build inputs proper (~11)** — `CLODE_TARGET_TEMPLATE`, `CLODE_ENGINE_RECIPE`,
  `CLODE_MAIN_BUNDLE`, `CLODE_RELEASE_BASE`, `CLODE_TEMPLATES_*`, `CLODE_ALLOW_FOREIGN_CARVE`.
  These change WHAT GETS BUILT and are the real candidates for the spec's "absorbed" verdict.
- **Store/path plumbing (~7)** — `CLODE_STATE_ROOT`, `CLODE_PROVIDERS`, `CLODE_NODES`,
  `CLODE_CACHE`, `CLODE_DEPS`, `CLODE_LIBEXEC`. These relocate state roots so tests and CI can
  run hermetically; they change how the build is PLUMBED, not what it produces. Env-only by
  the spec's own test, and making them flags would be a regression — a test harness cannot
  pass a flag through three layers of spawn as easily as it can set an environment.
- **Diagnostics (~6)** — `CLODE_SHIM_PROBE`, `_TRACE`, `_DEBUG`, `_HANDLE_DUMP`, `CLODE_PROBE`,
  `CLODE_RG_DEBUG`. Env-only; nobody wants `--shim-handle-dump` in `--help`.

**So phase 3b's env work is smaller than it looks and differently shaped:** roughly eleven
genuine absorption candidates, about twenty names that belong to phase 4's cmake conversation,
and the rest env-only with a written reason. The spec's instruction to "classify all 51" should
become "classify all 65, and route the engine cluster to phase 4 rather than the CLI."

**Method, so the next person can redo it rather than trust it:** one Node pass walking the
three trees, matching the env-read shapes above, inverting the index name→files. Counting raw
`CLODE_*` tokens instead gives 141 and is the wrong number — it includes build-time defines
that are not environment variables at all.


## THREE PHASE-3B DECISIONS (user, 2026-09-13)

### 1. The ~20 engine-build knobs go to phase 4 as cmake options, NOT to the CLI

`CLODE_TJS_STATIC`, `_WASM`, `_FFI`, `_MIMALLOC`, `_MACOS_SDK`, `_MACOS_MIN`, `_CROSS_FILE`,
`_REGEN`, `_SMOKE`, `CLODE_COSMOCC` and the rest of that cluster are read by
`scripts/build-tjs.cjs` and nothing else. They are options to a COMPILE, and the umbrella's
invariant is that `clode build` requires no compiler and no cmake — so they belong to the
program that does. Absorbing them into `clode build`'s flag surface would put twenty compile
options on a command that cannot compile: the same axis conflation phase 3a spent six tasks
removing, arriving from the other end. Phase 4 moves the engine build to cmake, where they
become typed options with defaults and a cache rather than undocumented env vars.

Consequence: phase 3b's env work is ~11 genuine absorption candidates, not 51 and not 65.

### 2. "The oracle is a product, not a fixture" is RETIRED — the oracle is an INGREDIENT

The umbrella clause was written before phase 3a's vocabulary existed. **The oracle is
`claude`** — upstream's own behaviour is what we are matching — and phase 3a already made it
first-class as `clode fetch claude`, an ingredient. There is no third product to build.
`test/oracle-models.cjs`'s `stageCli()` stays a test fixture (17 test files consume it), and
the clause is retired with that as its written reason rather than silently ignored.

**The user's correction that settles it, worth keeping verbatim in substance:** naude "is not
more of an oracle than claude itself. Less of one, strictly speaking, since Claude's behavior
is what we're trying to match." naude is the MIDDLE TERM in a three-way differential, not an
authority.

### 3. naude stays on EVERY platform we have it — and my narrowing was wrong

I proposed cutting naude to one platform, arguing the differential's value is per-LAYER (one
platform where both products run is enough to isolate engine-vs-shim) so additional naude
platforms add only packaging coverage. **The user overruled it with a better argument:** given
how much PLATFORM-DEPENDENT behaviour this project keeps finding, naude's carrying cost is in
the noise next to the carrying cost of the build system being rehabilitated.

That is right and my premise was wrong. I assumed divergences are layer-shaped; this
repository's own record says they are platform-shaped — the haiku tjs write deadlock, NetBSD's
64-bit `time_t` utimes truncation, Tiger/PPC's kqueue deadlock, the darwin-x64 floor walk, and
a Windows-only path-separator failure found the same day this was decided. If divergences are
per-platform, then "engine or shim?" is a per-platform question, and only a naude ON that
platform can answer it.

**The mechanism, already confirmed in this file (see the layer diagram above):** `bun-shim` is
shared by both products, `node-shim` exists only under quaude, and `scripts/build-naude.mjs`
bakes the bun-shim from the SAME staged location quaude reads — deliberately, "never one
reached back for from the repo". So the two products differ in exactly one layer by
construction, on every platform that carries both.

**Measured while deciding, and recorded because it cuts the other way:** of 116 `naude`
mentions in this file, most are maintenance (an unbuilt bundle, a broken `--cli` path, and one
entry reading "quaude … fixed, proven, and green. naude was not, and nothing noticed"). The
clearest isolation credited to the differential is the shim `FileHandle.chmod` gap. The
instrument's demonstrated yield is thinner than its architecture promises — which is an
argument for USING it more deliberately, not for having less of it.


## PHASE 3B SPECCED (2026-09-13)

Spec: `docs/superpowers/specs/2026-09-13-phase3b-env-and-products-design.md` (gitignored by
project convention, so the decisions live here). Phase order:
**1 → 2 → 2.5 → 5 → 5b → 3a → 3b → 4 → 6.**

**Scope, with the measurements that shaped it:**

- **The env absorption pool is EIGHT decisions, not fifty-one.** `libexec/clode-build.cjs`
  reads eleven env names and they are the entire candidate set; three of the eleven
  (`CLODE_TJS`, `CLODE_VERBOSE`, `CLODE_TARGET_TEMPLATE`) are already declared in the table
  from phase 3a. The remaining eight are `CLODE_ENGINE_RECIPE`, `CLODE_MAIN_BUNDLE`,
  `CLODE_RELEASE_BASE`, `CLODE_TEMPLATES_BASEURL`, `CLODE_TEMPLATES_BLOB`,
  `CLODE_TEMPLATES_MANIFEST`, `CLODE_TJS_PIN`, `CLODE_ALLOW_FOREIGN_CARVE`. Every other name
  among the 65 gets a recorded verdict without ceremony.
- **The plumbing cluster is env-only BY NECESSITY.** `clode-paths.cjs`'s seven
  (`CLODE_STATE_ROOT`, `CLODE_CACHE`, `CLODE_DEPS`, `CLODE_PROVIDERS`, `CLODE_NODES`,
  `CLODE_TRACE_LOG`, `CLODE_WATCH_DIR`) relocate state roots so the suite and CI run
  hermetically. A flag cannot replace them: the harness sets them once and they must survive
  three layers of spawn into a worker that parses its own argv. Recorded so nobody "finishes
  the job" later by mistake.
- **The built-binary loop is deliberately naive, and the sequencing reason is the point:** no
  content key, no staleness hash, because phase 4 owns derived keys and hand-rolling a second
  cache key here is exactly the "keys are never hand-written" violation phase 2 already caught
  in `MERGER_VERSION`. One build per run at the measured 14s, with prebuilt injection kept so
  CI and the slowest box need not pay it.
- **"One target builds both products" is largely ALREADY TRUE** — measured, not assumed:
  `clode build` takes the product as a positional (`clode-build.cjs:896`); both share argv,
  staging, the dep-closure gates and reporting; both attach through the same `blobulate()`
  since 3a; they diverge only where the mechanisms genuinely differ (postject injection vs a
  canonical-LE trailer). What remains is ONE item: the local default output name does not
  carry the upstream bundle version, so two builds from different bundles are
  indistinguishable on disk, while PUBLISHED assets already carry it via
  `canonical-name.cjs`'s `assetName`.

**Three inherited claims did not survive re-measurement**, which is the phase's own lesson
recorded for the next one: the env population was 51 and is 65; the "fast path to a built
builder" the umbrella said phase 3 REQUIRED already existed at 14s warm; and one-target-both-
products was mostly done. Only the first is a number — the other two are premises, and
premises are what a plan silently inherits.

**Open, deliberately:** whether the built-binary rule holds in the same form on the slowest
supported box — to be answered with a measurement there, not an opinion.

## CLODE_ALLOW_FOREIGN_CARVE CLOSED: env-only, deliberately awkward, no flag (2026-09-13)

Phase 3b task 2 decided the one entry the spec above left open twice. `CLODE_ALLOW_FOREIGN_CARVE`
stays `absorbed` (it genuinely changes whether a build proceeds with a given input, upheld on
review) but is declared on the `build` verb's `env` table in `libexec/cli-surface.cjs:173-187`
as `CLODE_ALLOW_FOREIGN_CARVE=1` — documented so `--help` (the only documentation inside a
shipped binary) does not hide that it exists, but deliberately NOT given a discoverable
`--allow-foreign-carve` flag.

**Why no flag:** it disables the carve-vs-target-platform guard, i.e. the check standing
between a build and the filed P1 above ("a quaude built from a foreign-carved provider LIES
about its platform") until phase 4 keys the provider store by platform+arch. A discoverable
flag would invite reaching for it as "the fix" when a build refuses a mismatched provider,
instead of the actually-correct move (`clode fetch claude` for the right platform, or point
`CLODE_CLAUDE_BIN` at one) — reintroducing, as a documented shortcut, exactly the failure mode
the guard exists to prevent.

**Why not deleted (making the guard unconditional):** no test exercises the escape hatch today,
but the guard's own error message (`libexec/clode-build.cjs:1713-1718`) already tells an
operator to set it "if you are deliberately testing this" — a legitimate, narrow use
(reproducing the P1, or exercising cross-platform build paths without re-fetching a matching
provider each run). Deleting it would also require rewriting that message.

Not declared on `bootstrap`: the guard is gated `!naude && !self`, so a `bootstrap` build never
reaches it (`libexec/clode-build.cjs:1706-1707`).


## ★ PATTERN: five instruments, one mistake — a loose match where an exact one was meant (2026-09-13)

Not a defect report. A **class**, found five times in two phases, each time in a DIFFERENT
instrument, each time by a reviewer rather than by the instrument itself. Writing it down
because the sixth instance is cheaper to prevent than to find.

    1. `FUSE_WORD_RE` caught only trailing-position compounds, because `\b` is not a camelCase
       boundary — in `fusedBuilder` the needed boundary sits between `d` and `B`, both word
       characters. It missed `materializeFusedPayload`, `fuseSrc`, `scanFuseReportWiring` —
       the very identifiers the task had just renamed. (phase 3a task 2, two fix rounds)
    2. The `no-fuse` gate matched the retired word inside its OWN header comment, so the file
       that forbids the word tripped over explaining itself. (phase 3a task 2)
    3. `classifyProductionFile()` runs its regexes over RAW source, so a COMMENT quoting
       `.includes('--naude')` made a pure data module read as a build gate. Twice: once for
       `cli-surface.cjs`, once for `clode-main.cjs`. (filed above, 2026-09-13)
    4. `guards-population.cjs` compared a POSIX literal against `path.relative()` output,
       which is backslash-separated on Windows — so a recorded exclusion silently stopped
       matching and the ratchet fired correctly for the wrong reason, on Windows only.
       (CI run 34762646884; fixed in `dd9aee5`)
    5. The absorbed-verdict gate used `help.includes(name)`, and `CLODE_TJS` is a substring of
       `CLODE_TJS_PIN` — so deleting BOTH `CLODE_TJS` entries left the gate green. A gate ruled
       in specifically to stop a name's absence going unnoticed could not notice that absence.
       (phase 3b task 2)

Phase 2's `merge-step.test.cjs` — asserting against text that matched inside its own header
comment — is the same class, and predates all of these.

**What they share, and it is not "regexes are hard":** every one is a scanner comparing a
STRING against a CORPUS that contains strings shaped like it. The failure is always the same
shape — the match succeeds somewhere it was not meant to, or fails somewhere it was — and the
symptom is always a green that means nothing.

**The rules that would have caught all five, in the order they are cheap:**

1. **Compare identities, not text.** Collect the set of things you mean (entry names, file
   paths, declared members) and test membership. #5's fix is exactly this and it is three lines.
2. **Exclude the instrument from its own corpus**, or strip comments before classifying. #2 and
   #3 are both "the scanner read its own explanation".
3. **Normalise the axis you did not choose.** Paths are POSIX, case is explicit, separators are
   decided once at the boundary — #4 is what happens when that is left to the OS.
4. **Prove the match FAILS on a near-miss, not just that it succeeds on a hit.** Every one of
   these passed its own positive test. The disproof — delete the thing and watch the gate go
   red — is what found #5, and a control that only proves the positive direction is half a
   control (see the `checkControl` per-detector gap, filed separately).

**Still latent, found while fixing #5 and left alone deliberately:** `test/e2e-man.test.cjs`
lines 38, 42, 46, 50, 70 and 82 are bare/unanchored matches of the same shape. None has a
superstring sibling among today's absorbed names, so there is no live hole — but that is luck,
not design, and the next absorbed name could supply the sibling. A sweep wants doing; it is not
urgent, and it should fix the shape rather than the six lines.

## `NATIVE_ONLY` now holds a transient entry in a list that documents itself as structural

`test/doctor-cli-parity.test.cjs:55` reads:

```js
const NATIVE_ONLY = ['Organization policy'];
const QUAUDE_ONLY = ['Invoked'];   // quaude names its VFS entry; native has no analogue
```

`QUAUDE_ONLY`'s comment states the contract both lists are under: a label
belongs here when **one side has no analogue at all** — a structural fact about
the two products that stays true across upstream bumps. `Invoked` qualifies:
quaude names its VFS entry and native has nothing to name.

`Organization policy` does not qualify, and phase 3b task 3 proved it doesn't
with the discriminating measurement: the string appears 10x in native 2.1.270
and **zero times in both 2.1.251 and 2.1.252**. So it is not a label quaude
cannot emit — it is a label the PINNED bundle does not contain yet. The entry
is version skew wearing a structural entry's clothes.

**Why that matters, concretely:** the day `UPSTREAM_PIN` advances past the
version that introduced the label, quaude starts emitting it too, the entry
becomes dead, and the gate at `:142` (`!Q.has(k) && !NATIVE_ONLY.includes(k)`)
keeps excusing it forever. If quaude later REGRESSES and stops emitting
`Organization policy` — exactly the divergence this file exists to catch — the
gate stays green. An allowlist entry in a fidelity comparison that outlives its
reason is how a fidelity gate goes quiet without anyone deciding it should.

**The wrong fix** is a new `NATIVE_ONLY` entry per upstream bump. That converts
a structural list into an unbounded skew ledger and guarantees the failure
above, once per label.

**The right fix** is a version-skew gate on the file: the comparison already
knows the pin, so a label present in native and absent from quaude should be
checked against the pinned bundle's own text before it is excused. Present in
the pinned bundle and missing from quaude's output = a real divergence, red.
Absent from the pinned bundle = skew, excused **with the pin recorded**, so the
excuse expires when the pin moves rather than when someone remembers. That
makes the entry self-retiring and keeps `NATIVE_ONLY` meaning what its own
comment says it means.

Filed rather than fixed because it is a change to how the fidelity gate decides,
not to phase 3b's subject. It belongs with whatever next touches
`doctor-cli-parity.test.cjs`, and the measurement above is the evidence a future
implementer needs so they don't have to re-derive it.

## THE BUILT TARGET DOCUMENTS NO ENV VAR IT READS (found 2026-09-13, phase-3b fix wave)

`CLODE_TTY_MOUSE` and `CLODE_TTY_FOCUS` are **end-user opt-ins** — the only way
to get terminal mouse tracking or focus reporting back in a running quaude,
which suppresses both by default because the event flood starves keystrokes on
slow hardware. `libexec/node-shim/modules/tty.cjs` says so in its own words
("Opt back in per capability: `CLODE_TTY_MOUSE=1` / `CLODE_TTY_FOCUS=1`").

**That sentence is in a source comment.** A user holding a shipped quaude has no
way to reach it: the built target's `--help` is upstream Claude Code's text, and
`clode --help` is the builder's surface, which correctly never mentions these
because no clode verb reads them. They are recorded `env-only` in
`test/env-verdicts.cjs` with that reasoning spelled out — the verdict is right
and the documentation gap is real and separate.

**The shape of the gap, not just the instance:** clode's CLI surface
(`libexec/cli-surface.cjs`) is a real declared table with a gate behind it, and
the built target has no equivalent at all. Every name in the "target runtime"
group further up this file has the same problem. A fix means deciding where a
quaude documents its own knobs — not adding two entries to clode's table, which
would document them in the wrong binary.

Filed rather than fixed: it is a new surface for the built product, which is
larger than an env-inventory fix wave.

## `man/clode.1`'s ENVIRONMENT section trails `--help` by 13 names

Phase 3b absorbed 17 `CLODE_*` names into the CLI surface, so
`libexec/cli-surface.cjs` now declares 18 (the 17 plus `CLODE_CACHE`) and all 18
render in `--help`. `man/clode.1`'s ENVIRONMENT section documents 5 of them.

This is incompleteness, not a lie — every name the man page *does* document is
accurate, and `--help` is the authority inside a shipped binary. But the man
page is the second hand-maintained copy of the surface, and
`test/e2e-man.test.cjs:53-62`'s own comment already says it "lied the moment the
spellings changed". Phase 3b tied exactly one claim between the two copies: the
`build --out` default, ratcheted in both directions by the test at
`test/e2e-man.test.cjs`'s `man's build --out default matches cli-surface.cjs's
rendered default`. Nothing binds the env list.

**The shape of the fix, when someone takes it:** the same derivation the `--out`
ratchet uses. `cli-surface.cjs` already holds every declared name and its doc
sentence as data (`env: [{name, doc}]`), so the ENVIRONMENT section can be
checked against it — or generated from it — rather than transcribed a third
time. A gate that requires every declared `absorbed` name to appear in
`man/clode.1` is the cheap version and would go red today, correctly, thirteen
times.

**Sequencing:** this belongs with the sweep already filed under "five
instruments, one mistake" for `test/e2e-man.test.cjs`'s six remaining
bare/unanchored matches (lines 38, 42, 46, 50, 70, 82). Both are the same file,
both are about the man page's relationship to the surface table, and doing them
together means reading that file's matching rules once instead of twice.

## Closure condition 7 has no mechanism, and phase 3b moved the number without anything noticing

The umbrella's condition 7 reads: *"Every skip is understood, and as many as
possible are not skips any more … and the count is recorded so a later rise is
visible."* The first half has been honoured. The second half has no
implementation: the count lives in the prose of the inventory entry above (33 at
the time), and nothing in the suite asserts it.

Phase 3b moved it. `test/doctor-cli-parity.test.cjs` went from running by default
to gated behind `CLODE_LIVE_RENDER`, on a measurement worth keeping — a logging
shim ahead of `/usr/bin/security` caught native `claude doctor` making six
Keychain calls, including an interactive `security -i` and a
`delete-generic-password` of its own `Claude Code-doctor-probe` item. It *writes*
to the login keychain. Gating it was right, and the three tests pass 3/3 under the
opt-in, so this is deferral rather than deleted coverage.

The point is not that the rise was wrong. It is that **the rise was invisible**: 31
-> 34 was noticed only because a controller happened to diff two suite summaries by
hand. A phase can gate a whole file for an excellent reason and the umbrella's own
closure condition cannot tell.

This was already proposed and never built. See the earlier entry's item 3: *"A CI
assertion on the skip COUNT (or better, the skip SET), so coverage silently…"* —
and **the set is the right shape, not the count**. A count ratchet says a number
moved; a set ratchet says *which test stopped running*, which is the thing anyone
actually needs in order to act. It also survives the common case of one skip being
fixed while another appears, which a count cannot see at all.

Shape of the fix: `test/run.mjs` already aggregates the TAP summary, so it can
collect skip names too. Record the set as data, assert against it, and require a
change to it to be an edit with a reason — the same both-direction ratchet shape
the `--out` man gate uses. A skip disappearing should be as loud as one appearing:
a test that stopped skipping because it started being ABSENT is exactly the defect
the 84 -> 33 inventory found in `inspect.test.cjs`.

Sequencing: this belongs before the umbrella is closed, since it is one of the
seven conditions. It does not block phase 4.

## ★ Phase 4 designed — the engine build splits four ways (2026-09-14)

Full spec: `docs/superpowers/specs/2026-09-14-phase4-declared-edges-design.md`
(gitignored, so this entry is the durable copy of what was expensive to establish).

The umbrella said "cmake owns the build graph; something small owns provisioning
and verification, and that something must run WITHOUT Node — i.e. quaude itself
or shell." Neither named candidate wins alone. The work splits by CAPABILITY:

| job | owner |
|---|---|
| build graph; bytecode regen as OUTPUT/DEPENDS; host-vs-target tjsc | cmake |
| fetch + verify, archive extract, sha256 | cmake |
| pinned clone + the 16 patch files | git |
| the 52 source fixups; artifact naming | tjs |
| hermeticity verification of the built binary | a tiny C program |

**Three eliminations, each closing a door someone will re-open.**

1. **Shell is dead, on Windows** (user's constraint). Windows shell means Git
   Bash, which means POSIX tools silently reinterpreting Windows paths — and we
   already own that scar: host-provision.cjs's tar KAT documents Git Bash tar
   reading `C:\…\x.tar` as a remote `host:path` and dying "Cannot connect to C:".

2. **One tiny C binary for everything is dead, on TLS.** Provisioning fetches
   (the cosmocc zip is a sha-pinned 441MB). clode-net.cjs:7-9 records that
   dropping curl/wget is an explicit goal and downloads use the engine's built-in
   fetch — a TLS stack. A C provisioner would have to re-solve it: bundle a
   library (not tiny), link three system ones (not one implementation), or shell
   out (see #1). It does not have to. MEASURED on cmake 4.3.3, 2026-09-14:
   `file(DOWNLOAD https://…)` → status 0, `file(SHA256)`, `ARCHIVE_CREATE`/
   `ARCHIVE_EXTRACT` round-trip, `cmake -E sha256sum` agrees. So
   `file(DOWNLOAD … EXPECTED_HASH …)` is fetch-and-verify as ONE primitive and
   the binary needs no network at all.

3. **Converting the 52 fixups to patch files is dead, because it is a
   DOWNGRADE.** They are imperative on purpose: idempotent (`if already applied,
   return`), self-validating with a domain-specific error (`CMakeLists.txt
   changed under the pin — re-derive`), and deliberately position-independent
   (append at EOF, not context-anchored). A `git apply` patch is worse at all
   three and fails with `hunk #1 failed`. The 16 real patches stay patches; the
   52 fixups stay code — and move to tjs, which is what actually retires Node.

**The bring-up cost of moving fixups Node -> tjs is ZERO, and the reason is that
weird platforms never had Node.** Measured over tjs-legs.mjs: 44 legs, 17
cross-file, 21 guest-platform, 17 `verify:'none'`/`no-exec:true`. netbsd-m68k is
`os:'ubuntu-latest'` + cross toolchain, "built-not-run … the arch gate (file(1))
is the proof" — that box never runs anything. Where a weird box DOES execute it
runs the PRODUCT: netbsd-sparc "cross-blobulates the bootstrap builder ON THE X64
RUNNER … then runs clode-on-sparc". So build-tjs.cjs has always run on
ubuntu/macOS/Windows, where we publish clode as hard publishers. The prerequisite
gets SMALLER: one static binary we already ship, not a full Node install.

**The verifier is the biggest coverage win in the phase, not a cleanup.**
`checkHermeticDeps` (build-tjs.cjs:3705) skips on cross-builds ("the host's own
otool/ldd cannot meaningfully inspect a foreign-arch/foreign-OS binary"), on
Windows, and on static links. Cross-building is how most of the fleet is made, so
for ~17 legs the ENTIRE hermeticity proof today is `file(1)` — "yes, that is an
m68k NetBSD ELF". Nothing checks what it links: a gate that cannot fail. But the
dependency list is a TABLE IN THE FILE — ELF `DT_NEEDED`, Mach-O `LC_LOAD_DYLIB`,
the PE import directory — readable regardless of which machine the file targets.
~150 lines per format, no network, no shell, no TLS, built by cmake on the spot
and NEVER SHIPPED (no new release artifact, no version skew). That converts ~17
legs from "right architecture" to "right architecture AND links nothing it
shouldn't", and it is the one gate phase 5 could not reach.

**Recommended split (controller's, not yet ruled on by the user):** 4a = the
build checks its inputs (provider store key × platform × arch, plus the
incapable-engine refusal — both are §7, both independent, and 4a's live bug is a
linux carve sitting at this Mac's pinned provider path RIGHT NOW, so fixing it
first makes every later measurement honest). 4b = the verifier, which proves the
"C built by cmake on every host" pattern on Windows and cross-builds BEFORE 4c
bets 3,799 lines on cmake. 4c = the cmake/tjs migration + ccache.

**Open question, SETTLED (phase 4c1, 2026-09-17):** build-tjs WAS ESM and
imported seven builtins (fs, path, os, crypto, child_process, url, module) —
all seven exist in libexec/node-shim/modules/, but loader.cjs is CommonJS-
oriented and does NOT intercept an ESM entry at all (`loader.cjs:481` guards its
transpile with `!isEntry`). The answer was to convert, not to teach the loader
ESM: `scripts/build-tjs.cjs`.

## ★ Phase 4 SEQUENCED 4b → 4c → 4a, and 4b is planned (user, 2026-09-17)

Plan: `docs/superpowers/plans/2026-09-17-phase4b-hermeticity-verifier.md`
(gitignored, so this entry is the durable copy of the decisions and the
measurements behind them).

**The ruling.** The 2026-09-14 design offered 4a → 4b → 4c and recorded it as
un-ruled. Re-measured first, and **4a's stated urgency had evaporated**: the
design said "a linux carve [is] sitting at this Mac's pinned provider path
RIGHT NOW, so fixing it first makes every later measurement honest." `2.1.251`
is now a correct `Mach-O arm64`. The defect is still real and structural but
sits at five OLDER versions — `2.1.207 .210 .211 .215 .243` are x86-64 Linux
ELF on an arm64 Mac — none of which any measurement runs against. So the
argument for 4a-first no longer holds, and the order is **4b → 4c → 4a**:

- **4b first** because it de-risks 4c. 4c bets 3,799 lines on "cmake builds our
  C correctly on every host including Windows and cross-builds"; 4b tests that
  exact pattern on ~450 lines of self-contained C first.
- **4b is also the only part that ADDS coverage** rather than reshaping what
  exists, and it is the one gate phase 5 could not reach.
- **4a last** because it is now a structural cleanup with no live contamination.

**The gap is 19 legs, not the design's "~17".** Every release leg with a
`cross-file` or a Windows host, minus the 8 `static` ones whose skip is correct
by construction; 15 of the 19 publish. Reproduce with `legsFor('release')`.
Named in `test/depscan-legs.test.cjs`'s `WAS_BLIND` so a regression is legible.

**§12 Q4 SETTLED — fat Mach-O reports PER SLICE.** darwin ships a 4-way
universal (`DARWIN_SLICES`), so a merged list — `otool -L`'s default — lets one
hermetic slice mask a non-hermetic one, which is the same gate-that-cannot-fail
shape the phase exists to remove.

**§12 Q1 SETTLED BY MEASUREMENT — the orchestration converts to CJS.** Probed
against the pinned tjs under `libexec/node-shim/loader.cjs`:

    .mjs ENTRY, `import fs from 'node:fs'`  -> SyntaxError
    same file require()d (non-entry)        -> works, builtins resolve
    non-entry file using import.meta.url    -> SyntaxError: import.meta only
                                               valid in module code

The transpile is guarded `if (!isEntry && esmDetect(src))` at `loader.cjs:481`,
so an entry is ALWAYS evaluated as CJS, and the loader's own header says it is
"NOT a general ESM implementation". Teaching it ESM means entry interception
PLUS an `import.meta` implementation. Conversion is far cheaper: of 20
`import.meta` hits in `build-tjs.cjs` only **2 are executable** (`:73`, `:75`) —
the other 18 are inside the C-fixup string literals and comments that teach
*txiki* about `import.meta` for the product. Both executable ones are
boilerplate that DISAPPEARS in CJS (`createRequire(import.meta.url)` -> built-in
`require`; `fileURLToPath(new URL('..', import.meta.url))` -> `__dirname`). No
top-level await — CORRECTED 2026-09-17, this was WRONG: `await` at `:272` is
inside `provisionCosmocc`, but its ONE caller awaits it at TOP LEVEL inside
`if (cosmoTarget)`, which CJS cannot express. The fix cost four lines, not a
re-indent: everything from the cosmo block to EOF now runs inside an async
arrow whose body is deliberately left at its original column, so the ~550 build-
phase lines keep their blame and the column-0 `function` anchors the source-text
gates slice by still line up. The two
sibling `.mjs` imports are 43 and 106 lines of plain `export function`.
Ripple to fix in the same commit: `test/engine-api-floor.test.cjs:109` pins the
exact import spelling, and `.github/actions/build-leg/action.yml:600,994` run
`node scripts/engine-api-floor.cjs --emit-check`.

**A DEFECT FOUND WHILE PLANNING, and it is the most important thing here.** The
denylist asks `dep === root || dep.startsWith(root + '/')` against
`PKG_MANAGER_ROOTS` — i.e. it assumes every dependency is an ABSOLUTE PATH.
True for Mach-O (`LC_LOAD_DYLIB` records an install path) and **never for ELF**,
where `DT_NEEDED` is a bare SONAME with no prefix in it at all. `ldd` only
appeared to solve this by RESOLVING the SONAME through the build host's own
loader — a fact about that machine, not about the file, and exactly the
coupling being removed. Ported naively, the new gate would have been green on
every ELF leg for the wrong reason: a NEW gate that cannot fail, introduced by
the phase whose purpose is removing one. The fix is to read `DT_RPATH`/
`DT_RUNPATH` (and Mach-O `LC_RPATH`) and deny on the search path, which is a
property of the artifact and true on every machine — a STRONGER check than the
one it replaces. It gets its own task rather than a line in another.

**PROVEN before the plan was written, so the premise is a dated fact.** A ~40-
line prototype ELF reader compiled on arm64 Darwin, run against real
cross-built engines in `~/.cache/clode/templates`:

| input | file(1) | prototype |
|---|---|---|
| `tjs-netbsd-sparc` | ELF 32-bit **MSB** SPARC, dynamic | `elf32be machine=2`, 5 deps: `libpthread.so.1 libkvm.so.6 libm.so.0 libgcc_s.so.1 libc.so.12` |
| `tjs-linux-s390x` | ELF 64-bit **MSB** S/390, static | `elf64be machine=22`, `deps=0` |
| `tjs-linux-arm64` | ELF 64-bit LSB aarch64, static | `elf64le machine=183`, `deps=0` |

`netbsd-sparc` is a published, dynamically-linked leg that links **five
libraries nothing has ever verified** — they turn out to be clean, but nothing
knew that until this ran, which is the point.

**And the tool being replaced fails silently.** On that same SPARC binary,
`otool -L` prints "is not an object file" and **exits 0**. The existing
`try { runOut(...) } catch` cannot see that; only the later `deps.length === 0`
guard catches it, and only by accident of ordering. One more instrument that
reported a non-answer as an answer — the class already filed under "five
instruments, one mistake".

## ★ Phase 4b SHIPPED — the hermeticity check stops skipping on 19 of 42 legs (2026-09-17)

`tools/depscan/depscan.c` reads the dynamic-dependency table out of a binary REGARDLESS of
which machine that binary targets — ELF `DT_NEEDED`/`DT_RUNPATH`, Mach-O
`LC_LOAD_DYLIB`/`LC_RPATH` per fat slice, the PE import directory. cmake builds it
host-native during the engine build; it is never shipped, so there is no release artifact
and no version skew. `scripts/build-tjs.cjs`'s `checkHermeticDeps` uses it instead of
`otool -L`/`ldd`; `scripts/depscan-verdict.cjs` holds the pure decision logic so
`test/guard.cjs`'s `scan()` can be fed a known-bad input.

**Build-side skips went 3 -> 1.** The survivor is static-by-construction, which is a
property of the ARTIFACT rather than of the host looking at it. The other two — cross-built
and Windows — were never verdicts; they were the absence of one, on 19 of 42 release legs
(15 `publish: true`), whose entire proof was `file(1)` saying "yes, that is an m68k NetBSD
ELF". `test/depscan-legs.test.cjs` ratchets that: 8 static, 19 named formerly-blind.

**Measured on real cross-built engines, from an arm64 Mac** (the point of the whole thing):

| engine | depscan |
|---|---|
| `tjs-netbsd-sparc` — 32-bit **BE** SPARC | 5 deps |
| `tjs-macos-ppc` — 32-bit **BE** PowerPC | 1 dep |
| `tjs-windows-amd64` — PE32+ | 10 DLLs |
| `tjs-linux-s390x` — 64-bit **BE** | static, `deps=0` |
| a cosmo APE built from the cached toolchain | `pe64`, 4 DLLs |

`otool -L` on that SPARC binary prints "is not an object file" **and exits 0** — one more
instrument reporting a non-answer as an answer.

### Four defects found by FUZZING or by running the thing, not by reading it

Each was invisible in review and each is the same class this phase exists to delete —
a gate that reports OK without having checked.

1. **Overflow → reported HERMETIC.** `DT_NEEDED = 0xffffffffffffff00` wraps to a small
   in-bounds offset; depscan printed `dep=` (empty name) and exited 0. An empty name does
   not start with `/`, so the denylist skipped it and the binary read as clean.
2. **A dependency name could FORGE the output protocol.** A name containing a newline
   emitted a fake `deps=1` terminator mid-stream, splitting one real dependency into a
   benign group and pushing the real `/opt/pkg` dep into another.
3. **A static engine read as BROKEN.** `examined` counted DEPENDENCIES, and a static binary
   has zero by construction — the STRONGEST hermeticity result there is. Wiring the guard
   into CI would have reddened all 8 musl legs.
4. **A fat Mach-O whose SECOND slice is corrupt printed slice 0's complete group, then
   exited 4.** That stdout parses CLEAN — one slice, zero findings — so the missing slice's
   `/opt/pkg` dependency vanished. Only the caller's exit-code check stood between that and
   a false hermetic verdict, on darwin, the one published 4-way universal. Found by the
   whole-branch review, which no task-scoped review could have caught: Task 6 examined the
   analogous ELF `run=` case and ruled it safe *because "no `deps=`/`format=` line is
   fabricated"* — which is exactly what the fat loop did. Both facts true; nobody owned both.
   Fixed at the emitter AND at the parser: `parseDepscan` was reading `slices=N` off the
   format line and discarding it; it now requires `slices.length === N`.

### The ELF class is NARROWER than what it replaced, deliberately — write it down

On native ELF legs the old check resolved SONAMEs through the host loader, so it could flag
a dependency that RESOLVED into a package-manager prefix with no RPATH baked in. depscan
cannot: `DT_NEEDED` is a bare SONAME, so all ELF detection now rests on
`DT_RPATH`/`DT_RUNPATH`. That is the right call — host resolution is a fact about the build
host, not the artifact — and it is a large net gain, but it IS a narrowed class on ~10
native legs. It also works today only because cmake bakes the build-tree RPATH by default
and the shipped engine is the build-tree binary; a future `-DCMAKE_SKIP_BUILD_RPATH=ON`
would silently blind the ELF half with no test going red. Recorded in
`hermeticityFindings`' comment.

### OPEN — filed, not fixed

- **Cache-hit legs now need a host C compiler.** The new CI oracle step has no `if:`, so a
  `tjs-cache` hit — which previously compiled nothing on the runner — must now cmake-build
  depscan or the leg goes red. Fails loudly, not silently. First-CI-run watch item, along
  with the windows-arm64 generator question (MSVC env exports a cross compiler; the
  `build-depscan-host-native` guard only checks that no cross-FILE is passed, so it cannot
  see an env-supplied one).
- **Static legs still write no CI summary line** — same shape as the failing-leg case fixed
  here, one path over.
- **`WAS_BLIND` is declared, not derived** — deriving it would also catch a future leg
  silently gaining a cross-file.
- **A new source-scan gate in `depscan-legs.test.cjs` has no `control()`**, and evades the
  guards-population ratchet only because it uses `.includes()` rather than a regex. Same
  class as the two files migrated under this phase's own ruling, opposite treatment.
- **Three comment-stripping tokenizers now exist** (`test/strip-comments.cjs`,
  `test/source-scan.cjs`'s `stripLineComments`, and a third copy in
  `test/build-gates/lexical-code-mask.test.cjs` justified by a reason this branch made
  false). No map says which to use when.

## ★ Phase 4c1 Task 3 SHIPPED — spec §11.1 acceptance met: the engine build runs with Node ABSENT (2026-09-17)

Tasks 1-2 converted the orchestration (`scripts/build-tjs.cjs`) and its three leaves
(`tjs-source-reset.cjs`, `engine-api-floor.cjs`, `build-depscan.cjs`) from ESM to CJS,
because `libexec/node-shim/loader.cjs` cannot host an ESM entry at all (`:481` guards its
transpile with `!isEntry`). Until this task, "it could run without Node" was an argument.
It is now a transcript, gated by `test/build-tjs-no-node.test.cjs`.

**Measured by hand first**, `env -i` with a PATH containing no Node install at all, driving
the ALREADY-BUILT engine at `tjsDir()`'s reported path:

    $ env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin HOME="$HOME" \
        "$E" run libexec/node-shim/loader.cjs scripts/build-tjs.cjs --source-only
    fixup libuv-hrtime-old-darwin: applied
    ...(31 more fixups)...
    fixup import-meta-require: applied to src/modules.c
    fixup import-meta-deserialize: applied to src/mod_engine.c
    fixup qjs-import-meta-by-identity: applied to deps/quickjs/quickjs.c
    fixup qjsc-msvc-getopt: applied (src/qjsc.c)
    esbuilt 16 plain-JS bundles for the BE regen path
    source tree ready: /Users/schmonz/.cache/clode/tjs-vendor/txiki.js
    $ echo $?
    0

`command -v node` against that same bare PATH returned nothing first — the test asserts
this itself, before asserting anything else, because a run with Node reachable proves
nothing.

**Proven able to fail.** A tiny `.mjs` (`import fs from 'node:fs'`) run the same way through
the same loader produces exactly the SyntaxError that motivated Tasks 1-2:

    SyntaxError: Unexpected identifier 'fs'
        at <anonymous> (<input>:3:10)
        at Function (native)
        at evalModule (libexec/node-shim/loader.cjs:489:18)
        ...
    exit 1

Wired into a throwaway copy of the test (assert `status === 0` against that same probe), it
failed under `node --test` with `1 !== 0` — the gate is not one that can only pass.

**What this does NOT prove.** `build-tjs.cjs` has exactly one surviving top-level `await`
(`const cosmoccBin = await provisionCosmocc()`), reached only `if (cosmoTarget)`. `cosmoTarget`
is false on this leg and every non-cosmo leg, so `--source-only` here never executes that
async continuation under the shim. Only a `CLODE_TJS_TARGET=cosmo` run would exercise it, and
that pulls a 441MB pinned download — out of scope for this gate. The test's header comment
carries this caveat so the proof cannot be misread as covering more than it does.

**Full suite:** 2089 tests / 2053 pass / 0 fail / 35 skip / 1 todo (baseline 2088/2052/0/35
plus this one new passing test; unchanged otherwise — this phase changes no behaviour).

**Scope check against the acceptance list:** `grep -c 'import\.meta' scripts/build-tjs.cjs`
is 18 (all inside C-fixup string literals/comments, none executable); the four orchestration
files (`build-tjs`, `tjs-source-reset`, `engine-api-floor`, `build-depscan`) are all `.cjs`;
`test/depscan-build.cjs` has no ESM bridge left. Linux and Windows legs proving the same
thing is deferred to CI exercising it — this task's proof is darwin-only, by hand and by test,
on this box.

## ★ Phase 4c-1 SHIPPED — the engine build runs with Node ABSENT (2026-09-17)

Spec §11 acceptance 1, met on darwin and proven by transcript rather than argument:

    $ env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin   ->  node: NOT FOUND
    $ "$ENGINE" run libexec/node-shim/loader.cjs scripts/build-tjs.cjs --source-only
      fixup qjs-import-meta-by-identity: applied to deps/quickjs/quickjs.c
      esbuilt 16 plain-JS bundles for the BE regen path
      source tree ready: ~/.cache/clode/tjs-vendor/txiki.js          exit 0

The thing that reconstructs the engine now runs ON the engine — a Mach-O arm64 binary this
project built. Four files became CJS (`build-tjs`, `tjs-source-reset`, `engine-api-floor`,
`build-depscan`), because `libexec/node-shim/loader.cjs` hosts CommonJS and CANNOT host an ESM
entry at all (`:481` guards its transpile with `!isEntry`; `import.meta` is a hard SyntaxError
even on the transpiled path). Red proof: that same loader, handed an ESM entry, rejects it with
`SyntaxError: Unexpected identifier 'fs'`.

**The true code delta is 12 lines** — ten imports and two `import.meta` uses. The other 18
`import.meta` mentions are PAYLOAD inside C-fixup string literals that teach txiki about
`import.meta` for the built product; a new guard pins the count at 18, their position after the
fixup banner, and per-fixup counts, so an edit cannot silently drop one.

### Two defects, and both were gates rather than code

**1. CJS forbids top-level `await`, and there was one nobody had found.** `const cosmoccBin =
await provisionCosmocc()` sits inside a top-level `if (cosmoTarget)` — legal ESM, rejected by
CJS. Everything from there to EOF now runs in `(async () => {…})().catch(…)` with
`process.exitCode = 1`; without that catch a rejected continuation would have exited **0**.
The arrow's body is deliberately NOT indented: indenting would rewrite ~550 untouched lines and
break the source-text gates that slice this file on column-0 `function` anchors (real — e.g.
`test/tjs-darwin-poll-fixup.test.cjs:139`).

**2. Moving that boundary killed `--regen-only`, and CI runs it.** `if (regenOnly)` sat ABOVE
the arrow calling four `function` declarations now inside it; function declarations hoist to the
ARROW's scope. `node scripts/build-tjs.cjs --regen-only` died with `ReferenceError:
buildHostTjsc is not defined`, on the path `.github/actions/build-leg/action.yml:594` runs for
the qemu guest-bake legs.
**2,085 green tests said nothing**, because the test "covering" `--regen-only` asserts on SOURCE
TEXT (`assert.match(buildTjsSrc, /buildHostTjsc\(/)`) — which passes on a file where that call is
a guaranteed ReferenceError. Now there is a test that EXECUTES it and asserts `at buildHostTjsc `
appears as a STACK FRAME, which a mis-scoped name cannot produce, plus a `defineGuard` that fails
if any function declared inside the continuation is named above it.

### Three gate-coverage regressions the branch introduced, found only by the whole-branch pass

None was a behavioural defect. All three were things still TRUE but no longer CHECKED.

- **All four converted files fell out of the zero-npm-dependency gate.**
  `test/clode-self-deps.test.cjs` filtered `scripts/` for `.mjs` only, so the rename made them
  unreachable. `require('semver')` in the 3,871-line file 42 legs depend on would have stayed
  green, and the gate's own anti-vacuity check could not notice because it still walked 72 files.
  Fixed, walk 71 -> 80, **zero violations on its first honest run** — plus a by-NAME assertion,
  because a COUNT check would not have caught this.
- **`'use strict'` landed on 1 of 4.** ESM is implicitly strict, CJS is not, so the other three
  were silently loosened. Per-task review could not see it: the leaves shipped before the ruling
  existed, and the next task's review scoped to `build-tjs`.
- **The flagship acceptance ran only on one laptop.** It hand-rolled engine resolution, so it
  ignored `CLODE_TJS` (set at nine places in `ci.yml`) and looked for `tjs` not `tjs.exe` on
  Windows — telling developers there to build an engine they already had. Now resolves via
  `tjsPath()`, with an explicit win32 skip naming the POSIX probe as the reason.

### OPEN — filed, not fixed

- **The cosmo `await` path is never exercised.** `if (cosmoTarget)` is false on every non-cosmo
  leg, so the async continuation is not on the wire. Only `CLODE_TJS_TARGET=cosmo` reaches it,
  and that needs a 441MB pinned download. Named in the test header and here.
- **Linux and Windows unexercised.** The acceptance can now RUN in CI, but runners have no vendor
  checkout, so it will honestly SKIP. Real matrix coverage needs a leg with both an engine and a
  checkout.
- `scripts/engine-recipe.mjs`'s `FILES` names `build-tjs.cjs` but not the three leaves — an edit
  to `tjs-source-reset.cjs`, which decides what "pristine" means before the patch stack applies,
  moves no recipe hash, so the cache can restore an engine built by a different recipe.
- The shim rewrites the entry's text for `import(` and `\p{}` regex flags; only `import.meta` is
  gated. A future fixup payload containing either would be silently corrupted under tjs and
  correct under Node — a Node-vs-tjs divergence with no gate.
- `docs/dev/windows-dev-setup.md` still names the old file (untracked, but a live how-to for the
  one platform this phase admits is unexercised).