Phase 2.6.Q — models.dev as the model-metadata source (ADR-0071)

.github/workflows/models-catalog.yml

@@ -0,0 +1,115 @@
+# The model-catalog guards (ADR-0071 §9). Two scheduled lanes, neither of which gates a PR:
+#
+#   • weekly-catalog-check — did any ALREADY-SHIPPED model's price MOVE or VANISH? A moved price feeds the
+#     ADR-0028 cost cap, so it is a HUMAN decision surfaced as a red check, never a silent bot commit. `pnpm
+#     sync:models` exits non-zero on a moved/vanished shipped price; benign additive drift stays green (a weekly
+#     red-no-matter-what trains the maintainer to ignore it — the erosion sync.mjs's own comments warn against).
+#
+#   • nightly-effort-conformance — the ONLY mechanism that catches a stale catalog re-introducing the reasoning
+#     bug: for each shipped reasoning model it asks the REAL provider whether it accepts every tier the catalog
+#     claims. A one-off manual probe proves a fact once; the catalog drifts continuously, so this runs nightly.
+#
+# Third-party actions are pinned to a full commit SHA (the `# vX.Y.Z` comment tracks the release) — the same
+# convention ci.yml uses, so a moved tag cannot inject unreviewed code.
+name: model-catalog
+
+on:
+  schedule:
+    # Monday 06:00 UTC — the drift check. Ahead of a typical review week, so a red one is seen on Monday.
+    - cron: '0 6 * * 1'
+    # 07:00 UTC nightly — the live effort conformance (key-gated; skips with no key).
+    - cron: '0 7 * * *'
+  # Manual trigger for both, so a maintainer can run either on demand without waiting for the cron.
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: model-catalog-${{ github.event_name }}
+  cancel-in-progress: false
+
+jobs:
+  weekly-catalog-check:
+    name: shipped-price-change guard
+    # Only the weekly cron (and a manual run); the nightly cron skips this job.
+    if: github.event.schedule != '0 7 * * *'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - name: Set up pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - name: Install (frozen lockfile)
+        run: pnpm install --frozen-lockfile
+      # `pnpm sync:models` builds `@relavium/llm` AND its `@relavium/shared` dependency first (via turbo `^build`) —
+      # the `@relavium/*` `exports` resolve only to `dist/`, which is gitignored, so a fresh runner has no built
+      # `@relavium/shared` and the sync's own `tsc`/dist import would otherwise die on TS2307 before any guard runs.
+      # `pnpm sync:models` fetches models.dev, normalizes it, and applies the money guards. It fails RED on the ONE
+      # thing that must be a human decision: a MOVED or VANISHED price on a model we already ship (a rate that
+      # silently moves also silently moves how much the ADR-0028 cost cap protects). It does NOT red on benign
+      # additive drift — models.dev adds models in our four providers constantly, and a check that is red every
+      # week trains the maintainer to ignore it, which is exactly how the price-change protection would erode
+      # (sync.mjs says so in its own comments). New models "merge automatically" via the deferred auto-PR
+      # (deferred-tasks.md); until it lands they are simply picked up by the next local `pnpm sync:models`. The
+      # snapshot this job writes into the ephemeral CI checkout is discarded — only the exit code is the guard.
+      - name: No ALREADY-SHIPPED model's price moved or vanished
+        run: pnpm sync:models
+
+  nightly-effort-conformance:
+    name: effort conformance (live)
+    # Only the nightly cron (and a manual run); the weekly cron skips this job.
+    if: github.event.schedule != '0 6 * * 1'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - name: Set up pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - name: Install (frozen lockfile)
+        run: pnpm install --frozen-lockfile
+      # Build the dependency closure first: the conformance suite imports `@relavium/shared`, whose `exports` resolve
+      # only to a gitignored `dist/`. Without this a fresh runner cannot resolve the cross-package entry and EVERY
+      # conformance file errors out before a single live probe — a red that looks identical to a real catalog drift.
+      # Turbo `^build` builds `@relavium/shared` ahead of `@relavium/llm` (mirrors ci.yml's pre-test build).
+      - name: Build workspace dependencies
+        run: pnpm turbo run build --filter=@relavium/llm
+      # Guard against a FALSE-GREEN nightly: the live cases are `it.skipIf(<key> === '')`, so with NO provider secret
+      # configured EVERY probe skips and the suite passes — a green that means "nothing was checked", indistinguishable
+      # from "all tiers verified". Fail loudly instead, so a green nightly is proof that probes actually ran.
+      - name: Require at least one provider secret
+        run: |
+          if [ -z "${ANTHROPIC_API_KEY}${OPENAI_API_KEY}${GEMINI_API_KEY}${DEEPSEEK_API_KEY}" ]; then
+            echo "::error::No provider secret is configured — every live effort probe would SKIP, and a green run would falsely read as 'all tiers verified'. Configure at least one of ANTHROPIC/OPENAI/GEMINI/DEEPSEEK_API_KEY."
+            exit 1
+          fi
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+      # The conformance suite (fixtures + the `it.skipIf(<key> === '')` live cases). With the provider keys set here
+      # the live cases execute — and a catalog that claims a tier a model rejects fails red — while a missing key
+      # simply skips that provider's lane. Scoped to `src/conformance` so a flaky live case cannot widen the red
+      # surface to the whole package's unit suite.
+      - name: Live effort conformance
+        run: pnpm --filter @relavium/llm exec vitest run src/conformance
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}

