@sagmans/dsh-tui 0.7.0 → 0.9.0

package/.agents/skills/dsh-tui-dogfood/SKILL.md

@@ -22,7 +22,11 @@ directory or branch tail. A path selects that checkout directly. The helper read
 runs `pnpm run build` only when the checkout declares a build script. It adds
 the bundle once if absent from the cloned profile, updates only its dependency,
 restores local links from `link:` specifications, and launches
-`dsh --profile tui` by default. The legacy
+`dsh --profile tui` by default. For this TUI, the packaged helper checks
+the launcher against compatible releases in the checkout’s `package.json` before
+cloning. This checkout uses installed `dsh 0.1.5-rc.3` for PTY tests. Never
+substitute `pnpm dsh` or a `--dsh` path from a Harness source checkout: that
+host may migrate the cloned `settings.yaml`. The legacy
 `scripts/dogfood/run-tui-from-worktree.sh` remains available in dsh-tui and
 defaults to that script's checkout even when called elsewhere.
 

package/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh

@@ -3,6 +3,7 @@
 set -euo pipefail
 
 name="$(basename "${BASH_SOURCE[0]}")"
+TUI_PACKAGE_NAME='@sagmans/dsh-tui'
 # The link policy is shared with the validator, so both read one rule set.
 helper_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 default_repo="${DSH_DOGFOOD_DEFAULT_REPO:-$PWD}"
@@ -268,11 +269,26 @@ if [[ "$dry_run" == 1 ]]; then
 fi
 
 [[ -n "$dsh_bin" ]] || die "no dsh launcher found; put dsh on PATH or pass --dsh"
+# This plugin's daily host must not be replaced by a source checkout during setup or launch.
+if [[ "$package_name" == "$TUI_PACKAGE_NAME" ]]; then
+  # Keep launcher startup writes out of both the live home and the clone.
+  version_probe_home="$(mktemp -d /tmp/dsh-dogfood-version.XXXXXXXX)" || die "cannot create isolated version probe home"
+  trap 'rm -rf -- "$version_probe_home"' EXIT
+  trap 'exit 1' INT TERM
+  reported_version="$(HOME="$version_probe_home" DSH_HOME="$version_probe_home" "$dsh_bin" --version 2>/dev/null)" || die "TUI dogfood requires compatible installed dsh"
+  rm -rf -- "$version_probe_home"
+  trap - EXIT INT TERM
+  node -e "const p=require(process.argv[1]);process.exit(p.dsh?.compatibility?.dshReleases?.[process.argv[2]] === 'compatible' ? 0 : 1)" "$target_path/package.json" "$reported_version" || die "TUI dogfood requires compatible installed dsh (got ${reported_version:-<empty>})"
+fi
 
 # --- seed the scratch home ---------------------------------------------------
 
 if [[ -d "$home" && "$action" != "clean" && "$dry_run" != 1 ]]; then
   validate_marker
+  # A marker that still reads 0 belongs to a run the kernel killed before it could
+  # clean up: the identity matches, so --reseed takes it, but nothing may reuse a
+  # home whose copy stopped halfway. A marker without the line predates this.
+  [[ "$reseed" == 1 ]] || [[ "$(marker_value ready)" != 0 ]] || die "$home is a half-seeded clone; pass --reseed to clone it again"
   check_credentials
   chmod 700 "$home"
   if [[ -f "$home/.credentials.yaml" ]]; then chmod 600 "$home/.credentials.yaml"; fi
@@ -293,6 +309,11 @@ if [[ ! -d "$home" ]]; then
   step "seeding $home from $source_home"
   mkdir -p "$home"
   chmod 700 "$home"
+  # Written before the copy, so whatever the copy does this directory is one that
+  # --clean and --reseed already own: an interrupted clone is recoverable rather
+  # than a husk neither action will touch. The copy marks it ready when it lands.
+  printf 'home=%s\nsource=%s\ntarget=%s\nprofile=%s\nready=0\n' "$home" "$source_home" "$target_path" "$profile" > "$marker"
+  chmod 600 "$marker"
   if [[ "$fresh" == 1 ]]; then
     for seed in .credentials.yaml settings.yaml; do
       if [[ -f "$source_home/$seed" ]]; then cp -p "$source_home/$seed" "$home/$seed"; fi
