Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
docs(meta-muse-code): record the Muse Code wire and Keychain login
Jack Rudenkodfd0c9661e82
diff --git a/CLAUDE.md b/CLAUDE.mdindex 23d92215..64d98377 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -18,6 +18,11 @@ lives in `ROADMAP.md`.- `behavior-layer.md` — Layer 4, the harness-conformance supervisor- `advisor.md` — `--advisor` for any main model: independent of `--monitor`, decorator on the routed handler, ids by tool name, retained session state, stub paths S1-S10, Claude Code's gates, metered panel billing; read before editing advisor, decorator, monitor-launch or native-auth code- `providers/devin.md`, `providers/grok-subscription.md`, `providers/antigravity.md`, `providers/qwen-alibaba.md` — one per reverse-engineered provider+- `providers/meta-muse-code.md`: `muse@` on a Muse Code subscription and its metered sibling `meta@`: the mint+ as entitlement evidence (per process, on 401, 30-min TTL), the Muse Keychain item read only by an+ `interactive-launch` or TUI role and never killed, the borrowed 0600 copy team/MCP slots sign with,+ the contributor guard and its removal trigger (backend M3). Read before editing `meta-muse/`,+ `prompt-role.ts` or `content-use.ts`- `headless-vs-interactive.md` — `-p` is not interactive-minus-a-TTY; an UNKNOWN `--agent` name issilently unvalidated under `--input-format stream-json` (a VALID one is applied correctly); why magmux,and the one `-p` the MCP server does start (`run_prompt` on a Claude model)diff --git a/ai-docs/architecture/README.md b/ai-docs/architecture/README.mdindex 06e8d1db..2890ed25 100644--- a/ai-docs/architecture/README.md+++ b/ai-docs/architecture/README.md@@ -22,6 +22,7 @@ three earlier write-ups this material cites were lost.| [`providers/grok-subscription.md`](providers/grok-subscription.md) | `gk@` on a SuperGrok / X Premium+ plan: RFC 8628 device flow, exact-scope matching, 6-hour token refresh with write-back, three mandatory client headers | touch `gk@`, `claudish login grok`, or its OAuth refresh || [`providers/antigravity.md`](providers/antigravity.md) | Gemini on an Antigravity subscription: the shared `agy` keychain token, runtime client-secret extraction, live discovery of the account's dynamic models catalog | touch `ag@`, `auth/antigravity-*`, or the keychain token || [`providers/qwen-alibaba.md`](providers/qwen-alibaba.md) | One service, two consoles, three isolated key+host products and account-discovery caveats | touch `qcode@`/`qtoken@`/`qpay@`, or assume anything about Alibaba's credentials |+| [`providers/meta-muse-code.md`](providers/meta-muse-code.md) | `muse@` on a Muse Code subscription: the Responses wire and the ignored `response.subscription_usage` event, the Muse CLI's Keychain item and the borrowed 0600 copy, the per-process prompt role, the never-killed `security` read and its per-machine lock, the mint as entitlement evidence with per-process, 401 and 30-minute rotation, the unused `/v1/messages` and `/v1/chat/completions`, the contributor guard and its removal trigger, backend M1 to M6 | touch `providers/meta-muse/`, `transport/meta-muse-code.ts`, `muse-code-credential.ts`, `prompt-role.ts`, `content-use.ts`, `claudish login muse`, or the metered `meta@` || [`custom-endpoints.md`](custom-endpoints.md) | User-defined `customEndpoints`: schema, `${VAR}` expansion, and `authScheme: "none"` for endpoints that take NO credential | change `customEndpoints`, `config-schema.ts`, or `authScheme` handling || [`predefined-endpoints.md`](predefined-endpoints.md) | The 25-vendor bundled catalog: credential-gated activation, the single registration seam, evidence tiers (all `probe`, none `live`), and the no-model-data rule | add a vendor to `providers/predefined-catalog.ts`, or change endpoint registration || [`onepassword.md`](onepassword.md) | SDK-only secret resolution, the FOUR causes of an identical denial error, the cross-process handshake lock, parent-side route pinning, and the config TUI tab | touch `providers/onepassword*.ts`, credential pre-hydration, or the 1Password TUI tab |diff --git a/ai-docs/architecture/adapters.md b/ai-docs/architecture/adapters.mdindex eeedecba..21b55db6 100644--- a/ai-docs/architecture/adapters.md+++ b/ai-docs/architecture/adapters.md@@ -436,6 +436,62 @@ The exclusion rested on "a 503 cannot silently switch the user off a pinned mode(found by the 10.3.0 release review, source-traced; the status alone could not tell aconnection fault from an overload).+### A subscription's credential failure stops the chain (2026-10-16)++The `upstream_status` recovery above made a remapped 401/403 advance the chain, on the reasoning+that a revoked key on one provider is exactly when the next should be tried. For a SUBSCRIPTION+that reasoning bills money: a user whose Kimi Code, Grok Build or Zen Go login had expired was+walked onto the next hop, usually metered, and never told to log in. Jack's decision: a terminal+credential failure of any subscription provider stops with its message, and a transient fault+never becomes a 401. This narrows the "strictly additive" property for exactly that case.++**The verdict rides a header, `x-claudish-auth-verdict`** (`terminal` or `transient`), from+`handlers/shared/auth-failure.ts`. The status cannot carry it: a terminal failure is answered 400+so Claude Code shows it inline, and a 400 with `upstream_status: 401` is precisely what the+recovery above reads as retryable. `isRetryableError` checks the verdict right after the+connection verdict, BEFORE the quota wording and the `upstream_status` recovery. It cannot be+forged for the same reason `x-claudish-recovery` cannot: every non-ok `ComposedHandler` exit is a+`c.json(...)`.++One classifier, `classifyAuthFailure(err)`, reads only fields a credential path sets on purpose,+in one order:++| Kind | Read from | Answer (`respondAuthFailure`) |+|---|---|---|+| connection | `classifyConnectionError` | none; the caller runs connection recovery first |+| terminal | `err.terminal === true` | 400 `invalid_request_error`, verdict `terminal`, `upstream_status` kept |+| transient | `upstreamStatus` 429 or 5xx, or `transient: true` | 429 for a 429, otherwise 503, verdict `transient` |+| unknown, subscription | anything else | as terminal |+| unknown, metered | anything else | 401 at `refreshAuth` and `forceRefreshAuth` only; other sites rethrow |++`unknown` on a subscription is terminal, not transient (a deviation from the architecture's 503).+Connection faults are classified first and real transients carry a status, so what is left is+overwhelmingly a credential fault: Kimi's "No Kimi OAuth credentials found. Please run `claudish+login kimi` first." is a plain `Error`. Answered 503 it would hide behind about two minutes of+Claude Code's silent retries.++All five auth sites in `composed-handler.ts` (`refreshAuth`, `getHeaders`, the primary fetch, the+parameter-recovery re-fetch, `forceRefreshAuth`) use it, and so does a `recoverConnection` that+throws a non-connection error (`c6a7b4a5`). `settleAuthRetry` answers a 401/403 after a refresh as+terminal when the provider is a subscription or `classifyTerminalError` says so, and leaves every+other status alone, so Antigravity's terminal 429 is unchanged.++**Not every 401/403 is a credential verdict** (`isCredentialRejection`, `a5a29f36`). The first+cut read the status alone and stopped three answers that must keep advancing:++| Body | Measured | Why it advances |+|---|---|---|+| Zen Go `401 "Model deepseek-v4-pro-0813 is not supported"` | 2026-08-18, same key serving `kimi-k3` with 200 | the model, not the credential (`hasModelUnsupportedWording`) |+| Kimi Code `403 "You've reached your usage limit for this billing cycle"` | `quota-exhaustion.ts` | a spent allowance, which advances with its per-token warning |+| Zen Go `403 {"error":{"type":"RegionError",…}}` | 2026-08-19 | the provider's own error type names a region |++`FallbackHandler`'s subscription rule, the generic remap's verdict header and `settleAuthRetry` all+ask the same predicate. A spent allowance still advances because the quota wording is checked+before the subscription 401 rule. An `"Invalid API key."` 401 or 403 is still a rejection.++`FallbackCandidate.provider` now carries the claudish provider uid. `isRetryableError` used to+receive the candidate's DISPLAY name, and `isSubscriptionProvider("Kimi Coding")` is false.+## The catalog's endpoint contract has two halves (v9.0.7)> **Superseded (10.5.0).** The gate, the name rule and the model-level `tokenParam` readdiff --git a/ai-docs/architecture/providers/meta-muse-code.md b/ai-docs/architecture/providers/meta-muse-code.mdnew file mode 100644index 00000000..cb81afe5--- /dev/null+++ b/ai-docs/architecture/providers/meta-muse-code.md@@ -0,0 +1,397 @@+> `muse@` on a Muse Code subscription: a minted `LLM|` key, the Muse CLI's Keychain login, and why the mint is the entitlement evidence.+>+> Added in the Muse Code work (2026-10-16, on v10.6.1). Indexed in [`README.md`](../README.md).++# Muse Code (`muse@`): Meta models on your Muse Code subscription++The claudish provider `meta-muse-code` (provider shortcut `muse@`, tier `subscription`) signs+requests with a Muse Code login. Its metered sibling is `meta` (`meta@`, tier `native`), signed by+`META_API_KEY` on route `meta/direct-api`. They are two credential silos on one host:++| | `meta` (`meta@`) | `meta-muse-code` (`muse@`) |+|---|---|---|+| Credential | `META_API_KEY` | a Meta `dca:` access token, minted into a short-lived `LLM\|` key |+| `apiKeyEnvVar` | `META_API_KEY` | `""` (load-bearing, see below) |+| Request | catalog connection on `meta/direct-api` | `POST https://api.meta.ai/v1/responses`, `stream: true`, `store: false` |+| Route binding | `meta/direct-api` | none yet (backend M1 to M3) |+| Billing | per token, from the connection's `pricing` | `SUBSCRIPTION_PROVIDERS`: `$0`, `SUB` |+| Models | catalog connections | the account's dynamic models catalog, `GET /muse-code/models` |++The `meta` provider shortcut belonged to `ollamacloud` until `ca4be53b`. It moved with no alias+(CLAUDE.md: a rename removes the old name).++**claudish has no runtime dependency on the `muse` binary.** It reads one Keychain item the Muse+CLI writes and calls the same two Meta endpoints the CLI calls. Nothing is executed, parsed out of+the binary at runtime, or version-gated. That matters because muse auto-updates: it went from+1.4.8 to 1.4.9 in the middle of the capture session.++## The wire, as captured++The Muse CLI 1.4.8 was run through a logging reverse proxy (`muse exec --base-url`), and on+2026-10-16 through a user-approved mitmdump for the two calls that bypass `--base-url`. Every+secret was redacted at write time.++```+POST https://api.meta.ai/v1/responses+authorization: Bearer LLM|<17 digits>|<27 chars> # 49 chars, opaque, not a JWT+content-type: application/json+{"model":"muse-wonder-full-1.0","instructions":"…","input":[…],+ "max_output_tokens":128000,"store":false,"tools":[…],+ "reasoning":{"effort":"high","summary":"auto"},+ "include":["reasoning.encrypted_content"],"stream":true}+```++- The bearer alone is enough. Probes with only `authorization` and `content-type` answered 200,+ without `user-agent`, `x-client-id` or the `x-tbh-*` session headers. claudish sends none of+ those.+- `MuseCodeTransport.transformPayload` (`providers/transport/meta-muse-code.ts`) reproduces the+ three fields the CLI sends that the Responses adapter does not: `store: false`,+ `reasoning.encrypted_content` in `include`, and `reasoning.summary: "auto"` when reasoning is+ sent. With `store: false` the encrypted reasoning items replay statelessly on the next turn.+- Effort values come from the model's `variants` keys in `/muse-code/models`. On the wire,+ `minimal`, `xhigh` and `max` answer 200; `none` and `ultra` answer 400. The CLI's own `ultra`+ never reaches the wire as `ultra`.+- A bad bearer answers+ `401 {"error":{"code":"invalid_api_key","message":"Unauthorized","type":"authentication_error"}}`,+ with no `www-authenticate`.++### `response.subscription_usage`++The Responses and chat-completions streams carry one Meta event after `response.completed`:++```json+{"type":"response.subscription_usage","subscription":{"tier":"27681631238169137",+ "weekly":{"resets_at":1792368000,"used_percent":0},+ "window":{"resets_at":1792088451,"used_percent":2,"window_duration_mins":300}}}+```++`openai-responses-sse.ts` has no branch for it, so the parser drops it and Claude Code never sees+it. A quota display that reads it (architecture phase 18) is not built. `used_percent` is an+integer, too coarse to attribute one small request.++### Endpoints claudish does not use, and why++The subscription bearer also gets 200 from `POST /v1/chat/completions` and `POST /v1/messages`+(full Anthropic SSE with `redacted_thinking` and `tool_use`). claudish uses neither:++- Whether either one bills the subscription or the metered API was not measured.+ `used_percent` cannot show one request.+- `/v1/messages` emits no `subscription_usage` event, so it carries no evidence of subscription+ accounting at all.+- The CLI itself sends only `/v1/responses`.++So `transportFor` builds `MuseCodeTransport` only for `api === "responses"`, and try-in-turn for+`meta-muse-code` is restricted to `responses` (`wire-handler.ts`). Opening another API needs a+billing measurement first, not a code change.++### Contributor mode++`muse exec --contributor-mode on` changes exactly two things: header `x-tbh-contributor-mode: 1`+and the model id `<id>-contributor`. The catalog describes those ids as "Your content, including+inter-session messages, may be used for product improvement." claudish never sends the header.+It sends a contributor id only when the user typed it (see the contributor guard below).++## The Keychain item++```+keychain: login.keychain-db class: genp+service (svce): ai.meta.dev.credentials account (acct): meta+value: {"secret_schema_version":1, "api_key":"LLM|…"(49), "access_token":"dca:…"(282)}+```++The binary's strings name a wider serde struct (`access_token, obtained_via, refresh_token,+expires_at, api_key, api_base_url, user_full_name, user_email, user_avatar_url, subs_active,+secret_schema_version`). The item observed on 2026-10-16 held only the three fields above: no+`refresh_token`, no `expires_at`.++- **claudish reads `access_token` only** (`parseMuseKeychainValue`, `muse-keychain.ts`). The+ `dca:` token is the durable credential.+- **`api_key` is never used.** It is the CLI's current minted key, and it rotates under the CLI.+ On a synthetic 401 the CLI re-minted and rewrote the item: its `mdat` moved from+ `20261015131850Z` to `20261016023620Z` at the instant of the retry.+- **claudish never writes the item.** `claudish logout muse` does not touch it.++### Presence is free; a value read is a dialog++`find-generic-password` without `-w` returns attributes only, with no dialog. The `-w` read of an+item another application created opens the macOS access dialog the first time, and a person may+take minutes to answer it. So presence and value are separate calls (`keychain.md`): presence is+async and memoized for 3 s, never on a render path. The value read is the only thing gated.++### Never kill `security`++A killed `security` mid-transaction is how this codebase once made macOS restart `securityd`+(`keychain.md`). `startGenericPasswordRead` (`providers/keychain.ts`, `a0fad487`) therefore+returns `{ done, pid }` and has no kill path:++1. `done` resolves only when `security` itself exits, and never rejects.+2. Each caller races `done` against its own deadline: 120 s (`MUSE_KEYCHAIN_READ_DEADLINE_MS`).+3. A caller whose deadline wins stops waiting. `security` keeps running.+4. A late approval resolves `done`. The answer is kept in-process (`lateResult`) for the next+ caller, which takes it without a second dialog.++Locked-keychain and Deny exit codes are NOT measured. Both open a desktop dialog, and no kill is+allowed to end one, so they need an interactive run.++### One read per machine: `~/.claudish/muse-keychain-read.lock`++Joining `done` works inside one process. Across processes, a fan-out of CLI `--team` grid panes+or two launches in two terminals, a lock file does the same job:++- The holder creates it with `wx` (exclusive), then rewrites it with the `security` CHILD's pid+ while the dialog is up. A holder that gives up and exits leaves a lock that stays live exactly as+ long as the dialog does.+- A process that finds a live lock does not spawn. It polls every 500 ms until the lock clears,+ then reads the borrowed copy the holder wrote. If no copy appeared, it reads for itself, when its+ role allows.+- A lock is stale when its pid is dead, when it is older than 30 minutes (pids are reused), or+ when it is unreadable for more than 5 s.++## The prompt role: which process may open the dialog++`credentialPromptRole()` (`auth/credentials/prompt-role.ts`, `da9c2c17`) is fixed once per process+by its entry point. The default is `never`. After the first set, the role can only be lowered to+`never`. A request can read the role and can never raise it.++| Entry point | Role | Muse Keychain value reads |+|---|---|---|+| `index.ts` `runCli`, stdin AND stderr are TTYs, not a pane child, no `--probe` | `interactive-launch` | the startup hook and the request path |+| `index.ts` in a pane child (`CLAUDISH_PANE_CHILD`), piped, or CI | `never` | none |+| `--probe` (`cli.ts`) | `never` | none |+| MCP server (`mcp-server.ts`): `team`, `create_session`, `preflight` | `never` | none |+| `claudish serve` | `never` | none |+| config TUI (`tui/index.tsx`) | `tui` | only inside `withInteractiveCredential(action)`, in-process, before the action sends a proxy request |++**`isPaneChild()`, never `isatty`.** A magmux pane has a real PTY, so an MCP `team` slot passes+every TTY test. `pane-launch.ts` sets `CLAUDISH_PANE_CHILD` for every MCP `team` slot and+`create_session` pane. CLI `--team` grid panes do NOT carry it, because the user who ran `--team`+is at that terminal. They take `interactive-launch`, and the lock bounds them to one dialog.++**A `never` process asks the Keychain nothing**, not even the attribute-only presence question.+A locked login keychain can answer any `security` call with an unlock dialog, and the process+could not use the item anyway. So in a `never` process a Keychain-only login reads as absent+(`MuseCodeCredentialProvider.describeReadiness`), and the error says how to fix it:++```+muse@ in a team slot / MCP session needs a claudish login: run `claudish login muse`, or one+interactive `claudish --model muse@<model>` and allow Keychain access.+```++## Sources, and the borrowed 0600 copy++`ensureMuseCredentialReady` (`providers/meta-muse/muse-credentials.ts`) tries three sources in order:++1. `~/.claudish/meta-muse-oauth.json`: claudish's own login (`claudish login muse`).+2. `~/.claudish/meta-muse-borrowed.json`: claudish's copy of the Muse CLI's `dca:` token.+3. The Keychain item, only when the caller may prompt AND the role is not `never`.++The borrowed copy is what lets a `team` slot, an MCP session or a piped launch use the Muse CLI's+login without a dialog of its own:++```json+{ "schema": 1, "access_token": "dca:…", "copied_at": "2026-10-16T02:36:20.000Z",+ "subs_tier_name": "Muse Code Power Usage" }+```++- It is written only after a Keychain read AND a mint that confirmed the subscription, by a+ process whose role allows the read.+- Both files are mode 0600 (the directory is created 0700 when missing), written by temp file+ plus `rename`, and valid only when they parse with a non-empty string `access_token`+ (`isValidMuseStore`, the one predicate every reader uses).+- An env handoff was rejected. A minted key in the environment cannot be re-minted by the child,+ and it would reach the child's Claude Code, whose Bash tool can print it.+- The Muse CLI's own logout revokes the `dca:` token remotely. After that, the mint answers 401 and+ the copy is useless. `claudish logout muse` deletes both files (`deleteMuseStores`).++### claudish's own login: `claudish login muse`++`MuseCodeOAuth` (`auth/meta-muse-oauth.ts`, `ad1cb22f`) runs Meta's RFC 8628 device flow, so a+user needs neither the Muse CLI nor a Keychain approval:++```+POST https://auth.meta.com/oidc/device/authorization/ (form) client_id=1031625952748946+→ {device_code, user_code, verification_uri, verification_uri_complete, expires_in: 600, interval: 5}+POST https://auth.meta.com/oidc/device/token/ (form)+ grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=…&client_id=1031625952748946+→ 400 authorization_pending | 400 slow_down | 200 {access_token, …}+```++- No scope parameter. `slow_down` adds 5 s to the interval for the rest of the wait (RFC 8628+ §3.5).+- The 200 body was never captured: the captured `muse login` was stopped before approval, so+ the Muse CLI's own login stayed intact. Only+ `access_token` is required; `refresh_token` and `expires_in` are kept if present and never read.+- The token is minted once BEFORE it is stored. An unsubscribed account is NOT stored: an own+ login is tried first, and a stored unconfirmed one would block a working borrowed copy on every+ request. A transient mint failure stores the login with a warning.+- Logout deletes both files and revokes nothing remotely. The shape of `muse-code/logout` was+ never captured.++## The mint is the entitlement evidence++```+POST https://api.meta.ai/muse-code/key+authorization: Bearer dca:… # 282 chars+x-api-version: 1.0.0+content-type: application/json+{"onboard":false}+→ 200 {"api_key":"LLM|…","base_url":"https://api.meta.ai/v1",+ "is_subs_active":true,"require_payment":false,"action_url":null,+ "subs_tier_id":"27681631238169137","subs_tier_name":"Muse Code Power Usage",+ "subs_usage":{…}, …}+```++The CLI calls this at start and again on a 401 from `/v1/responses`. That remint goes straight to+`api.meta.ai:443`, bypasses `--base-url`, and never contacts `auth.meta.com`. So the device-code+server is not part of renewal: the `dca:` token mints new keys until the mint itself answers 401.++**A mint is confirmed only when `is_subs_active === true` AND `require_payment === false`**, both+present as booleans (`interpretMint`, `muse-mint.ts`). Missing, `"true"` or `null` is unconfirmed.+An unconfirmed mint throws `MuseSubscriptionRequiredError`, a terminal error that links+`action_url`, or `https://accountscenter.meta.com/muse_code/?ep=no_payg` when the response names+none. It deliberately carries no login hint, because logging in again changes nothing.++This is the reason a mint happens before any signing. `meta-muse-code` is in+`SUBSCRIPTION_PROVIDERS`, so every request it signs reads `SUB` and accrues `$0`. A key minted for+an account with no active subscription would otherwise be labelled flat-rate while Meta charged or+refused it.++| Mint answer | Thrown | `classifyAuthFailure` |+|---|---|---|+| 401, 403 | `MuseLoginExpiredError` | terminal |+| 200, unconfirmed | `MuseSubscriptionRequiredError` | terminal |+| 429, 5xx | `MuseMintTransientError` | transient |+| network fault, 15 s timeout | `Error` with `cause` and `claudishEndpoint` | connection |+| 200 with no `api_key`, other status | `MuseMintProtocolError` | terminal |++claudish sends `User-Agent: claudish/<version>`, not the CLI's `muse-build/0.1.0`. Whether the+endpoint checks it was not measured, because no live mint was run during implementation.++### Rotation: per process, on 401, and on a 30-minute TTL++The minted key lives only in the memory of the process that minted it (`MuseState`), never on+disk, so every process mints its own. Three events renew it:++- **Process start.** The first request mints. For an interactive launch, the startup hook mints+ before Claude Code starts (below).+- **A 30-minute entitlement TTL** (`MUSE_ENTITLEMENT_TTL_MS`). This is a rule, not a vendor value.+ It bounds a lapsed subscription in `claudish serve` or a long session to 30 minutes of `SUB`+ labelling. A TTL re-mint first re-confirms the token already in use, so a working source is not+ abandoned for an earlier one.+- **A 401 from `/v1/responses`.** See the algorithm below.++Every source switch is logged with the tier name (`[MuseCode] signing source …`), so a silent+account switch between the own login and a borrowed one shows up in the debug log. Whether a+claudish mint invalidates the CLI's current key is not measured. The CLI re-mints on its own 401,+so either answer is survivable.++### The 401 algorithm++`MuseCodeTransport.forceRefreshAuth` receives the headers of the rejected request (the+`forceRefreshAuth?(ctx?: { rejectedHeaders })` parameter added in `c6a7b4a5`) and calls+`forceRefreshMuseApiKey({ rejectedKey })`:++1. Add the rejected key to the process's dead-key set.+2. If the key in use is a different key that is not dead, return it. The 401 was stale: a+ concurrent request already replaced that key.+3. Otherwise mark the current key dead and resolve again, single-flight: re-mint from the token in+ use; on a mint 401/403, try the next source.+4. If no source works, throw a terminal `MuseCredentialError`:+ `Meta rejected a freshly minted Muse Code key (HTTP 401): run claudish login muse (or muse login).`++A mint that confirms a key removes it from the dead-key set, because the service can hand back the+key it rejected a moment earlier, and a dead mark left on it would re-mint on every request.++A source whose mint answers 401/403 falls to the next source. A network or transient mint failure+is rethrown unchanged. It never falls to another source and never falls back to an unconfirmed key.++## The startup hook++`prepareMuseLoginForLaunch` (`providers/meta-muse/muse-launch.ts`) runs in `index.ts` after+`warmCatalogIfNeeded`, in every launch role, and is skipped under `--monitor`. It exists for two+reasons:++- `claude-runner` reads the served context window from discovery before it spawns Claude Code, and+ discovery needs a signed key. In a `never` role that key comes from the two files.+- In an interactive launch, the Keychain dialog belongs in front of the user who typed the command,+ not inside Claude Code's first turn.++An explicit `muse@` slot whose login is terminally unusable exits 1 before spawn, and the message+names its fix. A bare-name slot that gathers `meta-muse-code` only warns, because its routing chain+continues. A network or transient fault warns and continues.++## Classification at the auth sites++The terminal/transient contract every subscription now follows is in [`adapters.md`](../adapters.md)+("A subscription's credential failure stops the chain"). For `muse@` the consequence is direct: an+expired Muse login answers 400 with the login hint, and the chain never walks onto metered `meta@`.++`probe-live.ts` lists `meta-muse-code` in `OAUTH_PROVIDERS`. A login-fixable failure gets the+`claudish login muse` hint. An unsubscribed account gets `subscribe at <url>` instead.++## Models and effort++- **Discovery.** `GET /muse-code/models` (`muse-models.ts`, format `muse-code-models`) returns+ OpenAI-style rows with `metadata["muse-code"]`: modalities, `limit.context` / `limit.output`,+ effort `variants`, `is_hidden`. Hidden rows (`muse-image-1.0`) are not offered. `GET /v1/models`+ lists ids only, with `created: 0`, so it is not used.+- **Context window.** The transport reads the served window (1,007,997 on the captured account)+ from the dynamic models catalog, memoized, with a 5-minute backoff after a miss. The+ `direct-api` catalog records publish 1,048,576. Both numbers belong to different routes.+- **Effort borrow** (`muse-wire.ts`, `281caf0a`). With no route binding, no connection describes+ the `muse@` request shape. `ownerWireForModel` borrows the KNOWN `responses` wire of the same wire+ id on `meta/direct-api`, after a 5 s registry wait, with its speed and mode forced to `unknown`+ because those carry entitlement and price (`wire.md`).+- **The `muse-wonder-full-1.0` gap.** `meta/direct-api` does not publish that id, so it gets no+ borrowed wire, and its effort is whatever the Responses adapter sends. The `direct-api`+ contributor rows publish no reasoning support either, so an explicit contributor id gets only the+ token limit. Both gaps close when backend M3 to M5 publish subscription connections.++## The contributor guard, and when to remove it++Jack's decision (2026-10-16): **a contributor wire id is never chosen implicitly, on any route.** A+user who types `provider@<id>-contributor` gets it verbatim.++`isOptInWireId` (`providers/content-use.ts`, `d9193383`) matches `-contributor` and+`-contributor-free` on the last path segment. Where catalog data enters memory, the matching+connections move from `aggregators[]` to `optInConnections[]`, which only exact-id readers+(`allConnections`) consult. [`routing.md`](../routing.md) lists the entry points and readers.++**Remove the guard when models-index publishes a content-use field on every route (backend M3).**+It is the one wire-id name rule claudish keeps. The trigger is that field, not Meta: OpenCode Zen's+`-contributor-free` ids are covered by the same regex.++## Backend tasks (models-index)++Filed in `ai-docs/reports/BACKEND_TASKS_meta_muse_code_route-20261016.md`, read against generation+`g-20261015133900604-fb6199b5`:++| Task | What | Unblocks |+|---|---|---|+| M1 | a subscription route profile on route `meta`, `apis: [responses]`, its own credential profile | the binding row (architecture phase 17) |+| M2 | plan `meta-muse-code` to `supported` with that route | membership gating |+| M3 | one mapped connection per member, wire id as `/muse-code/models` spells it; contributor ids marked by a field, not only the suffix | bare-name routing to `muse@`; removing the contributor guard |+| M4 | a model record `muse-wonder-full`, wire id `muse-wonder-full-1.0` | bare `muse-wonder-full` |+| M5 | per-connection limits and effort from `/muse-code/models` | the effort and window gaps above |+| M6 | per-tier membership: Wonder Full is Power and Maximum only | no 4xx candidate on a lower tier |++Until M1 to M3 land, a bare `muse-*` name never reaches `muse@`. `meta-muse-code` is tier+`subscription`, not `dynamic-subscription`, so it makes no namespace claim; with no mapped+connection the gatherer has nothing to offer. A bare `muse-spark-1.3` goes to `meta@` (with+`META_API_KEY`), then OpenCode Zen, then OpenRouter.++## Captures++Raw captures are in the GITIGNORED session directory+`ai-docs/sessions/dev-feature-muse-code-20261016-010810-37623ac2/research/`. They do not survive a+fresh clone. The facts above are the durable record.++| File | What |+|---|---|+| `muse-wire.md` | the full reverse-engineering notes, §1 to §8 |+| `capture.log` | a PONG run through the base-url proxy |+| `cap2/` | a one-tool-call run (the Responses round trip) |+| `cap3/` | a contributor-mode run |+| `cap4/capture.log`, `cap4/connect.log` | the synthetic-401 run and the CONNECT host log that placed the remint on `api.meta.ai` |+| `cap5-mitm.log` | the decrypted mint |+| `cap6-login.log` | the device login, stopped before approval |diff --git a/ai-docs/architecture/routing.md b/ai-docs/architecture/routing.mdindex 7700a3f6..b28aa654 100644--- a/ai-docs/architecture/routing.md+++ b/ai-docs/architecture/routing.md@@ -41,6 +41,8 @@ claudish --model ollama@<model>:3 "task" # 3 concurrent requests- `dv@`, `devin@` → Devin (Cognition/Codeium subscription — see `ai-docs/architecture/providers/devin.md`)- `gk@` → Grok Build subscription (SuperGrok / X Premium+ — see `ai-docs/architecture/providers/grok-subscription.md`). `grok@` stays with the METERED `x-ai` provider- `x-ai@`, `xai@`, `grok@` → xAI direct API, metered (`XAI_API_KEY`)+- `muse@` → Muse Code subscription (`meta-muse-code`: `claudish login muse`, or the Muse CLI's Keychain login; see `ai-docs/architecture/providers/meta-muse-code.md`). No route binding yet, so only an explicit `muse@<wire id>` reaches it+- `meta@` → Meta Model API, metered (`meta`, `META_API_KEY`, route `meta/direct-api`). Until `ca4be53b` `meta` was an `ollamacloud` shortcut; it moved with no alias, so an old `meta@llama-…` spec now goes to Meta- `llama@`, `oc@` → OllamaCloud- `litellm@`, `ll@` → LiteLLM (requires LITELLM_BASE_URL)- `ollama@` → Ollama (local)@@ -318,6 +320,44 @@ It runs in two places:The catalog itself is extracted, published and documented in the[models-index](https://github.com/MadAppGang/models-index) repo; claudish only reads it.+## Contributor wire ids are never chosen implicitly (2026-10-16)++Some vendors publish a second wire id for one model whose use opts the request's CONTENT into+the vendor's product improvement: `muse-spark-1.3-contributor` beside `muse-spark-1.3` on+`meta/direct-api`, and `…-contributor-free` beside the plain id on OpenCode Zen. The catalog maps+both as ordinary connections. On generation `g-20261015133900604-fb6199b5` OpenCode Go mapped+ONLY the contributor id for `muse-spark-1.3`, so a bare `muse-spark-1.3` went to Go first, opted+in, with nothing on screen to say so.++Jack's decision: a contributor id is never chosen for the user, on any route. One typed exactly+(`[email protected]`) is sent verbatim.++`isOptInWireId` (`providers/content-use.ts`) matches `-contributor` and `-contributor-free` on the+last path segment. It is enforced where catalog data enters memory, not at each reader, so a+reader added later inherits it:++| Entry point | What it does |+|---|---|+| `readAllModelsCache`, the refreshed `_memCache`, `_setCatalogEntriesForTest` | `splitOptInConnections`: matching rows move from `aggregators[]` to `optInConnections[]` |+| `fetchCatalogPage` (Firebase `ModelDoc`s) | `normaliseCatalogPayload`, the same split |+| `getProbeModel`, `rankProbeCandidates`, `expandSelection` | skip an opt-in id |+| `discoverProviderModelsCatalog` | offered rows exclude opt-in ids; `discoverProviderServedIds` returns both lists for entitlement |++The rows are moved, never deleted. Only EXACT-id readers consult `allConnections()`:+`resolveExternalId`'s first step (`publishesWireIdFor`), `findConnection`'s exact step, the+availability reverse lookup, `allExternalIds`, and `wiresMatchRegistry`, which still validates+every row. A reader that CHOOSES a wire id reads `aggregators[]` and cannot see an opt-in one.++A provider whose only connection for a model is a contributor one is not gathered. `--probe`+shows it as `excluded-by-content-use`. A provider that maps both ids keeps its plain candidate+and shows no drop. Measured on the pinned generation `g-20261016053727894-8a743761` (1189+models): three chains changed, and each lost only `zengo@<id>-contributor` (`gemini-4-argon`,+`muse-spark-1.3`, `muse-spark-1.2`).++**Removal trigger:** models-index publishes a content-use field on every route (backend task M3,+`ai-docs/reports/BACKEND_TASKS_meta_muse_code_route-20261016.md`). Until then this is the one+wire-id name rule claudish keeps.+## Route bindings: which claudish provider a catalog route meansA connection names a route binding `(routeId, routeProfileId)`, never a claudish provider.@@ -355,6 +395,20 @@ Plan absence has two different meanings:public backend cannot know, so absence remains unknown and the candidate is retained. Devin,Antigravity, and the `xai-supergrok` plan use this account-scoped behavior.+Membership gates GATHERED candidates too (`66d10dae`). Before, `gatherFromConnections` kept any+mapped connection of a `subscription`-tier provider, so a plan whose membership did not include+the model still became a hop. Now `resolveSubscriptionRouting(...) === "not-served"` sends the+candidate to `excluded-by-membership`. On the pinned generation `g-20261016053727894-8a743761`,+seven chains lost only their subscription hop (`zengo@` for `qwen3.7-max`, `glm-5.1`,+`qwen3.6-plus`, `minimax-m2.5`, `omen-alpha`; `qtoken@` for `deepseek-v3.2`,+`deepseek-v4-flash`).++**A subscription's terminal credential failure stops the chain.** An expired or revoked login on+any `SUBSCRIPTION_PROVIDERS` member (and `openai-codex` when its OAuth arm signed) answers 400+with its login hint and never walks onto the next, usually metered, hop. A model the plan does not+carry and a spent allowance still advance. The mechanism is in `adapters.md` ("A subscription's+credential failure stops the chain").+The backend recommendation projection supplies canonical model IDs and exactroute/profile identities. Claudish resolves them against the generation-pinnedcatalog for model wire IDs. A user routing rule decides preference when one