mcpx: a promise and a behaviour that disagree — every declared surface needs a guard that walks it (tracker) #1893

Relocated from dezren39/darwin-nix#177 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #181

Purpose

Six open issues are filed separately and are the same bug six times: something mcpx
declares does not do what the declaration says. A doc promises a capability the binary
does not have (#102, #159). A flag is accepted and is inert (#108). A function is built,
tested and never called (#116). An env var is honoured and declared nowhere (#172). A
concept — "a script file" — is resolved one way locally and another way remotely (#106).

Every one of them was found by a human, by hand, after shipping: reading --help, reading
a flag definition, trying a documented example. None was found by a test, because no test
was watching the seam. That is the argument for treating them as one item: fixing the six
instances leaves the seam unwatched and the seventh arrives on schedule.

Done looks like: each instance fixed, and — the part that matters — every surface in
mcpx that declares a set of things has a test that walks that declaration and proves each
member does something observable. The inventory below is the checklist for the second half.

The class, stated

A promise-and-behaviour disagreement is any place where mcpx publishes a set — commands,
flags, routes, tools, settings, environment variables, documented capabilities — and a
member of that set does not do what publishing it implies. The failure mode is specific and
nasty: it is indistinguishable from success. A flag that does nothing parses cleanly and
exits 0. A documented feature that does not exist reads exactly like one that does. An
unread setting appears in mcpx settings. The user's evidence and the code's behaviour are
both silent, so the bug survives until somebody tries the thing for an unrelated reason.

This is distinct from a plain defect, where something is attempted and produces a wrong
answer. Here nothing is attempted at all, and the surface reports that everything is fine.

Instances

• Bump build/buck/preludes/buck2-prelude from d956689 to f12c8d1 #102 an adapted binary is not callable from a script, though the docs say it is — docs/story.md says an adapted CLI "is callable from a script"; adapter tools are attached as mcpserver.Extra (internal/cli/serve.go:346,391) and internal/codegen never sees Extra, so they reach tools/list over /mcp and stdio and appear in no generated client, no mcpx ls, no script. Confirmed on 8001f23: rg Extra internal/codegen returns nothing.
• Bump h2 from 0.3.19 to 0.3.24 in /sources/pavex/examples/realworld #106 exec should run any shebang, and resolve file scripts the same way local or remote — half of this issue belongs to this class and half does not. The class half: file means two different things. The CLI resolves a script name against a search path (resolveScript, internal/cli/scripts.go:254), while /v1/exec passes req.File straight through (internal/execsvc/execsvc.go:326) to runner.Options.File, which does filepath.Abs and runs it (internal/runner/runner.go:293), so a name that works locally is a path error remotely, and docs/exec.md's "a remote run sends the script's text, not its path" is true of the CLI and false of the endpoint. The not-class half — shebang dispatch, script.interpreter, script.cwd — is new feature work and is tracked there on its own merits, not here. Bump h2 from 0.3.19 to 0.3.24 in /sources/pavex/examples/realworld #106 is tracked natively under fix(id): make Nix E2E check reproducible #175 (runtimes and languages), which was created in the same session and claimed it first; it is listed here as a member of the class for its resolution half only.
• Bump build/buck/preludes/buck2-prelude from d956689 to cb5dc60 #108 --runtime node rejects TypeScript that Node runs, because of one flag — internal/runner/runner.go:100 still passes --no-warnings --experimental-strip-types; on Node 24 strip-types is the default (the flag enables nothing) and it is the wrong flag anyway (--experimental-transform-types is the one that compiles enum). The flag is accepted by Node, exits 0, and is inert — which is why an "every flag we pass is accepted" check would not catch it.
• chore(deps): update github.com/developing-today-forks/charm digest to 15e844d - autoclosed #116 diagnose.CallError is built and tested but never called — internal/diagnose/diagnose.go:483, tested in internal/diagnose/diagnose_test.go, zero non-test callers outside the package. Re-verified on 8001f23. Users get Error: -32602 invalid params where the function already produces the argument at fault and the date its schema changed.
• Phase 2: membership, delegation, groups, and server config #172 44 MCPX_* variables the code reads that no setting declares — 64 distinct MCPX_* names are referenced in non-test code; the registry declares 152 settings; 44 referenced names are not among them. Re-counted on 8001f23. The counts depend on the allowlist and have never been reconciled with Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159's "about 49" — that is Phase 3: sync, blob gate, and relays #181 collision 17, owned by Phase 2: membership, delegation, groups, and server config #172, whose first deliverable is the allowlist itself. The inbound ones (MCPX_CONFIG, MCPX_CACHE_DIR, MCPX_ENDPOINT, MCPX_ALLOW_READ, …) are real user knobs with no config key, no flag, no /v1/settings row and no MCP tool. The outbound ones (MCPX_CWD, MCPX_CALL_ID, MCPX_HARNESS, …) are a contract with the script that is declared nowhere at all.
• Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 the sources the reference would be generated from are incomplete, and several docs say what the code does not — the docs-side inventory of the same class: Commands() is not the one command list, mcpx openapi publishes a removed server, docs/parity.md is stale and nothing reads it, docs/opencode-plugin.md:406 says the plugin "Sets MCPX_SESSION, MCPX_CALL and friends" when the plugin actually sets MCPX_SESSION_ID and MCPX_CALL_ID (plugin/opencode/mcpx-session.ts:670,677), and four documents claim mcpx is dependency-free while go.mod requires five. Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 is tracked natively under Bump golang.org/x/crypto from 0.16.0 to 0.17.0 in /sources/import #96 (generated reference); it is listed here as a member of the class, not adopted, because GitHub allows one parent per sub-issue.

Added to this tracker in the 2026-09-30 issues pass, after the bodies above were written. Each is
the same shape; none changes the thesis.

• Phase 3: range read_flight buffers frames with no cap while more is set #178 the nix derivation's generated man page, completions and version are unverified, and one of them is not reproducible — postInstall runs mcpx man and mcpx completion <shell> and inspects neither; internal/cli/manual.go:335 stamps time.Now() into a nix output; 0.1.0 is written in three build-relevant places (package.nix:19, :61, cmd/mcpx/main.go:18) that nothing keeps in agreement, and internal/testsupport/build.go:63 builds the e2e binary without the ldflags, so it will silently disagree on the first bump.
• Phase 3: /id-sync/1 is used by both range and LogSync handshakes #179 registry.pageSize is read but unreachable, and nextCursor is parsed and dropped — the setting is consulted only inside if limit <= 0 (internal/registry/registry.go:154-156), so it passed Phase 2: delegated Manage cannot add members #171's sweep while being inert to every ordinary caller. That is a hole in the newest guard in the repository and it is why this tracker's inventory is not finished when a surface is merely "guarded".
• Phase 3: sync data phase batches are bounded by count, not bytes #180 re-verification of twelve reported findings, with corrected counts and two claims whose framing is wrong — the review artefact for this class. One of its corrections stops a wrong fix (MCPX_SESSION); another disproves the static-binary blocker outright.
• Phase 5: persisted incremental tag index #183 ForConfig's comment describes keying that was deliberately removed — internal/daemon/paths.go:79-82 promises that editing a config produces a new daemon key; FingerprintConfig (:192) hashes the file paths. The code is right and the prose is wrong, on the one function whose semantics the fingerprinting rework was about.
• Phase 3: test_an_interrupted_session_restarts_without_duplicates flakes under full-suite load #188 Resolved.PoolID hashes Headers in map order — internal/config/config.go:371-373 ranges over a map while the Env block six lines above sorts its keys, so one configuration yields different pool ids across calls. The file already declares the rule and one branch breaks it.
• Phase 4: joiner misses an update made without knowing its concurrent add #189 the opencode plugin sends field names the daemon does not read — DaemonClient.call sends arguments/sessionId/callId (plugin/opencode/mcpx/daemon.ts:471-473); /v1/call reads args/session/context (internal/api/ops.go:382,110-113). Arguments and session are both dropped, and the plugin README documents the call. Plus mcpx_exec passing no session and rendering an output field execsvc.Result does not have.
• Serve stalls before printing node in test_world_module_shared_over_iroh_and_web_presentations #190 a wrong-case cwd on a case-insensitive volume keys separately from the on-disk spelling — canonical() (internal/config/scope.go:188-201) resolves symlinks and keeps the given spelling, so one directory gets two scope keys. Over-isolation, never accidental sharing.
• Phase 4: groups, encryption, and history #191 the degraded-scope log line says 'per-call' when the key is the directory — internal/daemon/registry.go:761 hard-codes "degraded to per-call" while repo/worktree/cwd fall back to cwd:<dir>, shared by every caller there. A diagnostic that reports the opposite of what happened.
• Phase 4 fix: a joiner fetches the epoch it missed #192 a remote exec accepts and drops most exec flags — Update Rust crate petgraph to 0.6.4 - autoclosed #74's class on the path Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75 did not cover.
• id: lib does not build with --no-default-features #193 /v1/events replay drops everything past 256 events without a gap marker — documented as lossless, and silent when it is not.

Precedent (closed)

Each of these was the same class, each was fixed as a one-off, and each was found by a
person noticing rather than by a test failing.

• Bump checkmarx/ast-github-action from 2.0.19 to 2.0.20 #39 (merged) — mcpx declared MCP sampling and the passthrough from fix(deps): update rust crate serde to 1.0.188 - autoclosed #31 was unreachable: the handler was installed after the handshake, so the capability was announced and never offered. Found while answering "what was the decision for sampling?", not by a test — the tests called the passthrough directly, which is how it passed.
• Update Rust crate bimap to 0.6.3 #66 (merged) — mcpx exec --typecheck=on accepted the flag and ignored it, because opts.TypeCheck was assigned inside the else branch of the inline/file split. Found by asking "does a typo'd namespace fail validation or partially run?" It partially ran. Two further faults were stacked underneath it and each hid the next.
• Update Rust crate petgraph to 0.6.4 - autoclosed #74 (closed) — --launcher and --allow-repeat accepted by mcpx exec and silently dropped, because writeLauncher was guarded by if opts.File != "". Filed with the observation that this was already "the third instance of the same shape", and the proposal that a test should walk the command table.
• Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75 (merged) — the fix. Auditing the one flag found five: --launcher, --no-launcher, --export, --allow-repeat, --no-capture-console, all defined for exec, all in its help, all read only when a file was given. It shipped TestEveryExecFlagChangesSomething, and its closing note is the thesis of this tracker: "This fault has now shipped three times … and each was found by accident, because a flag that does nothing looks exactly like a flag that worked."

Four closed instances, six open ones, ten total, zero found by a test written to find them.

The systemic fix: guard tests

The repo has already invented the answer three times without generalising it. A guard test
takes a declared set and asserts that every member of it does something observable.

consumed_test.go is the most developed of the four and worth reading before writing the
next one, for two reasons stated in its own header comment. First, it rejects the obvious
design — a ReadBy: "daemon" field on the declaration — because "that note sits in the same
struct literal as the declaration, gets written in the same keystroke by someone who believes
both halves, and nothing checks the second." A guard must ask the code, not the author.
Second, it narrows the question from "does this string appear anywhere" to "is it handed to
an accessor on a resolved Set", because pool.max was honoured from a config file and
ignored from its variable and its flag — half-read, which a grep calls live. It found 54
dead settings of 149 (#171).

The generalisation: for every surface that declares a set, there is a test that walks the
declaration and proves each entry does something. Where no declaration exists, the first
task is to create one — an undeclared set cannot be guarded, only audited by hand, which is
what got us here.

Surface inventory — guarded vs unguarded

Counts and line numbers checked on 8001f23.

Eleven unguarded surfaces, four guarded, two guarded in one direction only. Every open
instance in this tracker sits on an unguarded row.

Division of labour with #129

#129 (mcpx testing: guard tests that close a whole bug class, under #99 under #91) and this
tracker are the two halves of one subject and must not be merged or duplicated.

Concretely: the surface inventory table above is this tracker's output and #129's input.
When #129 picks its next guard, it picks a row from that table. When a fix here closes an
instance, it reports back which row moved from unguarded to guarded. #129's mechanics
sections (approaches A/B/C for writing guards, the no-network sub-choice, the exemption
ratchet, the negative-test requirement) are not restated here and should not be.

Overlap to watch: #129's candidate list already names "every exec/run flag has a row",
"every command's flags", "every /v1 op has a CLI command", and the #102/#106 parity
tests. Those are #129's to build. This tracker's job is to make sure the list is complete
and that the underlying bug is actually fixed, not merely guarded against recurring.

Proposed order

1. Bump build/buck/preludes/buck2-prelude from d956689 to cb5dc60 #108 — one line, --experimental-strip-types → --experimental-transform-types, plus a test that a file containing enum runs under --runtime node. Ease S, high impact, no dependencies. Ship it first because it is the cheapest possible demonstration that the pattern pays: the fix and its guard are both smaller than this paragraph.
2. chore(deps): update github.com/developing-today-forks/charm digest to 15e844d - autoclosed #116 — wire diagnose.CallError at the daemon's call boundary. Ease S for the wiring. Second because it is also small, and because a function that has been tested-but-uncalled for months is the clearest illustration of the class to anyone who has not seen it.
3. Bump build/buck/preludes/buck2-prelude from d956689 to f12c8d1 #102 (doc half) — delete the false sentence from docs/story.md now. There is no reason to keep shipping a known-false claim while the capability is designed. Minutes.
4. Phase 2: membership, delegation, groups, and server config #172 (inbound half) — move the inbound MCPX_* variables into the registry. Mechanical, 44 decisions, and each one converts a source-only knob into four surfaces at once. Do this before the generated reference (Bump golang.org/x/crypto from 0.16.0 to 0.17.0 in /sources/import #96/🎨 Palette: Improve accessibility of editor search panel #144/⚡ Bolt: Optimize cursor color generation and position grouping #145) is built, or the reference is generated from an incomplete source.
5. Bump h2 from 0.3.19 to 0.3.24 in /sources/pavex/examples/realworld #106 (class half only) — one script-resolution rule for CLI and daemon. Larger, and it unblocks the harness-free plugin (Update Rust crate anyhow to 1.0.75 #48, Bump rustls-webpki from 0.100.1 to 0.100.2 in /sources/pavex/examples/realworld #44), which has a socket and no binary and therefore cannot resolve a name locally.
6. Bump build/buck/preludes/buck2-prelude from d956689 to f12c8d1 #102 (capability half) — extras as a real tool source, via chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 36464cf #83, with the tools/list ↔ generated-client parity test.
7. Phase 2: membership, delegation, groups, and server config #172 (outbound half) — declare the script environment contract, then guard it.
8. Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 — under Bump golang.org/x/crypto from 0.16.0 to 0.17.0 in /sources/import #96, on its own schedule; sequence it so the doc fixes land before anything is generated from those sources.

Added in the 2026-09-30 pass, slotted by cost rather than appended:

• Beside step 1, because each is smaller than its description and none has a dependency:
  Phase 3: test_an_interrupted_session_restarts_without_duplicates flakes under full-suite load #188 (sort the header keys — three lines and a determinism test), Phase 4: groups, encryption, and history #191 (pass the resolved
  key into the log line — one parameter), Phase 5: persisted incremental tag index #183 (correct one comment and assert the two
  properties it should have described), id: lib does not build with --no-default-features #193 (the events replay gap marker; Phase 4 fix: a joiner fetches the epoch it missed #192 is the same
  — Update Rust crate petgraph to 0.6.4 - autoclosed #74's class on the remote path).
• Beside step 2, because it is the same "hand-written client disagrees with the declaration"
  shape and the first half is an hour: Phase 4: joiner misses an update made without knowing its concurrent add #189's three field renames. Its generated-types half
  belongs with Update Rust crate clap to 4.5.4 - autoclosed #76's approach C, not here.
• Before the release work in amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158: Phase 3: range read_flight buffers frames with no cap while more is set #178. A release pipeline needs a reproducible derivation,
  one version source, and generated artefacts it can trust; none of the three exists yet.
• Phase 3: sync data phase batches are bounded by count, not bytes #180 first of all of them, as the super tracker says: it is editing rather than engineering,
  and one of its corrections stops a wrong fix (MCPX_SESSION) and another removes a blocker that
  was never real (the static-binary claim).
• Phase 3: /id-sync/1 is used by both range and LogSync handshakes #179 feeds Add omasnap upstream repository to flake inputs #129 rather than waiting on it. The two defects are small; the finding — that
  consumed_test.go proves a setting is read, not that reading it changes behaviour — is the
  input Add omasnap upstream repository to flake inputs #129 needs, and it must be applied before or with Phase 2: membership, delegation, groups, and server config #172's 44 new declarations.
• Serve stalls before printing node in test_world_module_shared_over_iroh_and_web_presentations #190 is the one that needs a decision before code. Case-folding is the obvious answer and the
  wrong one; it trades over-isolation for accidental sharing. Read its approach C first.

Throughout: each fix names the surface row it sat on and hands it to #129. A fix that closes
an instance without identifying its row has not finished.

Ease / impact

Pulled verbatim from each instance's own footer.

Warnings

1. A guard that cannot be enumerated is a reminder, not a guard. TestEveryExecFlagChangesSomething is the cautionary example in this repo: it was written as the fix for Update Rust crate petgraph to 0.6.4 - autoclosed #74/Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75 and it has four rows against 23 hand-declared flags plus every exec-scoped setting the registry binds, including three flags Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75 itself repaired. Its comment says "Add a row when you add a flag" — which is the memory the guard was created to replace. Any new guard that starts from a hand table inherits this failure on day one.

2. Acceptance is not effect, and Bump build/buck/preludes/buck2-prelude from d956689 to cb5dc60 #108 is the proof. Node 24 accepts --experimental-strip-types and exits 0. A guard asserting "every flag we pass to a subprocess is a flag that subprocess accepts" passes cleanly on the exact bug in this tracker. Guards must observe a difference in outcome (the Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75 with-and-without pattern), never the absence of an error.

3. Fixing all six without adding guards is the failure mode this tracker exists to prevent. Bump checkmarx/ast-github-action from 2.0.19 to 2.0.20 #39, Update Rust crate bimap to 0.6.3 #66, Update Rust crate petgraph to 0.6.4 - autoclosed #74 and Update Rust crate proc-macro2 to 1.0.81 - autoclosed #75 were each fixed individually and correctly, and the class arrived four more times. If the fix PRs land and the inventory table above is still eleven rows of "unguarded", nothing has been learned — record that plainly in the closing comment rather than closing quietly.

4. A guard with an allowlist decays into a no-op unless something shrinks it. TestNoPackageRedeclaresADefault exempts eight whole packages via outOfScope "owned by work happening in parallel", and that parallel work has since landed. consumed_test.go's unreadAllowed has exactly one entry with a paragraph of justification — that is the standard to copy, and Add omasnap upstream repository to flake inputs #129 owns the ratchet that enforces it.

5. Regex source scans pass silently when they are wrong. PR chore(deps): bump rustix from 0.37.19 to 0.37.25 in /sources/pavex/examples/realworld #56: the defaults guard matched "5 * time.Minute" while gofmt writes 5*time.Minute in call arguments, so nine live constants were invisible and the test reported green. Two of the six guards in the table above are regex scans. Prefer walking a registry; use go/ast when there is no registry; never regex when a declaration exists to enumerate.

6. Do not run the full test suite to check any of this. go test ./... is ~135 s with internal/e2e at ~101 s. The four-hour daemon leak is fixed — Phase 5: tag event bodies must travel with the event #182 closed chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to e7457f6 #52 by having cleanup call stop --all through the daemon-<key>.json info files and setting MCPX_AUTOSTART_IDLE_EXIT=60s in every test environment (internal/e2e/e2e_test.go:68-83) — so the reason is now time, not hygiene. What is still true is Update dependency htmx.org to v1.9.12 #138: the suite inherits the caller's environment, so a run can reach a developer's real daemon. Run the specific package.

7. Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 and Bump h2 from 0.3.19 to 0.3.24 in /sources/pavex/examples/realworld #106 must not be re-parented. Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 is a native sub-issue of Bump golang.org/x/crypto from 0.16.0 to 0.17.0 in /sources/import #96, Bump h2 from 0.3.19 to 0.3.24 in /sources/pavex/examples/realworld #106 of fix(id): make Nix E2E check reproducible #175, and GitHub permits one parent. Adopting either here would silently remove it from the tracker where the work is actually scheduled. Native sub-issues of this tracker at 05c78b2 are Bump build/buck/preludes/buck2-prelude from d956689 to f12c8d1 #102, Bump build/buck/preludes/buck2-prelude from d956689 to cb5dc60 #108, chore(deps): update github.com/developing-today-forks/charm digest to 15e844d - autoclosed #116, Phase 2: membership, delegation, groups, and server config #172, Phase 3: range read_flight buffers frames with no cap while more is set #178, Phase 3: /id-sync/1 is used by both range and LogSync handshakes #179, Phase 3: sync data phase batches are bounded by count, not bytes #180, Phase 5: persisted incremental tag index #183, Phase 3: test_an_interrupted_session_restarts_without_duplicates flakes under full-suite load #188, Phase 4: joiner misses an update made without knowing its concurrent add #189, Serve stalls before printing node in test_world_module_shared_over_iroh_and_web_presentations #190, Phase 4: groups, encryption, and history #191, Phase 4 fix: a joiner fetches the epoch it missed #192 and id: lib does not build with --no-default-features #193; Bump h2 from 0.3.19 to 0.3.24 in /sources/pavex/examples/realworld #106 and Root flake check fails on nixosConfigurations due to missing clan-core.clanModules #159 are members of the class listed in the task list above and nothing more.

Related

Parent: #181

Related: #129 (the testing-side half — guard mechanics and policy; read it before writing any
guard), #99 (its tracker), #91 (the strategy above both), #49 (CI for every package — a guard
that does not run in CI is a guard nobody runs), #52 (closed, fixed in #182 — the leak is gone;
#138 still owns the environment-inheritance half), #159 (member of this class, tracked natively under #96), #175 (runtimes tracker, which owns #106), #171 (the merged settings
audit that produced consumed_test.go and found 54 dead settings of 149), #83 (one tool-source
interface, which #102's capability half belongs to), #76 (CLI ↔ /v1 parity, an unguarded row),
#96 / #144 / #145 (the generated reference, which reads several of these declarations and will
publish whatever they contain).

Closed precedent: #39, #66, #74, #75.

Security/auth deferred; see tracker.