@@ -316,8 +337,6 @@ if [[ ! -d "$home" ]]; then
   fi
 fi
 
-printf 'home=%s\nsource=%s\ntarget=%s\nprofile=%s\n' "$home" "$source_home" "$target_path" "$profile" > "$marker"
-chmod 600 "$marker"
 materialize_cloned_links
 check_clone_links
 
@@ -398,6 +417,11 @@ if ! node -e "process.exit(require(process.argv[1]).dsh.profile.bundles.includes
   die "profile '$profile' does not list $package_name after relink (bundles: $bundles)"
 fi
 
+# The home is finished: it points at the target and its bundles answer, so it is
+# ready to be reused rather than re-seeded.
+printf 'home=%s\nsource=%s\ntarget=%s\nprofile=%s\nready=1\n' "$home" "$source_home" "$target_path" "$profile" > "$marker"
+chmod 600 "$marker"
+
 printf '\n' >&2
 printf 'home:    %s\n' "$home" >&2
 printf 'target:  %s\n' "$target_path" >&2

package/.agents/skills/dsh-tui-update-models/SKILL.md

@@ -13,10 +13,11 @@ the ctx gauge. Find the owner first; then edit exactly one place.
 | Where the wiring is | What it owns |
 | --- | --- |
 | `~/.dsh/profiles/<profile>/cordis.patch.yml` | The patch layer: applied after every bundle layer, last entry wins. Holds the catalog or `llm-pi-ai` config a developer actually edits. |
-| `~/.dsh/settings.yaml` | Host settings. Plugin sections keyed by plugin id; used when a host writes config through the settings service instead of a patch. |
+| `~/.dsh/settings.yaml` | Host settings, hot-reloaded. A `llm-pi-ai:` or `llm-deepseek:` section overrides that adapter's patch entry without a restart - it is what the web Models page writes, and what an additive sign-in declares a route in. The legacy `dsh-provider-extra:` section carries `extraModels` and `codexExtraModels` only. **A catalog is never settings-owned**: managed mode installs no section, reads no overlay, and turns off settings projection for its own Config, so the profile patch is the only place a catalog exists. |
 | `~/.dsh/profiles/<profile>/package.json` | Bundles and their dependency specs (`link:` for a checkout, a range for a release). |
 | `node_modules/<bundle>/cordis.patch.yml` | The bundle's own defaults: disabled base rows, inserted rows, default config. |
-| `node_modules/@earendil-works/pi-ai/dist/providers/data/<source>.json` | Installed per-provider catalog: ids, and the cost/context/effort data a template clone inherits. |
+| `node_modules/@earendil-works/pi-ai/dist/providers/data/<source>.json` | Installed per-provider catalog: ids, and the cost/context/effort data a template clone or a `filter` match inherits. |
+| `node_modules/@sagmans/dsh-provider-extra/docs/catalog.md` | The catalog's own field list and rejection rules, matching the plugin build the profile resolves. Read it before inventing a field. |
 
 Entry shapes in the patch layer:
 
@@ -39,8 +40,13 @@ A config in a patch **replaces** the base config; it never merges field by field
 | One new id that behaves like a catalog sibling | `extraModels: [{ id, template, name? }]` (clone the sibling's wire behavior) |
 | Serve only some of a route's catalog | a `models:` whitelist of ids, in the order the picker should show |
 | Own the whole model directory (gateways, subscriptions, logins) | `dsh-provider-extra` `catalog` v1, and disable the base rows |
+| Serve most of an installed source, minus a few ids | catalog route `filter: { include?, exclude? }` - keeps every installed fact |
+| Point a route at your own endpoint | catalog route with `api` + `baseURL` and no `source` |
 | Retire a model or a provider | drop it from the list, or disable the row that offers it |
 
+A catalog route declares **exactly one** of `models` and `filter`; `models: []`
+is the explicit empty selection, and `filter` needs an installed `source`.
+
 `dsh-provider-extra` catalog skeleton, with the two override layers a correct
 entry needs as soon as a vendor number differs from the inherited one:
 
@@ -54,20 +60,61 @@ entry needs as soon as a vendor number differs from the inherited one:
         - id: openai
           name: OpenAI API
           source: openai              # pi-ai provider id; its data is the base
-          auth: { apiKeyRef: OPENAI_API_KEY }
+          auth: { apiKeyRef: OPENAI_API_KEY }   # omit auth for a keyless local route
           models:
             - id: gpt-6-sol
               name: GPT-6 Sol
+              aliases: [gpt-6-sol-preview]  # extra selector inputs, never extra rows
               template: gpt-5.6-sol   # inherits wire behavior AND stale metadata
+              defaultMaxTokens: 128000  # request cap, only when the request gives none
               metadata:               # override what the vendor documented
                 contextWindow: 1050000
                 cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 }
