[viztor]

Phase 0 of the architecture review. It does three things:

• makes the suite deterministic: right engine, offline, independent of test order;
• fixes ten confirmed defects, each with a test that fails without its fix;
• adds docs/improvement-plan.md, the reviewed plan for everything after this PR.

The suite

Before	After
Below Node 24, three cases failed for engine reasons (node:sqlite, Intl.DurationFormat, ICU strings) that looked like regressions	the run refuses to start below engines.node and names both versions; .node-version pins Node 26
engines promises Node 24, but no job ran it	a new CI job runs the unit suite shuffled, plus the mock suite, on Node 24
the "offline" unit suite made 54 requests per run to models.opencode.ai (the catalog's background refresh), so a networked runner could swap the catalog mid-test	test/support/offline.ts refuses every non-loopback request in the unit and mock suites; e2e keeps the network
shuffled runs failed on seeds 42 and 1234 (captured keys, session spend and the live catalog leaked between tests)	test/support/reset-process-state.ts resets all three after every test; pnpm run test:shuffle
the client-bundle boundary was guarded only by a size tripwire	architecture.test.ts walks the bundle's import graph and fails on node:*, cordis, pi or process.env (checked by planting a violation)
the host/client parity test grepped for a string literal, so a namespace passed as a constant slipped through	it resolves constants and checks every declared Remote method

Defects fixed

Every fix has a regression test, and each test was run against the old code and failed.

• Host crash risk. A rejected internal-route mount escaped as an unhandled rejection. mountInternalRoutes now owns the mount and reports the failure.
• Leaked registrations. Three early exits leaked the Google bridge registrations, so the next reload failed with DUPLICATE_ADAPTER. A mount that failed to start kept its fiber and its routes.
• Reloads ignored. Model discovery answered from the first activation's settings for the life of the process. Phase P3 deletes that registration anyway, because Settings never queries it.
• Foreign providers. The listing and model-info patches rewrote providers this plugin does not claim, such as a direct anthropic or openai route.
• Relay listing. A relay's Go /models was answered with the Zen catalog.
• Free models. The free-model check never read a Request body, which is how DSH sends a turn, so every keyless free turn was reported as a missing credential.
• Meter session. The meter's session fallback picked the newest session, not the one that just ran.
• Key tiers. A key's tier was read from its prefix. OpenCode issues oc_sk_ for Go too, so a working Go key was filed under Zen, and an OpenAI sk- key on a claimed relay was filed under Go.
• Store inspection. The store-inspection row called opencodeStore, which the client never mounted. The descriptor is now added, with a whitelist codec.
• Store reader. The credential reader's legacy-row fallback was not per integration, so one flagged Go row hid the Zen key.

Reviewer notes

• tierForRequest no longer takes the key. Three tests that pinned the prefix rule were rewritten to the rule docs/engineering-notes.md records as measured: the observed URL decides, then the route.
• CLIENT_BUDGET is raised to 136 KB for the store descriptor and its parser, on top of what main added since. That is about 1.2 KB of source, not a dependency, and is the gate's own "raise it" case.
• The no-credential warning no longer says "sign in through the settings card", which this build does not have.
• AGENTS.md no longer describes nine login modules that do not exist. CONTRIBUTING.md documents the new test rules.

The plan

docs/improvement-plan.md is the plan of record. A nine-lens review, with two independent skeptics per finding (78 of 82 upheld), is folded into it. It contains:

• the owner's decisions (D1–D25);
• what the DeepSeek Harness host supports, read from its source (F1–F20);
• the defects this audit found, and where each now stands (several are fixed on main);
• the routing design, measured on the real host (pi 1.1.0 then; the pinned cell is now 1.3.0 with the alpha harness's patch, D14');
• 21 phases (P1a through P12, including the new P-R3), landing as stacked pull requests on this one, with a status table each phase updates.

The plugin owns opencode and opencode-go.

• An outermost internal/config filter keeps pi-ai from claiming the two routes, and the plugin registers its own adapter under the same ids. It never deletes another plugin's registration.
• That adapter serves every protocol per model, any catalog model, and any custom id.
• The user's file is never written. A read-only wrapper on settings.describe keeps the Models page showing both providers.

Decisions:

• Protocol. The catalog map decides it, never a guess at the model's name.
• Precedence. Catalog first: the user's row, then the catalog, then pi.
• Reasoning. A model whose reasoning is only on/off is offered as Off / On. Old Minimal/Xhigh/Max selections on such models break, and the release notes say so.
• Releases. Everything ships as 1.x minors. internalRoutes, resolveRoutedKey, three plugin settings and the deprecated @viztor/dsh-opencode wrapper go.

Before routing changes, two harnesses pin today's behaviour:

• a real-host test harness (a bare cordis/llm/llm-pi-ai tier, and a boot tier with ConfigEditor and Settings);
• a CI job that boots the published dsh offline, for the pinned pi (1.3.0 + the harness's patch) and whatever the registry resolves for the published wrapper.

Restacked onto main 1.8.0

This branch was cut from main 1.4.1. main (1.8.0) is merged in once, here; every PR above merges its parent.

• Scope now: P0 on main 1.8.0. Suite hardening (engine floor, offline guard, per-test reset and shuffle, client-boundary gate); the lifecycle, mount and credential fixes main lacks (the free-model check on a Request body, now with main's URL plane; the relay's Go listing; the key tier decided by the URL; the meter's session fallback; the store-inspection remote mount); and D23's freshness scoping with --copies, with the generated-table skip in scripts/vendor-version.ts, which joins the strict input list.
• Taken from main as-is: the regenerated catalog and allowance tables (chore(catalog): regenerate for the Argon rename and the Go plan's new allowances #132; the generated files are main's blobs, and every count in the docs is re-derived from that shim, dated 2026-10-31), the per-plane pricing and the debugFile rule (fix: the plane decides the price, the flag and the refusal #133, recorded as D24), the wrapper forwarder (fix(publish): the retired alias must LINK, not fail on every load #135; P2 retires the wrapper again, D9), readAccount (fix(usage): answer the whole opencodeGoUsage contract, for the sibling page and the client #137), coreToolDecision and the catalog fixtures (feat(test): a fixture harness for the worlds the vendor has not produced #138, D25), the docs-pairing gate and test/e2e/verdict.ts (feat(test): gate the language pairs, and lift the live-run rules out of the e2e #140), the mock's base coverage (test(mock): the mock must serve every base the plugin can produce #142), the Go-limits HTML reader (test(scripts): the Go-limits HTML reader, which is the half that broke #143), the CLI-version rules in scripts/vendor-version.ts (test(scripts): the CLI-version gate's rules, which have passed while wrong twice #144, now on D23's strict list), the testing guide (docs(testing): the scripts' pure halves, and why they moved out #145) and the plugin page (feat(plugin-page): a curated page and a featured image, instead of the whole README #146–feat(plugin-page): the page is a picture, like the upstream plugins' #150).
• Dropped from this PR, because main already has them: the three catalog refreshes, the pricing fix, the local copies of the e2e verdicts (only an upstream's 400 "Model is unavailable" is ported into verdict.ts, with a probe-verdict row), the usage-panel test, and the remote-count assertion main's readAccount invalidated.
• Resolved on the way: the free-model check reads the body once and asks the URL's plane; plane-lookup installs its world before each test; the generated-table skip moved into vendor-version.ts with a test row; the client bundle ceiling is 136 KB for the store descriptor on top of what main added.
• The plan carries D14' (the pinned cell runs the pi the alpha harness tag pins, with its patch; the floating cell runs what the registry resolves), D22' (the alpha.2 cluster, named once), D17's defaults restated as pi-ai's current ones, D24 and D25.
• Live re-measures CI must confirm (the catalog host is unreachable from where this was restacked, so nothing was regenerated here):
  • the catalog freshness job: src/catalog-data.ts and src/go-limits-data.ts (main's 2026-10-31 blobs) are current. If it reports drift, the nightly refresh regenerates them, and the counts in the READMEs, the docs and the tests (80 Zen, 23 without an SDK, 30 Go) are re-derived from the new shim;
  • the registry-listed counts in docs/redirect-planes.md (130 Zen, 37 Go) come from main and from the live registry, not the shim, so only the live job can confirm them;
  • the live protocol-routing job: the free-tier walk now skips when every candidate was busy and reads a 400 "Model is unavailable" as a retirement; confirm the free-tier and subject-picking cases still find a subject.

Verification

All run locally on this head. main was measured the same way, on an export of origin/main against this branch's install.

Node	Step	Command	Result
26	lint, format, types	pnpm run check	0 errors; 23 warnings, the same count as main and the pre-restack branch
26	unit suite	pnpm exec vp test run	85 files, 1315 tests pass (main: 83 files, 1236)
26	shuffled	pnpm exec vp test run --sequence.shuffle --sequence.seed=<n>	seeds 1 and 42 pass
26	gateway mock	pnpm exec vp test run --config vitest.mock.config.ts	52 tests pass
26	build and bundle gate	pnpm run build && node --experimental-strip-types scripts/check.ts	pass; consumer install loads both halves; client bundle 135,604 B under the 139,264 B ceiling
26	coverage	pnpm exec vp test run --coverage	96.41% statements, 92.05% branches, 96.25% functions, 96.4% lines; above the ratchet
26	CLI version	pnpm run cli:version	the pin is the published version and every copy agrees
24	floor	vp test run --sequence.shuffle --sequence.seed=7, then the mock suite	pass

The live suites (keyed probes, the e2e jobs) run in CI, where the keys are.

Follow-ups

• main: release.yml still quotes a pnpm version in the comment ci.yml no longer does.
• The README's "Verified on DeepSeek Harness 0.2.1" line waits for P-T1b's binary e2e on the alpha host.
• Three rows of the Chinese README (the protocol count, the Go Google route, the quota-ring row) are rewritten by P-R1's docs sweep, which replaces the routing prose they describe.

🤖 Generated with Claude Code

https://claude.ai/code/session_0141fKp5k6hiaJcP5ovhGtSD

[viztor]

813e6f3 ports the nightly catalog refresh (#111) into this branch, so this diff now touches src/catalog-data.ts and src/go-limits-data.ts. Both files are exactly what the generator wrote; neither was edited by hand.

The vendor added Go kimi-k3.1-pro, which turned catalog freshness red on every branch of the stack. On main, #111's own test job is red as well, because three assertions and two docs hard-code the catalog's size. The commit updates those counts here:

• the Go shim test: 28 → 29;
• docs/redirect-planes.md: Go served 28 → 29, and the no-SDK Go cell 17 → 18;
• the Go completions list in both READMEs.

I merged the commit up through #106 → #107 → #108 → #109 → #110 → #112. On each branch, the unit suite has the same test count as before and passes.

The port becomes a no-op once main carries the refresh. If #105 merges first, #111 has nothing left to add and can be closed. P-T2 turns these counts into invariants, so later refreshes stop needing this.

---

Generated by Claude Code

[viztor]

2ebaffc ports today's regenerated vendor tables into this branch, the same way 813e6f3 did, so catalog freshness is green again. In the Go plane, gemini-4-argon-contributor became gemini-4-argon and is now priced, and iceman-contributor-free was added. The fixtures, counts and README lists that named the old id moved with it.

e2e · live gateway failed on the same commit because of the vendor's live state. Three cases failed:

• Two get 400 Upstream request failed: Model is unavailable for the free nemotron-3-ultra-free on completions.
• One gets a 429 rate limit from the free beam-free.

That is the gateway's own "model is unavailable / rate limited" answer for free models. The commit touches neither model; it changes only the generated tables, test fixtures and docs. The same suite passed on this branch's previous head.

I re-ran the failed job once to tell a transient outage from a free model being retired upstream. If it fails the same way, the suite's free-model cases need to pick a model the gateway still serves rather than a fixed id. That work belongs to the stack's later phases (P-T2 removes hard-coded vendor ids from the suites), and I'll report it there rather than widen this PR.

---

Generated by Claude Code

[viztor]

059236a — ci: gate freshness only on a pull request's own generator changes

The repository owner chose this. The vendor moves its catalog, its Go limits page and its CLI version almost daily, and each move turned every open pull request red although none of them caused it.

What a pull request is now gated on. Each freshness check (catalog:shim, limits:shim, cli:version) fails a pull request only when the diff touches one of that check's inputs: the generator script and every local module it loads, transitively (type-only imports excluded), plus src/identity.ts for the CLI check. scripts/freshness-scope.ts derives those inputs from the sources, so a new import moves them without a list to edit. The offline check that every copy of the CLI version agrees with the pin still gates every pull request, because only the repository can break it. The gates fail closed: if the scope answer goes missing, the gate runs; the check is not skipped.

What it only reports. On any other pull request, vendor drift becomes a warning with exit 0, the same as a push to main already got. That includes a pull request that only carries a refresh. A generated file edited without its generator gets a warning that names the file. The nightly run still regenerates the two tables and opens the refresh as its own pull request, and it warns on the CLI version.

Tests that pin both paths (test/freshness-scope.test.ts):

• the decision, per check: a pull request touching its inputs gates; one carrying only a refresh reports; an unrelated diff or an empty diff reports
• the CI wiring, parsed from ci.yml: for each check, a pull request runs exactly one of its gate and its report, gating unless the answer is report; the scope step runs before every step that reads its outputs; the offline copy scan gates whatever the scope
• the scope step's own shell and the CLI it calls are run for real: a generator change gates and a refresh reports, also when the CLI is reached through a symlink
• the walk over the real generators finds each parser behind its generator, never counts a generated file as an input, and counts a JSON import as a leaf input

The full gate passed before the push: check, unit suite, mock suite, build, bundle gate.

It reaches every stacked PR through the sync that follows.

Note: these reviews ran on the general model because the dedicated reviewer was unavailable: review:rules#2, review:correctness#2, verify#2.1, review:rules#3, review:correctness#3, verify#3.1.

---

Generated by Claude Code

[viztor]

Restacked onto main 1.8.0. This branch now carries main 1.8.0, merged in once here (this PR is the parent of the stack; every PR above merges this one). Pushed head: 7cd12d3b7caab0c5379a4c30a4bdddc1396c98bd.

Conflicts and how they were resolved

Rules and docs

• AGENTS.md: main's go-limits bullet (one lookup, allowance row label); main's login bullet plus the branch's credentialOrg remnant sentence; the branch's remote-timing line (now also naming main's opencodeGoUsage lookup message) and its web-client line kept.
• README.md / README.zh-CN.md: Go model lists and the no-SDK count from main, re-derived from main's shim (Zen 80 = 23/31/17/8/1, Go 30 = 19/5/5/1); count paragraph dated 2026-10-31; install floor ^1.8.0 in both; the Chinese no-SDK row corrected to 23.
• docs/protocol-routing-and-merge.md: "of 80", 23 completions.
• docs/redirect-planes.md: 80 served / 130 listed and 30 / 37 (listed counts are main's, from the live registry); 23 no-SDK; Go non-completions 11 = 30 − 19, re-checked.

Build and dependencies

• package.json: main's ultracite and vite-plus entries plus the branch's yaml.
• pnpm-lock.yaml: main's lockfile, then a fresh install; the only delta from main is es-module-lexer and yaml; frozen install passes.
• scripts/check-vendor-version.ts: main's pure-half structure with the branch's generated-table skip, --copies and error line; a follow-up moved the skip into scripts/vendor-version.ts.
• scripts/check.ts: both 128 → 132 KB paragraphs kept; a follow-up raised the ceiling to 136 KB after measuring the merged client (135,604 B).

Source

• src/fetch-patch.ts: the body read once from a Request (branch) and the plane from the URL (main).
• src/stream-hook.ts: comment only, main's wording made model-free.
• src/catalog-data.ts, src/go-limits-data.ts: reset to main's generated blobs exactly.

Tests

• test/catalog.test.ts: Zen length 80.
• test/e2e/protocol-routing.e2e.ts: main's verdict.ts and usableAsSubject taken, the local verdicts deleted; the free-tier walk asks "busy" before the refusals and skips when every candidate was busy; follow-ups restored the subject picker's narrowing and ported 400 "Model is unavailable" into verdict.ts.
• test/settings-page.test.tsx: the fixed remote count dropped (main's readAccount adds a descriptor).
• test/usage-panel.test.tsx: main's two tests supersede the branch's.

Follow-up commits

15e6236 plane-lookup installs its world before each test · 2454609 the generated-table skip lives in the CLI-version rules, with cases · beae0ca upstream 400 "Model is unavailable" read as a retirement · 1d4aaab testing guide describes the suite this branch keeps · 4b0ebea subject picker keeps the free-tier narrowing · 28fee8d plan restacked (D14', D22', D17 defaults, D23/D24/D25, F10 gone, P-R3 after P-T3) · 8b9da84 client ceiling 136 KB.

Dropped, because main already does it

• the branch's three catalog/limits refreshes (main chore(catalog): regenerate for the Argon rename and the Go plan's new allowances #132 is newer);
• the per-plane pricing hunk in stream-hook.ts (main fix: the plane decides the price, the flag and the refusal #133; recorded as D24);
• the branch's local e2e verdicts, superseded by test/e2e/verdict.ts (only the 400 shape ported);
• the branch's usage-panel "unknown allowances" test;
• the settings-page remote-count assertion.

Review rounds

Round	Found	Upheld	Fixed
1	12	11	all 11 (stale comments and figures, README pair drift, PR body, plan's pi claims, docs dates, repo map, testing guide)
2	6	6	all 6 (deep-dive Muse Spark line, plan's fixed-defects table and D19, Chinese merge rule, CONTRIBUTING contradictions, unpinned test count; the PR body in this update)
3	9	7	all 7: five in the tree (engineering-notes ids, meter mock-ups now pinned by a test against the generated allowances, deep-dive figure, docs index), two in this PR body (phase count 21)

Live re-measures still owed (CI)

• Catalog freshness job: confirm main's 2026-10-31 catalog and allowance blobs are current; on drift, the nightly refresh regenerates them and the counts (80 Zen / 23 no-SDK / 30 Go) are re-derived from the new shim.
• The registry-listed counts in docs/redirect-planes.md (130 Zen / 37 Go) can only be confirmed by the live job.
• Live protocol-routing: confirm the free-tier and subject-picking cases still find a subject with the new busy-skip and the 400 retirement.

Reviews on the general model because the dedicated reviewer was unavailable: none.

---

Generated by Claude Code

[viztor]

catalog freshness is red on 7cd12d3. The vendor added a Zen model, pulse-alpha-free (80 → 81), after main's 2026-10-31 regeneration. This pull request changes the catalog generator's code, so under the D23 scoping it gates on that drift rather than only reporting it.

Nothing in the branch is wrong: it carries main's generated files exactly. The fix is the regenerated src/catalog-data.ts. It cannot be produced from the machine doing this restack, because the vendor registry is unreachable from there, and no regenerated file exists yet to port. The nightly refresh job on main (04:37 UTC) will regenerate it. I will port that file into this branch the same way as the earlier refreshes: the file taken unchanged, the counts that restate it re-derived, and the change merged up the stack.

---

Generated by Claude Code