Phase 2.6.Q — models.dev as the model-metadata source (ADR-0071) + DB-backed catalog (ADR-0072)

.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 {