+        - id: local-llm
+          name: Local llama.cpp
+          api: openai-completions     # own endpoint: api is required, source is absent
+          baseURL: http://127.0.0.1:8080/v1
+          models:
+            - id: qwen3-coder
+              name: Qwen3 Coder
+              metadata:             # no installed sibling: every fact is declared
+                reasoning: true
+                input: [text]
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+                contextWindow: 262144
+                maxTokens: 65536
+        - id: zai-all
+          name: Z.AI Coding Plan
+          source: zai
+          auth: { apiKeyRef: ZAI_API_KEY }
+          filter: { include: ['glm-*'], exclude: ['glm-4*'] }   # '*' is the only wildcard
 ```
 
-Rules the resolver enforces: `version` is exactly `1`; duplicate provider ids
-are refused; an empty catalog requires `default: null`; `default` must resolve to
-a declared provider/model; a `reasoningEffort` the model does not support fails
-composition.
+Rules the resolver enforces, each rejecting the **whole** candidate: `version` is
+exactly `1`; an unknown field anywhere; duplicate provider ids, model ids, or
+aliases; a `source` no installed pi-ai provider ships; `api` beside `source`, or
+absent when `source` is absent; `baseURL` absent, non-HTTP(S), or carrying
+credentials; a `transport` on a route whose source is not `openai-codex`; a
+`fallbackSessionId` on a route whose source is not `opencode-go`; `auth` naming
+both modes, or `apiKeyRef` on `openai-codex`, or a `credentialProvider` that is
+not the `source`; both or neither of `models`/`filter`; an unknown `template`; a
+model with no resolvable template and incomplete `metadata`; a
+`defaultMaxTokens` above the model's `maxTokens`; a `metadata.api` that changes a
+template-backed protocol; an empty catalog whose `default` is not `null`; a
+`default` outside the served selection; a `reasoningEffort` the model does not
+support. Omitting `catalog` is not `providers: []`: the first keeps the plugin's
+legacy additive routes, the second serves nothing.
+
+Ownership is exclusive and checked at boot. Disable **every** competing row in
+the whole profile - on `dsh-base` those are `llm-pi-ai`, `llm-deepseek`, and
+`agent-default-model` - and mount provider-extra after them. A surviving adapter,
+provider directory, or default owner logs `CATALOG_OWNER_COLLISION` and fails
+listing, selection, dispatch, and sign-in closed until it is gone.
+
+The pinned host reads only `provider` and `model` from `catalog.default`: it
+ignores `reasoningEffort`, so effort is chosen in the session surface. Saving a
+default needs the host's `configEditor`; a host without one rejects with
+`CONFIG_PERSISTENCE_UNAVAILABLE`, and the profile patch stays the place to edit.
 
 ## 3. Reasoning efforts
 
@@ -86,21 +133,47 @@ concept differently - map it, never rename the vendor value.
 
 ## 4. Costs
 
-Per 1M tokens: `{ input, output, cacheRead, cacheWrite }`. `0` is right for a plan
-that bills credits, wrong for a per-token route. A vendor that charges more above
-an input threshold needs the tier row, otherwise long prompts are understated.
+Per 1M tokens: `{ input, output, cacheRead, cacheWrite }`, plus optional
+`tiers: [{ inputTokensAbove, input, output, cacheRead, cacheWrite }]`. `0` means
+unknown pricing on a credit plan, not free inference. A vendor that charges more
+above an input threshold needs its tier row, otherwise long prompts are
+understated. `metadata.maxTokens` is model capacity and never a request cap;
+`defaultMaxTokens` is the request default and must not exceed that capacity.
 
 ## 5. Verify before and after the edit
 
 ```sh
