@sagmans/dsh-tui 0.6.0 → 0.8.0

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

@@ -0,0 +1,292 @@
+# Model wiring reference
+
+Companion to [SKILL.md](../SKILL.md): exact fields, files, and checks.
+
+## Resolution order
+
+1. Bundle layers in `cordis.yml`, in order.
+2. The profile patch `~/.dsh/profiles/<profile>/cordis.patch.yml`, entry by entry:
+   `id` targeted config, `disabled`, `insert`.
+3. A patch `config` **replaces** that row's base config; fields it omits fall back
+   to the schema default, not to the bundle's value.
+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:
+
+```yaml
+- { "id": "agent-default-model", "disabled": true }
+- { "id": "llm-pi-ai", "disabled": true }
+- { "id": "llm-deepseek", "disabled": true }
+- id: dsh-provider-extra
+  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
+- id: llm-pi-ai
+  config:
+    providers:
+      qwen-token-plan:
+        apiKeyEnv: QWEN_TOKEN_PLAN_API_KEY   # env var holding the key
+        baseURL: https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
+        api: openai-completions              # optional wire override
+        models:
+          - id: qwen3.8-max                  # served as-is
+          - id: deepseek-v4.1-flash
+            name: DeepSeek V4.1 Flash
+            contextWindow: 1000000
+            maxTokens: 384000
+            input: [text, image]
+            reasoningEfforts: { low: low, high: high, max: max }
+            compat:
+              supportsStore: false
+              supportsDeveloperRole: false
+              supportsReasoningEffort: true
+              supportsStrictMode: true
+              thinkingFormat: qwen
+```
+
+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, and presence of
+`catalog` is what opts a profile into managed ownership:
+
+| Config | Use |
+| --- | --- |
+| 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 |
+
+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 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         # 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 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                 # 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, 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
+
+```sh
+# the harness install owns the pi-ai catalog the profile resolves against
+DSH=$(readlink -f "$(command -v dsh)")
+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
+```
+
+`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
+`metadata` needs no installed entry at all, which is how a route the harness does
+not describe is wired.
+
+## Credentials
+
+| Field | Meaning |
+| --- | --- |
+| `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
+missing fails its route only; other routes still serve.
+
+## Verify
+
+```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"] [--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.
+
+For every model you touched, confirm against the vendor's own page:
+
+1. price per 1M tokens for input, output, cached input, cache write;
+2. context window and maximum output tokens (a "272K" beside "above 272K input
+   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 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`.
+
+Then run the profile against a cloned home before the real one - see the
+`dsh-tui-dogfood` skill - and `pnpm run build` any linked bundle first: a linked
+profile loads `lib/`, not `src/`.

