Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs(architecture): record unknown shortcuts and the test preload

Jack Rudenko988475a34ea1
diff --git a/ai-docs/architecture/routing.md b/ai-docs/architecture/routing.md
index a8755573..2a3f33ff 100644
--- a/ai-docs/architecture/routing.md
+++ b/ai-docs/architecture/routing.md
@@ -48,6 +48,7 @@ claudish --model ollama@<model>:3 "task" # 3 concurrent requests
- `ollama@` → Ollama (local)
- `lmstudio@` → LM Studio (local)
- Custom endpoint names also work as provider prefixes (e.g., `my-vllm@model-name`) — see `ai-docs/architecture/custom-endpoints.md`
+- **An unknown shortcut is named as unknown** (`providers/unknown-shortcut.ts`). `parseModelSpec` passes an unknown shortcut through as the provider name, so `[email protected]` (`go@` was removed in v7.36.0) used to reach the credential filter and answer `No credentials configured for "go"` (D9). `explainExplicitSpec` now asks `isKnownProviderName` FIRST, before any credential read (no authority lookup, readiness probe or 1Password attempt for a name that cannot exist), and answers no-route with cause `explicit-unknown-shortcut` and candidate outcome `unknown-provider`. Known means a builtin or runtime-registered provider, a bundled endpoint (even with no key, so `groq@` keeps its credential message), a `customEndpoints` key, or `custom-url`. The one wording, printed by routing, the proxy's step 6b, preflight and `--probe`: `Unknown provider shortcut "go" in "[email protected]".` plus `Providers that serve gemini-3.8-flash: ag@… (Antigravity, subscription · account decides models) · g@… (Gemini, native API) · … Every shortcut: claudish --help.` The suggestions are the providers `gatherRouteCandidates` returns for the model (catalog connections and namespace claims, chain order, no credential filter, no cap), spelled with `getShortestPrefix`; a model that gathers nothing lists the shortcuts one edit from the typed one. No model list is written anywhere, and a removed shortcut gets no alias. Whoever adds a credential read to `explainExplicitSpec` keeps it BELOW this check
- **Bundled catalog vendors** each use their own name as their only prefix, and appear only when their key is locally present: `groq@`, `cerebras@`, `together@`, `fireworks@`, `deepinfra@`, `nebius@`, `hyperbolic@`, `sambanova@`, `novita@`, `baseten@`, `perplexity@`, `venice@`, `chutes@`, `featherless@`, `parasail@`, `inference-net@`, `aimlapi@`, `requesty@`, `nanogpt@`, `cohere@`, `scaleway@`, `upstage@`, `writer@`, `moonshot-cn@`, `tuningengines@` — see `ai-docs/architecture/predefined-endpoints.md`. `moonshot-cn@` is the China-region Moonshot product, a DIFFERENT service from the builtin Kimi provider reached by `moonshot@`
## Local models
@@ -236,7 +237,10 @@ process inherits env, not argv. `--default-provider ""` exports an empty value,
the hop. The export runs after `--op-env` and `--op`, which overwrite env unconditionally, so the
flag still beats a value they hydrate. Children see it only because every claudish child is
spawned through `node:child_process`, which inherits `process.env`: `Bun.spawn` without an `env`
-option drops in-process env writes.
+option drops in-process env writes. Measured 2026-10-22, that holds on bun 1.4.0 only: on bun
+1.3.10 (the CI pin) a `node:child_process` child spawned with no `env` option ALSO gets the
+original environment, a deletion or an assignment made in-process undone. A child that must see an
+in-process write needs `env: { ...process.env }` on 1.3.10 (`testing.md`, the spawn rule).
**Who reads it.** `route(model)` with no overrides asks the resolver on every call
(`effectiveDefaultProvider`), and so does `--probe`'s chain, so the two cannot name different
diff --git a/ai-docs/architecture/testing.md b/ai-docs/architecture/testing.md
index b007489f..cc314acd 100644
--- a/ai-docs/architecture/testing.md
+++ b/ai-docs/architecture/testing.md
@@ -211,6 +211,68 @@ drained the event loop and exited 0 before `process.exit(code)`. The shutdown no
holds the loop with an interval until the reap ends. A test of an exit code under
signals needs `--rerun-each`: one run hides a race that loses more often than it wins.
+## A test run never writes into a real session's records (the preload)
+
+A suite run inside a claudish pane (a `create_session` runner, a `team` slot) inherits the pane's
+session variables, and `captureUpstreamError` appended the suite's test doubles (`stub`,
+`fixture-upstream-error`) to `~/.claudish/sessions/<id>/upstream-errors.jsonl`, so that session's
+`get_diagnostics` listed them as upstream failures (`model-failures-2026-10-21.md`, D5).
+
+`scripts/test-preload.ts` deletes `SESSION_ENV_VARS` from `process.env` before the first test file
+loads. The six names live in the import-free `scripts/session-env-vars.ts`, each the literal of the
+production constant whose writer follows it: `CLAUDISH_UPSTREAM_ERROR_LOG`, `CLAUDISH_HOOK_INBOX`,
+`CLAUDISH_HOOK_SESSION`, `CLAUDISH_TOKEN_FILE`, `CLAUDISH_PUBLISHED_TOKEN_FILE`,
+`CLAUDISH_PANE_CHILD`. Neither file imports production code: that would load `hooks/`, `config.ts`
+and the token tracker ahead of the module-scope snapshots tests rely on. A new session-record
+writer means a new name in that list.
+
+**Three bunfig.toml files** register the preload: the repo root, `packages/cli` and
+`packages/macos-bridge`. bun reads `bunfig.toml` from the working directory only and never walks
+up (measured on 1.3.10 and 1.4.0), and the suite runs from all three.
+
+**The trap: a child spawned with no `env` option gets the ORIGINAL environment back.** Measured
+2026-10-22: `Bun.spawn`/`Bun.spawnSync` on 1.3.10 and 1.4.0, and `node:child_process` on 1.3.10 (the
+CI pin; 1.4.0's `child_process` sees the deletion). So the preload covers in-process writers (D5's
+observed records) and children given `env: { ...process.env }`, and two more layers close the rest:
+
+- `scripts/guard-real-config.ts` deletes the same names from the OS environment of a `test:safe`
+ run, so no descendant can inherit them.
+- `scripts/spawn-env.test.ts` fails on any `Bun.spawn`, `Bun.spawnSync` or `node:child_process`
+ spawn/exec/fork in test code (`*.test.ts(x)` and anything under a `test-helpers/` directory)
+ whose options are not an object literal with an `env` key. It parses with the TypeScript
+ compiler API, so a comment cannot satisfy it. A site whose options cannot be read statically goes
+ in its allowlist with the file, the line text and the reason. 42 sites lacked `env` when it
+ landed; each got `env: { ...process.env }`.
+
+Two pane tests "fail inside a pane by design" (`launcher/magmux-wrapper.test.ts`,
+`team-grid.e2e.test.ts`). With `CLAUDISH_PANE_CHILD`, `CLAUDISH_PANE_CWD` and `MAGMUX_SOCK` set,
+magmux-wrapper measured 16 pass / 9 fail both before and after the preload: the 9 come from
+`MAGMUX_SOCK` (the ambient-multiplexer branch), which is not a session-record variable and stays
+inherited. team-grid.e2e was 7 / 0 both times in that simulation.
+
+## Clearing provider keys: derive the list, never hand-write it
+
+`routing-rules.test.ts` cleared a hand list of 24 key names that missed `POE_API_KEY` and every
+bundled vendor's key (D4). `test-helpers/provider-credential-env.ts` derives the list:
+`providerCredentialEnvVars()` is every `apiKeyEnvVar`/`apiKeyAliases` in `BUILTIN_PROVIDERS` and
+`PREDEFINED_ENDPOINTS` (`providerKeyEnvVars()`), the credential names no definition declares
+(taken from the reader's constant where one exists: `DEVIN_API_KEY_ENV`,
+`VERTEX_PROJECT_ENV_VARS`), and every `CUSTOM_<NAME>_KEY` present; `providerBaseUrlEnvVars()` is
+every declared `baseUrlEnvVars`. `clearProviderCredentialEnv()` deletes both and returns the
+restore function. A test that needs "no provider key" uses it, so a new provider cannot reopen the
+hole.
+
+## Credential files: seams and a redirected HOME
+
+`GrokOAuth`, `KimiOAuth` and the Devin reader re-read their credential files when they change
+(`credential-files.md`), so a test that reaches one without its path seam reads, and through a
+refresh may write, the developer's real login. Use `setGrokOAuthPathForTesting`,
+`setKimiOAuthPathForTesting`, `setKimiDeviceIdPathForTesting`, `KimiOAuth._resetForTests()` and
+`setDevinCredentialsPathForTesting`. A test file that imports `auth/credentials/authority.ts` or
+`auth/kimi-oauth.ts` should also run in a child spawned with `HOME` set to a temp directory in the
+child's environment (Bun resolves `homedir()` from the environment a process starts with, never
+from an in-process assignment), so a missed seam lands there.
+
## Pane tests: a real magmux, a fake child, nothing left behind
MCP `team` slots and `create_session` run as interactive Claude Code in headless magmux panes