-dsh --profile tui list-models                          # every reachable route, id<TAB>name
-~/.agents/skills/dsh-tui-update-models/scripts/dump-model-catalog.mjs   # resolved cost/ctx/efforts
+dsh --profile tui list-models        # every reachable route, id<TAB>name
+# resolved cost/ctx/efforts, naming the layer each number came from:
+~/.agents/skills/dsh-tui-update-models/scripts/dump-model-catalog.mjs \
+  [--home "$DSH_HOME"] [--profile tui] [--data <pi-ai data dir>] [--json]
+```
+
+The dump marks each value `installed`, `template:<id>`, `route`, or `metadata`, so
+an inherited number is visible instead of trusted, expands a `filter` route
+against the installed data the same way the resolver does, and exits 1 on the
+declarations the resolver refuses - incomplete metadata, a request default above
+capacity, both membership styles, a default the served selection does not
+contain.
+
+Then check the vendor's own page for price, context window, max output, and
+accepted effort values - the installed catalog lags vendors, and a template
+clone carries a sibling's numbers.
+
+To prove a catalog on a disposable home instead of the live one, provider-extra
+ships a clone-only setup that composes the candidate and disables the competing
+rows for you:
+
+```sh
+cd <dsh-provider-extra checkout> && pnpm catalog:setup \
+  --helper ~/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh \
+  --source-home ~/.dsh --home /tmp/dsh-catalog-check --profile tui \
+  --catalog /tmp/catalog-config.json [--allow-row ROW_ID] [--dsh /abs/path/to/dsh/lib/bin.js]
 ```
 
-The dump marks each value `installed`, `template:<id>`, or `metadata`, so an
-inherited number is visible instead of trusted. Then check the vendor's own page
-for price, context window, max output, and accepted effort values - the installed
-catalog lags vendors, and a template clone carries a sibling's numbers.
+`--catalog` is a private JSON file holding only `{"catalog": {...}}`. Success
+means `composition-verified`, not authenticated runtime; launch only the clone
+command it prints.
 
 ## 6. Pitfalls
 
@@ -110,8 +183,13 @@ catalog lags vendors, and a template clone carries a sibling's numbers.
 | A window that is really a pricing threshold | vendors publish e.g. "above 272K input priced 2x" beside the real window |
 | `off` missing on a reasoning model | `thinkingLevelMap.off` is `null` or absent where the vendor takes `none` |
 | A stealth model with no vendor page | its numbers exist only in the routing catalog (pi.dev model page, models.dev) |
-| Config ignored after an edit | a linked bundle loads `lib/`; run `pnpm run build` in that checkout |
+| Config ignored after an edit | a linked bundle loads `lib/` or `dist/`; run the build in that checkout |
 | ctx gauge and auto-compact trigger early/late | the declared `contextWindow` is wrong, not the gauge |
+| Same model id, two context windows | each route inherits its own source's numbers; declare `metadata` on both |
+| Everything fails closed, logs `CATALOG_OWNER_COLLISION` | a competing adapter, provider directory, or default owner row survived |
+| A new field looks accepted but does nothing | the resolver rejects unknown fields; a stale plugin build silently predates it |
+| `/model` saves a default that reverts | the host has no `configEditor`: `CONFIG_PERSISTENCE_UNAVAILABLE`; edit the patch |
+| Route serves nothing after a `filter` edit | patterns match installed ids only, and `exclude` wins over `include` |
 
 Never put a key in a profile or a patch: name it (`apiKeyEnv`, `apiKeyRef`,
 `credentialProvider`) and keep the value in the environment or `$DSH_HOME/.env`.

package/.agents/skills/dsh-tui-update-models/references/model-wiring.md

@@ -12,6 +12,12 @@ Companion to [SKILL.md](../SKILL.md): exact fields, files, and checks.
 4. The model directory a profile sees is owned by whichever row is enabled:
    `llm-pi-ai` (additive provider config), `dsh-provider-extra` (owned catalog),
    or both, if the profile is not using exclusive ownership.
+5. `$DSH_HOME/settings.yaml` sits over the adapter rows, not over a catalog. A
+   `llm-pi-ai:` or `llm-deepseek:` section reshapes that adapter per request; a
+   `dsh-provider-extra:` section reshapes only the legacy routes'
+   `extraModels`/`codexExtraModels`, and only where no `models`/`codexModels`
+   selection is declared. A managed catalog reads no settings overlay at all, so
+   a catalog edit lands in the profile patch or nowhere.
 
 Exclusive ownership is a set of disable rows plus the catalog itself:
 
@@ -23,6 +29,19 @@ Exclusive ownership is a set of disable rows plus the catalog itself:
   config: { catalog: { version: 1, ... } }
 ```
 