package/.agents/skills/dsh-tui-update-models/scripts/dump-model-catalog.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * Print the model directory a dsh profile resolves, with the provenance of
+ * every field.
+ *
+ * The surface reads prices, context windows, and reasoning levels from the
+ * composition, not from the vendor's page, so an inherited or stale value is
+ * invisible in the UI. This reads the same two inputs the resolver does - the
+ * owned catalog in the profile patch, and the installed pi-ai provider data -
+ * and names where each number came from: "installed" for the source's own
+ * entry, "template:<id>" for a clone, "route" for the protocol a sourceless
+ * route declares once for every model it serves, "metadata" for what the
+ * catalog declares.
+ *
+ * An entry the catalog spells out completely needs no installed entry at all,
+ * so a missing harness install must not hide it. A `filter` route is the
+ * exception: its membership is the installed catalog's, so it cannot be read
+ * without that install. A declaration the plugin's resolver would refuse is
+ * reported as a refusal here too, because a catalog that cannot compose serves
+ * nothing.
+ *
+ * Usage: dump-model-catalog.mjs [--home <dsh home>] [--profile <name>]
+ *                               [--data <pi-ai data dir>] [--json]
+ *
+ * `--data` names the installed provider-data directory to inherit from, which
+ * is how a reading is checked where no harness is installed - a `filter` route
+ * and every template clone need one.
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+/** Fields a catalog entry may inherit, and the layer each value came from. */
+const INHERITED_FIELDS = ['contextWindow', 'maxTokens', 'cost', 'input', 'reasoning', 'thinkingLevelMap', 'api']
+/** What a model with no installed sibling and no template must state itself. */
+const REQUIRED_METADATA = ['api', 'reasoning', 'input', 'cost', 'contextWindow', 'maxTokens']
+const COST_FIELDS = ['input', 'output', 'cacheRead', 'cacheWrite']
+const INSTALLED = 'installed'
+const METADATA = 'metadata'
+const ROUTE = 'route'
+const ABSENT = 'none'
+/** The only wildcard a `filter` pattern carries; every other character is itself. */
+const WILDCARD = '*'
+
+/** The levels pi-ai offers: a null mapping removes one, and xhigh/max need one. */
+export function supportedLevels(levelMap) {
+  return LEVELS.filter((level) => {
+    const mapped = levelMap?.[level]
+    if (mapped === null) return false
+    if (level === 'xhigh' || level === 'max') return mapped !== undefined
+    return true
+  })
+}
+
+function parseArgs(argv) {
+  const options = { home: process.env.DSH_HOME ?? join(homedir(), '.dsh'), profile: 'tui', data: undefined, json: false }
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index]
+    if (flag === '--json') options.json = true
+    else if (flag === '--home') options.home = argv[++index]
+    else if (flag === '--profile') options.profile = argv[++index]
+    else if (flag === '--data') options.data = argv[++index]
+    else throw new Error('unknown argument ' + flag)
+  }
+  return options
+}
+
+/** The pi-ai data directory of the harness install the launcher belongs to. */
+function dataDirectory() {
+  try {
+    const bin = execFileSync('sh', ['-c', 'command -v dsh'], { encoding: 'utf8' }).trim()
+    const root = join(realpathSync(bin), '..', '..')
+    return join(root, 'node_modules', '@earendil-works', 'pi-ai', 'dist', 'providers', 'data')
+  } catch {
+    // No harness install is a supported reading: declared entries still resolve.
+    return undefined
+  }
+}
+
+/** Every JSON patch entry that configures the owned catalog, last one winning. */
+export function catalogConfig(patch) {
+  const lines = readFileSync(patch, 'utf8').split('\n')
+  let catalog
+  for (const line of lines) {
+    if (!line.startsWith('- {') || !line.includes('"catalog"')) continue
+    const entry = JSON.parse(line.slice(2))
+    if (entry.config?.catalog !== undefined) catalog = entry.config.catalog
+  }
+  return catalog
+}
+
+export function providerData(directory, source) {
+  if (directory === undefined || source === undefined) return undefined
+  try {
+    return JSON.parse(readFileSync(join(directory, source + '.json'), 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/** Installed models in the order the source publishes them, one api map at a time. */
+function installedModels(data) {
+  if (data === undefined) return []
+  return Object.entries(data).flatMap(([api, models]) => Object.entries(models)
+    .map(([id, model]) => ({ ...model, id, api: model.api ?? api })))
+}
+
+/** Mirror the resolver's pattern rule so a filter reads the same here and there. */
+function patternToRegExp(pattern) {
+  const escaped = pattern.split(WILDCARD).map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+  return new RegExp('^' + escaped.join('.*') + '$')
+}
+
+/** A filter keeps installed facts and order, then drops what exclude names. */
+export function expandFilter(data, filter) {
+  const include = filter?.include === undefined ? undefined : filter.include.map(patternToRegExp)
+  const exclude = filter?.exclude === undefined ? [] : filter.exclude.map(patternToRegExp)
+  return installedModels(data)
+    .filter(model => (include === undefined || include.some(pattern => pattern.test(model.id)))
+      && !exclude.some(pattern => pattern.test(model.id)))
+}
+
+/** Look one id up across a provider's api maps; an api in the spec disambiguates. */
+function lookup(data, id, api) {
+  if (data === undefined) return undefined
+  for (const [key, models] of Object.entries(data)) {
+    if ((api === undefined || key === api) && models[id] !== undefined) return { ...models[id], api: models[id].api ?? key }
+  }
+  return undefined
+}
+
+function costOf(cost) {
+  if (cost === undefined) return undefined
+  return '$' + COST_FIELDS.map(field => cost[field]).join('/') + ' per 1M'
+}
+
+/** Resolve one catalog entry against the installed data it may inherit from. */
+export function resolve(spec, data, routeApi) {
+  const metadata = spec.metadata ?? {}
+  const declared = Object.keys(metadata).length > 0
+  const cloneOf = spec.template ?? spec.id
+  const base = lookup(data, cloneOf, metadata.api)
+  if (base === undefined && !declared) {
+    return { error: 'no source entry for ' + cloneOf + '; declare a template or metadata' }
+  }
+  const merged = { ...base, ...metadata, id: spec.id, name: spec.name ?? base?.name ?? spec.id }
+  // A route that names no source states its protocol once, for every model.
+  if (merged.api === undefined && routeApi !== undefined) merged.api = routeApi
+  // Capacity and the request default are different numbers, and the resolver
+  // caps one by the other: folding them would hide the mistake it refuses.
+  const capacity = metadata.maxTokens ?? base?.maxTokens
+  const missing = base === undefined
+    ? REQUIRED_METADATA.filter(field => field === 'api' ? merged.api === undefined : metadata[field] === undefined)
+    : []
+  if (missing.length > 0) return { error: 'unknown model requires complete metadata: missing ' + missing.join(', ') }
+  if (spec.defaultMaxTokens !== undefined && capacity !== undefined && spec.defaultMaxTokens > capacity) {
+    return { error: 'defaultMaxTokens ' + spec.defaultMaxTokens + ' exceeds model maxTokens ' + capacity }
+  }
+  const origins = {}
+  for (const field of INHERITED_FIELDS) {
+    if (metadata[field] !== undefined) origins[field] = METADATA
+    else if (field === 'api' && base === undefined && routeApi !== undefined) origins[field] = ROUTE
+    else if (base === undefined) origins[field] = ABSENT
+    else origins[field] = spec.template === undefined ? INSTALLED : 'template:' + spec.template
+  }
+  return {
+    model: { ...merged, maxTokens: capacity },
+    origins,
+    levels: supportedLevels(merged.thinkingLevelMap),
+    ...(spec.defaultMaxTokens === undefined ? {} : { requestMax: spec.defaultMaxTokens }),
+    ...(spec.aliases === undefined ? {} : { aliases: spec.aliases.join(',') }),
+    ...(metadata.cost?.tiers === undefined ? {} : {
+      tiers: metadata.cost.tiers.map(tier => 'above ' + tier.inputTokensAbove + ': ' + costOf(tier)).join('; '),
+    }),
+  }
+}
+
+function rowsOf(catalog, directory) {
+  const rows = []
+  for (const provider of catalog.providers ?? []) {
+    const data = providerData(directory, provider.source)
+    const hasModels = 'models' in provider
+    const hasFilter = 'filter' in provider
+    // The resolver refuses both and neither; saying so here beats serving half.
+    if (hasModels === hasFilter) {
+      rows.push({ route: provider.id, error: 'declare exactly one of models or filter' })
+      continue
+    }
+    if (hasFilter) {
+      if (data === undefined) {
+        rows.push({
+          route: provider.id,
+          error: 'filter expands the installed catalog of source "' + provider.source + '"; no harness install found',
+        })
+        continue
+      }
+      for (const model of expandFilter(data, provider.filter)) {
+        rows.push({
+          route: provider.id + '/' + model.id,
+          name: model.name ?? model.id,
+          api: model.api,
+          contextWindow: model.contextWindow,
+          maxTokens: model.maxTokens,
+          cost: costOf(model.cost),
+          levels: supportedLevels(model.thinkingLevelMap).join(','),
+          origins: 'filter:' + (provider.filter.include ?? [WILDCARD]).join(',') + ' all installed',
+        })
+      }
+      continue
+    }
+    for (const spec of provider.models ?? []) {
+      const result = resolve(spec, data, provider.api)
+      const route = provider.id + '/' + spec.id
+      if (result.error !== undefined) {
+        rows.push({ route, error: result.error })
+        continue
+      }
+      rows.push({
+        route,
+        name: result.model.name,
+        api: result.model.api,
+        contextWindow: result.model.contextWindow,
+        maxTokens: result.model.maxTokens,
+        cost: costOf(result.model.cost),
+        levels: result.levels.join(','),
+        ...(result.requestMax === undefined ? {} : { requestMax: result.requestMax }),
+        ...(result.aliases === undefined ? {} : { aliases: result.aliases }),
+        ...(result.tiers === undefined ? {} : { tiers: result.tiers }),
+        origins: INHERITED_FIELDS
+          .map(field => [field, result.origins[field]])
+          .filter(([, origin]) => origin !== INSTALLED)
+          .map(([field, origin]) => field + '=' + origin)
+          .join(' ') || 'all installed',
+      })
+    }
+  }
+  return rows
+}
+
+/**
+ * The default is part of the catalog, not a comment beside it: the resolver
+ * refuses a selection nothing serves, so a reading that skipped it would call a
+ * broken catalog readable.
+ */
+export function checkDefault(catalog, rows) {
+  const served = rows.filter(row => row.error === undefined)
+  const selection = catalog.default ?? null
+  if (served.length === 0) {
+    return selection === null ? [] : [{ route: 'default', error: 'an empty catalog requires default null' }]
+  }
+  if (selection === null || typeof selection !== 'object') {
+    return [{ route: 'default', error: 'a served catalog requires a default selection' }]
+  }
+  const alias = new Map()
+  for (const provider of catalog.providers ?? []) {
+    for (const model of provider.models ?? []) {
+      for (const name of [model.id, ...(model.aliases ?? [])]) alias.set(provider.id + '/' + name, model.id)
+    }
+  }
+  const route = selection.provider + '/' + selection.model
+  const canonical = alias.get(route)
+  const row = served.find(candidate => candidate.route === selection.provider + '/' + (canonical ?? selection.model))
+  if (row === undefined) {
+    return [{ route: 'default', error: 'provider/model is outside the managed selection: ' + route }]
+  }
+  const effort = selection.reasoningEffort
+  if (effort !== undefined && !String(row.levels).split(',').includes(effort)) {
+    return [{ route: 'default', error: 'effort is not supported by the selected model: ' + effort }]
+  }
+  return []
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const patch = join(options.home, 'profiles', options.profile, 'cordis.patch.yml')
+  const catalog = catalogConfig(patch)
+  if (catalog === undefined) {
+    process.stderr.write('no owned catalog in ' + patch + '\n'
+      + 'this profile wires models another way; see references/model-wiring.md\n')
+    process.exit(1)
+  }
+  const directory = options.data ?? dataDirectory()
+  if (directory === undefined) {
+    process.stderr.write('no harness install found; entries that inherit from it cannot be checked\n')
+  }
+  const served = rowsOf(catalog, directory)
+  const rows = [...served, ...checkDefault(catalog, served)]
+  const unresolved = rows.filter(row => row.error !== undefined).length
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ default: catalog.default ?? null, rows }, null, 2) + '\n')
+  } else {
+    for (const row of rows) {
+      if (row.error !== undefined) {
+        process.stdout.write(row.route + '\n  UNRESOLVED: ' + row.error + '\n')
+        continue
+      }
+      process.stdout.write(row.route + '\n  ' + row.name + ' | ' + row.api + ' | ctx ' + row.contextWindow
+        + ' | max ' + row.maxTokens
+        + (row.requestMax === undefined ? '' : ' | req ' + row.requestMax)
+        + ' | ' + row.cost
+        + (row.tiers === undefined ? '' : ' | tiers ' + row.tiers)
+        + ' | efforts ' + row.levels
+        + (row.aliases === undefined ? '' : ' | aliases ' + row.aliases) + '\n  inherited: ' + row.origins + '\n')
+    }
+    process.stdout.write('default: ' + JSON.stringify(catalog.default ?? null) + '\n')
+  }
+  process.exit(unresolved === 0 ? 0 : 1)
+}
+
+// Importing the resolver must not run the CLI: the spec reads it that way.
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main()