CLAUDE.md

@@ -47,8 +47,10 @@ inbound MCP client, and the full YAML lifecycle (`create`/`import`/`export`).
 Home, the two-registry command system (`/` palette + shell commands), per-tool
 approval/modes (ask/plan/accept-edits/auto), `@`-mention file injection, context
 compaction, the onboarding wizard + live model catalog, reasoning rendering, and regression
-hardening. **Phase 2.6 (Conversational Authoring and the First-Class CLI) is next up**
-— a full-screen Home-managed CLI with conversational workflow authoring, management
+hardening. **Phase 2.6 (Conversational Authoring and the First-Class CLI) is in progress** — two
+workstreams are merged to `main`: **2.6.F** (the platform floor + the full-screen TUI renderer,
+PR #74, 2026-07-11) and **2.6.C** (the reseat transcript-carry + the `/cost` per-model breakdown,
+PR #75, 2026-07-13). The phase is a full-screen Home-managed CLI with conversational workflow authoring, management
 browsers, competitor-breadth tools, settings/theming/`en`+`tr` localization, and the
 run-ops resume follow-up.
 

apps/cli/src/chat/agent-source.test.ts

@@ -36,6 +36,33 @@ describe('resolveChatAgent', () => {
     expect(agent.provider).toBe('openai');
   });
 
+  it('passes opts.defaultProvider VERBATIM to the default agent — an unplaceable id starts (ADR-0059, Bug-3 wiring)', () => {
+    // The decisive Bug-3 hop: a persisted provider carried into the default agent so a live-discovered id the prefix
+    // map cannot place (`chat-latest`) still resolves. Without this passthrough it throws "cannot infer a provider".
+    const agent = resolveChatAgent(undefined, {
+      cwd: dir,
+      projectConfigDir: undefined,
+      defaultModel: 'chat-latest',
+      defaultProvider: 'openai',
+    });
+    expect(agent.model).toBe('chat-latest');
+    expect(agent.provider).toBe('openai');
+  });
+
+  it('still throws a clean CliError for an unplaceable id when NO defaultProvider is persisted', () => {
+    let caught: unknown;
+    try {
+      resolveChatAgent(undefined, {
+        cwd: dir,
+        projectConfigDir: undefined,
+        defaultModel: 'chat-latest',
+      });
+    } catch (err) {
+      caught = err;
+    }
+    expect(isCliError(caught)).toBe(true);
+  });
+
   it('falls back to DEFAULT_CHAT_MODEL when neither --agent nor [chat].default_model is set', () => {
     const agent = resolveChatAgent(undefined, {
       cwd: dir,

apps/cli/src/chat/agent-source.ts

@@ -1,5 +1,5 @@
 import { parseAgent, type AgentDefinition } from '@relavium/core';
-import type { ReasoningEffort } from '@relavium/shared';
+import type { LlmProviderId, ReasoningEffort } from '@relavium/shared';
 
 import { resolveYamlSource } from '../workflows/resolve.js';
 import { buildDefaultChatAgent, DEFAULT_CHAT_MODEL } from './default-agent.js';
@@ -9,6 +9,9 @@ export interface ResolveChatAgentOptions {
   readonly projectConfigDir: string | undefined;
   /** The resolved `[chat].default_model` — used only to build the default agent when no `--agent` is given. */
   readonly defaultModel: string | undefined;
+  /** The resolved `[chat].default_provider` (ADR-0059) — persisted at pick time, used verbatim for the DEFAULT
+   *  agent so a live-discovered id whose prefix the inference cannot place still resolves. Absent ⇒ inference. */
+  readonly defaultProvider?: LlmProviderId;
   /** The resolved `[chat].reasoning_effort` (ADR-0066) — baked onto the DEFAULT agent only (an authored `--agent`
    *  owns its own `reasoning_effort`, never overridden by config). Absent ⇒ no reasoning control. */
   readonly reasoningEffort?: ReasoningEffort;
@@ -28,7 +31,11 @@ export function resolveChatAgent(
   opts: ResolveChatAgentOptions,
 ): AgentDefinition {
   if (agentRef === undefined) {
-    return buildDefaultChatAgent(opts.defaultModel ?? DEFAULT_CHAT_MODEL, opts.reasoningEffort);
+    return buildDefaultChatAgent(
+      opts.defaultModel ?? DEFAULT_CHAT_MODEL,
+      opts.reasoningEffort,
+      opts.defaultProvider,
+    );
   }
   const source = resolveYamlSource(agentRef, {
     cwd: opts.cwd,

apps/cli/src/chat/default-agent.test.ts

@@ -28,6 +28,14 @@ describe('inferProviderFromModel', () => {
     expect(inferProviderFromModel('llama-3')).toBeUndefined();
     expect(inferProviderFromModel('')).toBeUndefined();
   });
+
+  it('resolves a catalog-known id via the catalog branch (ADR-0071 hardening)', () => {
+    // Every SHIPPED id ALSO matches a prefix, so the catalog and the heuristic agree — this cannot prove the catalog
+    // is consulted FIRST, only that the catalog branch is wired and returns the right provider. The catalog-first
+    // ORDER only bites for a live-only id the prefix cannot place (e.g. `chatgpt-4o-latest`), which no shipped
+    // catalog id exercises; there the PERSISTED provider (see buildDefaultChatAgent) is the decisive fix.
+    expect(inferProviderFromModel('gpt-5-chat-latest')).toBe('openai'); // a real catalog id
+  });
 });
 
 describe('buildDefaultChatAgent', () => {
@@ -56,6 +64,21 @@ describe('buildDefaultChatAgent', () => {
     expect(buildDefaultChatAgent('gemini-2.5-pro').provider).toBe('gemini');
   });
 
+  it('uses a persisted knownProvider VERBATIM, skipping inference — the Bug-3 fix (ADR-0059)', () => {
+    // `chat-latest` is a live OpenAI id `keepOpenAiModelId` admits; it has no gpt/o-digit prefix and is not in the
+    // catalog, so inference returns undefined and the chat used to crash "cannot infer a provider". A provider
+    // persisted at pick time is used as-is, so the chat starts on the right provider.
+    const agent = buildDefaultChatAgent('chat-latest', undefined, 'openai');
+    expect(agent.provider).toBe('openai');
+    expect(agent.model).toBe('chat-latest');
+  });
+
+  it('a knownProvider makes the throw path unreachable even for an id inference cannot place', () => {
+    expect(buildDefaultChatAgent('mystery-model-9', undefined, 'anthropic').provider).toBe(
+      'anthropic',
+    );
+  });
+
   it('bakes the [chat].reasoning_effort default onto the agent, and OMITS it when absent (ADR-0066)', () => {
     expect(buildDefaultChatAgent('claude-opus-4-8', 'high').reasoning_effort).toBe('high');
     // Absent ⇒ the key is not present (never an explicit `undefined` under exactOptionalPropertyTypes).

apps/cli/src/chat/default-agent.ts

@@ -1,4 +1,4 @@
-import type { ProviderId } from '@relavium/llm';
+import { catalogModel, type ProviderId } from '@relavium/llm';
 import type { Agent, ReasoningEffort } from '@relavium/shared';
 
 import { CliError } from '../process/errors.js';
@@ -35,17 +35,27 @@ const DEFAULT_CHAT_SYSTEM_PROMPT =
 export const DEFAULT_CHAT_TOOLS: readonly string[] = ['read_file', 'list_directory', 'git_status'];
 
 /**
- * Infer the provider that serves a model id from its well-known prefix. Phase-1 has no model→provider
- * catalog lookup wired for the chat path, and a default agent must name a provider ({@link Agent.provider});
- * this covers the four `@relavium/llm` seam providers (ADR-0011) and returns `undefined` for an unrecognized
- * model so the caller fails with a clear "bind an explicit `--agent`" message rather than guess wrong.
+ * Infer the provider that serves a model id — **catalog first** (ADR-0071), then a well-known-prefix fallback.
+ *
+ * A default agent must name a provider ({@link Agent.provider}). The catalog knows the provider of every model it
+ * carries AUTHORITATIVELY, regardless of how the id is spelled — `chatgpt-4o-latest` has no `gpt`/`o<digit>` prefix
+ * yet is unmistakably openai — so a catalog hit is trusted before the heuristic. The prefix map remains the fallback
+ * for an id the catalog does not carry (a brand-new model, or a custom `base_url` endpoint), covering the four
+ * `@relavium/llm` seam providers (ADR-0011). Returns `undefined` for an id neither knows, so the caller fails with a
+ * clear "bind an explicit `--agent`" message rather than guess wrong.
+ *
+ * The truly robust source is a PERSISTED provider from pick time (the picker knows it authoritatively — the live
+ * `/models` list is per-provider); {@link buildDefaultChatAgent} prefers that and only falls back to this inference.
  */
 export function inferProviderFromModel(model: string): ProviderId | undefined {
+  // Normalize ONCE — catalog ids are lowercase, and the prefix fallback lowercases too, so a mixed-case id
+  // (`Claude-Opus-4-8`) resolves via the CATALOG (authoritative) instead of only via the prefix heuristic.
   const m = model.toLowerCase();
+  const cataloged = catalogModel(m)?.provider;
+  if (cataloged !== undefined) return cataloged;
   if (m.startsWith('claude')) return 'anthropic';
   // OpenAI's GPT family + the o-series reasoning models. `/^o\d/` matches the whole o-series (o1/o3/o4 and
-  // future o5+) in one expression rather than enumerating each prefix. (A model→provider catalog lookup is
-  // the eventual robust source; this prefix map is the deliberate Phase-1 zero-config default.)
+  // future o5+) in one expression rather than enumerating each prefix.
   if (m.startsWith('gpt') || /^o\d/.test(m)) return 'openai';
   if (m.startsWith('gemini')) return 'gemini';
   if (m.startsWith('deepseek')) return 'deepseek';
@@ -54,19 +64,28 @@ export function inferProviderFromModel(model: string): ProviderId | undefined {
 
 /**
  * Build the built-in default chat agent over `model` (the resolved `[chat].default_model`, or
- * {@link DEFAULT_CHAT_MODEL}). Throws a clean exit-2 {@link CliError} when the provider cannot be inferred
- * from the model id — guiding the user to set a known `[chat].default_model` or bind an explicit `--agent`.
- * `reasoningEffort` (the resolved `[chat].reasoning_effort`, ADR-0066) is baked onto the agent so the default
- * chat honors the config default; absent ⇒ no reasoning control (the provider default).
+ * {@link DEFAULT_CHAT_MODEL}).
+ *
+ * `knownProvider` — the provider PERSISTED alongside the model (`[chat]`/`[preferences].default_provider`, written by
+ * the picker/wizard at pick time, ADR-0059's "the provider is authoritative, never re-inferred"). When present it is
+ * used verbatim and inference is SKIPPED, so a model whose id the prefix map cannot place — a live-discovered
+ * `chatgpt-4o-latest`, a custom-endpoint id — still starts. Only when it is absent does this fall back to
+ * {@link inferProviderFromModel}; a clean exit-2 {@link CliError} then guides the user to a known model or `--agent`.
+ * `reasoningEffort` (the resolved `[chat].reasoning_effort`, ADR-0066) is baked onto the agent so the default chat
+ * honors the config default; absent ⇒ no reasoning control (the provider default).
  */
-export function buildDefaultChatAgent(model: string, reasoningEffort?: ReasoningEffort): Agent {
-  const provider = inferProviderFromModel(model);
+export function buildDefaultChatAgent(
+  model: string,
+  reasoningEffort?: ReasoningEffort,
+  knownProvider?: ProviderId,
+): Agent {
+  const provider = knownProvider ?? inferProviderFromModel(model);
   if (provider === undefined) {
     throw new CliError(
       'invalid_invocation',
       `cannot infer a provider for chat model '${model}'. Set [chat].default_model to a known model ` +
-        `(claude-*, gpt-*, gemini-*, deepseek-*), or bind an explicit agent with ` +
-        `'relavium chat --agent <ref>'.`,
+        `(claude-*, gpt-*, gemini-*, deepseek-*) — or set [chat].default_provider, or bind an explicit agent ` +
+        `with 'relavium chat --agent <ref>'.`,
     );
   }
   return {