+Disable every competing row in the **whole** profile, not only the rows that come
+before provider-extra: on `dsh-base` those are `llm-pi-ai`, `llm-deepseek`, and
+`agent-default-model`, and another bundle may add `llm-openai` or
+`llm-anthropic`. Inspect the composed profile rather than trusting this list.
+Preflight refuses to register managed routes when an adapter, a provider
+directory, or a default owner already exists; a later registration is caught by
+the host's `llm/adapters-updated` notification. Either way the plugin logs
+`CATALOG_OWNER_COLLISION` once per transition and fails closed: listing,
+selection resolution, request preparation, default reads and saves, new
+dispatch, and starting a sign-in all refuse while the conflict exists. Requests
+already past their credential gates finish. Removing the competing rows restores
+service without a reload of the catalog itself.
+
 ## `llm-pi-ai` provider config
 
 ```yaml
@@ -52,57 +71,131 @@ Exclusive ownership is a set of disable rows plus the catalog itself:
 An id that the installed catalog already describes needs no restatement. An id it
 does not describe needs the metadata (or a `template` sibling to clone).
 
+Route fields (`providers` is a dict keyed by the route id; the key is the route):
+`apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `modelOverrides` (per-id
+reshaping of an installed catalog, refused beside a `models` list), `compat`,
+`defaultContextWindow` (262144), `defaultMaxTokens` (32768), `defaultInput`
+(`[text]`), `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`,
+`transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`,
+`maxRequestImageBytes`, `requestImagePixelBudget`, `requestImageMaxBytes`,
+`retryPolicy`. A route key that names an installed pi-ai provider inherits that
+provider's endpoint, protocol, display name, and catalog; any other key is a
+complete hand declaration and must name `api` and `baseURL`.
+
+`reasoningEfforts` is this adapter's spelling of `thinkingLevelMap`: a dict of
+selectable level to the wire value dispatch sends, `false` for a non-reasoning
+model, and only `off` may carry an empty or null value. An empty dict, a level
+mapping to an empty string, or a dict offering nothing beyond `off` is refused.
+
 ## `dsh-provider-extra`
 
-Two config generations exist; a profile normally uses one:
+Two config generations exist; a profile normally uses one, and presence of
+`catalog` is what opts a profile into managed ownership:
 
 | Config | Use |
 | --- | --- |
-| Additive: `routeId`, `displayName`, `apiKeyEnv`, `fallbackSessionId`, `extraModels`, `models`, `codexExtraModels`, `codexModels`, `codexTransport` | add a gateway or subscription route beside whatever else the profile serves |
-| `catalog` v1 | own the entire directory: ids, aliases, metadata, and the default selection |
+| Additive: `apiKeyEnv`, `routeId`, `displayName`, `baseURL`, `headers`, `fallbackSessionId`, `models`, `extraModels`, `codexEnabled`, `codexRouteId`, `codexDisplayName`, `codexModels`, `codexExtraModels`, `codexTransport`, `loginCommandEnabled`, `loginCommandName` | add a gateway or subscription route beside whatever else the profile serves |
+| `catalog` v1 | own the entire directory: routes, ids, aliases, metadata, and the default selection |
 
-Catalog fields:
+The generations differ where a declaration cannot resolve. An additive
+`extraModels` entry with a bad `template` lands in that route's model
+diagnostics while the route keeps serving; an additive `models`/`codexModels`
+whitelist naming an id nothing provides refuses the whole route. A **catalog**
+rejects the whole candidate instead: there is no per-model diagnostic path.
+
+Catalog route fields (an unknown field rejects the candidate):
 
 ```yaml
 catalog:
   version: 1                      # exactly 1
-  default:                        # null only when the catalog is empty
+  default:                        # null only when nothing is served
     { provider: opencode-go-session, model: deepseek-flash, reasoningEffort: max }
   providers:
     - id: opencode-go-session     # the id every selection and alias check uses
       name: OpenCode Go (session)
-      source: opencode-go         # pi-ai provider id: its installed data is the base
-      baseURL: https://api.x.ai/v1            # optional
-      transport: sse                          # optional
-      fallbackSessionId: dsh-provider-extra   # optional
-      auth: { apiKeyRef: OPENCODE_GO_API_KEY }        # or { credentialProvider: openai-codex }
+      source: opencode-go         # installed pi-ai provider id; its data is the base
+      api: openai-completions     # own endpoint only: required without source, refused beside it
+      baseURL: https://api.x.ai/v1            # required without source; http(s), no user/pass/fragment
+      headers: { X-Route: tenant-a }          # static headers; secrets stay in a credential reference
+      transport: sse                          # openai-codex only: sse|websocket|websocket-cached|auto
+      fallbackSessionId: dsh-provider-extra   # opencode-go only: session header for sessionless calls
+      auth: { apiKeyRef: OPENCODE_GO_API_KEY }        # or { credentialProvider: openai-codex }; absent = keyless route
       models:
         - id: deepseek-flash
           name: DeepSeek V4.1 Flash
-          aliases: [deepseek-v4.1-flash]      # extra ids that resolve to this model
-          template: deepseek-v4-flash         # clone wire behavior when the source lacks the id
-          defaultMaxTokens: 384000            # request ceiling; metadata.maxTokens overrides
+          aliases: [deepseek-v4.1-flash]      # extra selector inputs, unique in the route, never extra rows
+          template: deepseek-v4-flash         # installed sibling of the SAME source to clone
+          defaultMaxTokens: 384000            # request default; must be <= resolved maxTokens
           metadata:
             api: openai-completions
             reasoning: true
             input: [text, image]
             cost: { input: 0.22, output: 0.66, cacheRead: 0.007, cacheWrite: 0 }
+            # a threshold-priced vendor adds its tier rows beside those four rates:
+            # cost: { input: 0.22, output: 0.66, cacheRead: 0.007, cacheWrite: 0,
+            #         tiers: [{ inputTokensAbove: 272000, input: 0.44, output: 1.32,
+            #                   cacheRead: 0.014, cacheWrite: 0 }] }
             contextWindow: 1000000
-            maxTokens: 384000
+            maxTokens: 384000                 # capacity, never a request cap
             thinkingLevelMap: { off: null, minimal: null, low: low, medium: null, high: high, xhigh: null, max: max }
+            headers: { X-Model: flash }
             compat: { supportsStore: false, supportsDeveloperRole: false, supportsReasoningEffort: true, supportsStrictMode: true, thinkingFormat: qwen }
+    - id: zai-catalog
+      name: Z.AI Coding Plan
+      source: zai
+      auth: { apiKeyRef: ZAI_API_KEY }
+      filter: { include: ['glm-*'], exclude: ['glm-4*'] }   # instead of models; '*' is the only wildcard
 ```
 
+`filter` needs an installed `source`: an absent `include` starts from every
+installed model, matches keep installed order and every installed fact (id, name,
+cost, capacity, protocol, endpoint), and the route serves them minus `exclude`.
+A matched model that publishes no endpoint needs a route `baseURL`.
+
+A model with no resolvable template must declare all of `api` (unless the route
+declares `api`), `reasoning`, `input`, `cost`, `contextWindow`, and
+`maxTokens`. `metadata.api` cannot change a template-backed protocol, must equal
+a route's declared `api`, and must be an api the `source` describes.
+
+`compat` accepts only the flags the model's protocol honors: completions takes the
+`supports*`/`requires*` booleans plus `maxTokensField`, `thinkingFormat`,
+`thinkingTokenBudgetField`, `cacheControlFormat`, `deferredToolsMode`, and
+`sessionAffinityFormat`; responses takes its own flag set plus
+`sessionAffinityFormat`; anthropic-messages takes its flag set and no enums.
+Template-language and gateway-routing keys (`chatTemplateKwargs`,
+`chatTemplateArgs`, `openRouterRouting`, `vercelGatewayRouting`,
+`vllmPriority`, `allowedFallbackModels`) are refused. The plugin's own
+`src/catalog-routes.ts` lists the accepted names per protocol.
+
 Behaviour:
 
 | Case | Result |
 | --- | --- |
 | `template` names a sibling the source ships | clone its wire behavior and metadata |
-| `template` names nothing | that model lands in the route's diagnostics; the rest of the route still serves |
-| a `models` whitelist names an id nothing provides | the whole route is refused - a typo there is a broken deployment |
-| two providers share an id | composition error |
-| `default` names a model outside the catalog | composition error |
-| `reasoningEffort` unsupported by the model | composition error |
+| `template` names nothing, or the route has no source | candidate rejected: `unknown template <id>` |
+| unknown id, no template, incomplete metadata | candidate rejected: `unknown model requires complete metadata: missing <field>` |
+| both `models` and `filter`, or neither | candidate rejected: `declare exactly one of models or filter` |
+| duplicate provider id, model id, or alias | candidate rejected |
+| `defaultMaxTokens` above the resolved `maxTokens` | candidate rejected: `exceeds model maxTokens` |
+| `default` names a model outside the served selection | candidate rejected; an alias is canonicalized to its wire id |
+| `reasoningEffort` unsupported by the model | candidate rejected |
+| nothing served (empty providers, or `models: []`) | `default` must be `null`; `currentSelection()` throws `NO_DEFAULT_MODEL` |
+
+### Default persistence
+
+`catalog.default` reaches a new session as provider and model only: the pinned
+host ignores its `reasoningEffort`, so effort is chosen in the surface.
+`saveSelection(next)` validates first, then writes through the host's
+`configEditor.edit(entry, updater)` so only `catalog.default` changes and
+membership is re-checked inside the editor's lock. A host with no addressable
+entry or no such editor rejects with `CONFIG_PERSISTENCE_UNAVAILABLE` - the
+released `0.1.5-rc.2` host does - and nothing falls back to legacy
+`agent-default-model` settings. Edit the profile patch there.
+
+`compileCatalog(config)` and `buildCatalogProfile(provider)` are public: the
+first returns a detached frozen snapshot or `undefined` for absence, the second
+validates one route declaration on its own. Both are what the dump script and a
+candidate check should read against.
 
 ## Where the base data comes from
 
@@ -113,8 +206,10 @@ PI_AI="${DSH%/lib/bin.js}/node_modules/@earendil-works/pi-ai"
 ls "$PI_AI/dist/providers/data"      # one JSON per provider source, keyed by api
 ```
 
-A JSON entry is the whole truth for a `source`: `id`, `name`, `cost`,
-`contextWindow`, `maxTokens`, `input`, `reasoning`, `thinkingLevelMap`, `compat`.
+`source` must be an id the installed pi-ai build ships (`builtinProviders()`);
+`ls` the data directory for the list this harness answers. A JSON entry is the
+whole truth for a `source`: `id`, `name`, `cost`, `contextWindow`,
+`maxTokens`, `input`, `reasoning`, `thinkingLevelMap`, `compat`, `baseUrl`.
 A model declared without `template` and without `metadata` is served exactly as
 this file describes it, so an id the vendor renamed or repriced shows stale
 numbers until the catalog declares them. An entry that carries its own complete
@@ -125,9 +220,10 @@ not describe is wired.
 
 | Field | Meaning |
 | --- | --- |
-| `apiKeyEnv` | read the key from this environment variable |
-| `apiKeyRef` | read it from the profiles' stored credentials under this reference |
-| `credentialProvider` | use a login flow's stored credentials (codex subscriptions) |
+| `apiKeyEnv` | additive config and `llm-pi-ai`: read the key from this environment variable |
+| `apiKeyRef` | catalog: a host credential reference; without a credential service the route reads that environment variable. Refused on an `openai-codex` source, which needs OAuth |
+| `credentialProvider` | catalog: use a login flow's stored grant. Needs an installed `source` and must equal that source id |
+| no `auth` | catalog: the route carries no key of its own, as a local endpoint does |
 
 Keys never belong in a patch, a settings file, or a repository. Put launch-time
 values in `$DSH_HOME/.env` or the environment. A provider row whose credential is
@@ -137,9 +233,39 @@ missing fails its route only; other routes still serve.
 
 ```sh
 dsh --profile tui list-models        # provider/model<TAB>display name, one per reachable route
-~/.agents/skills/dsh-tui-update-models/scripts/dump-model-catalog.mjs --home "$DSH_HOME"
+~/.agents/skills/dsh-tui-update-models/scripts/dump-model-catalog.mjs \
+  [--home "$DSH_HOME"] [--profile tui] [--data <pi-ai data dir>] [--json]
+```
+
+The dump reads the catalog row written as a single JSON flow map
+(`- {"id":"dsh-provider-extra","config":{"catalog":…}}`), which is the shape
+`pnpm catalog:setup` appends and the shape a hand-written patch keeps when one
+line must stay machine-readable. A catalog spread over block YAML is invisible to
+it; `list-models` still reads the composed result either way. `--data` points the
+dump at a provider-data directory instead of the installed harness, which is how
+a template clone or a `filter` route is read on a machine with no `dsh`. The dump
+also reports what the resolver would refuse, and exits 1, because a catalog that
+cannot compose serves nothing: incomplete metadata for an unknown model, a
+`defaultMaxTokens` above capacity, both or neither of `models`/`filter`, a
+default the served selection does not contain, an effort the selected model does
+not offer, and a default that is null while models are served.
+
+To validate a candidate on a disposable home, provider-extra's clone-only setup
+composes it and disables the competing rows itself:
+
+```sh
+cd <dsh-provider-extra checkout> && pnpm catalog:setup \
+  --helper <plugin checkout>/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh \
+  --source-home ~/.dsh --home /tmp/dsh-catalog-check --profile tui \
+  --catalog /tmp/catalog-config.json [--allow-row ROW_ID] [--dsh /abs/path/to/dsh/lib/bin.js]
 ```
 
+`--catalog` is a private JSON file holding only `{"catalog": {...}}`. It prints
+`composition-verified` on success, which is composition only: not runtime
+ownership, not authentication. `--allow-row` asserts a provider-looking row
+registers no provider and no default owner, because setup cannot see row
+provenance and refuses rather than guesses.
+
 `list-models` exits zero only after printing a line, so a deployment that
 advertises nothing cannot pass for one that was enumerated.
 
@@ -150,9 +276,13 @@ For every model you touched, confirm against the vendor's own page:
    is priced 2x" is a billing threshold, not the window);
 3. the accepted reasoning effort values, and how the vendor spells "no reasoning"
    (OpenAI: `none`; codex: omit the parameter);
-4. whether the route bills per token at all - a credit or token plan wants cost
-   `0`, a metered API wants its published rates;
-5. that an `xhigh` or `max` mapping exists when the vendor documents one.
+4. whether the route bills per token at all - a metered API wants its published
+   rates, and a credit or token plan writes `0`, which reads as unknown pricing
+   rather than free inference;
+5. that an `xhigh` or `max` mapping exists when the vendor documents one;
+6. that the same model id served on two routes carries the same facts: each route
+   inherits its own `source` entry, so one declared `contextWindow` and one
+   inherited is two different ctx gauges for one model.
 
 A model with no vendor page (stealth releases, previews) is documented only by the
 routing catalog: its pi.dev model page and `models.dev/api.json`.