typeclaw 0.4.0 → 0.5.0

package/src/cli/init.ts

@@ -11,7 +11,7 @@ import {
   type KnownModelRef,
   type KnownProviderId,
 } from '@/config/providers'
-import type { DockerAvailability } from '@/container'
+import { checkDockerAvailable, type DockerAvailability } from '@/container'
 import {
   findAgentDir,
   formatEagerGithubWebhookInstallResult,
@@ -29,8 +29,9 @@ import {
 } from '@/init'
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
 import { fetchModelOptions, type ModelOption } from '@/init/models-dev'
-import { makeOAuthLoginRunner } from '@/init/oauth-login'
+import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
 
+import { buildOAuthCallbacks } from './oauth-callbacks'
 import { c, done, errorLine } from './ui'
 
 // ESC and Ctrl+C both produce clack's cancel symbol (the keypress layer
@@ -54,9 +55,15 @@ import { c, done, errorLine } from './ui'
 // a clean exit. Inside an active clack prompt Ctrl+C is still aliased to
 // cancel, so the abort hotkey is "cancel twice in a row".
 export class WizardAbortedError extends Error {
-  constructor() {
+  // When the wizard ran a successful eager OAuth login before aborting, the
+  // resulting credentials are already on disk at `<cwd>/secrets.json`. The
+  // CLI surfaces this on abort so the user knows to either re-run init in
+  // the same directory (the credentials will be reused) or delete the file.
+  readonly oauthCredentialsSaved: boolean
+  constructor(options: { oauthCredentialsSaved?: boolean } = {}) {
     super('Wizard aborted by user')
     this.name = 'WizardAbortedError'
+    this.oauthCredentialsSaved = options.oauthCredentialsSaved === true
   }
 }
 
@@ -102,11 +109,37 @@ export const init = defineCommand({
     intro('Initializing TypeClaw...')
     log.info('Press ESC at any prompt to go back. Press ESC twice in a row to abort.')
 
+    // Docker preflight runs BEFORE the wizard so an OAuth login (which the
+    // wizard fires the moment the user picks "OAuth (browser login)") doesn't
+    // burn a real browser flow on an agent folder we can't actually start.
+    // `runInit` re-runs the preflight as a defense-in-depth gate, but
+    // surfacing the failure here lets the user fix Docker without re-doing
+    // every wizard step.
+    const preflightSpinner = spinner()
+    preflightSpinner.start('Checking Docker...')
+    const preflight = await checkDockerAvailable()
+    if (!preflight.ok) {
+      preflightSpinner.error(preflightFailureSummary(preflight))
+      note(preflightFailureGuidance(preflight).join('\n'), 'Docker check failed')
+      process.exit(1)
+    }
+    preflightSpinner.stop('Docker is reachable.')
+
     let collected: CollectedInputs
     try {
       collected = await collectWizardInputs(cwd, defaultWizardPrompts)
     } catch (error) {
       if (error instanceof WizardAbortedError) {
+        if (error.oauthCredentialsSaved) {
+          note(
+            [
+              'OAuth credentials were saved to `secrets.json` before you aborted.',
+              'Re-run `typeclaw init` here to pick up where you left off (the credentials',
+              'will be reused), or delete `secrets.json` if you want a clean restart.',
+            ].join('\n'),
+            'Saved OAuth credentials',
+          )
+        }
         cancel('Aborted.')
         process.exit(0)
       }
@@ -309,9 +342,24 @@ export interface WizardPrompts {
   hasExistingChannelSecrets: (cwd: string, channel: Exclude<ChannelChoice, 'none'>) => Promise<boolean>
   askReuseExistingChannel: (channel: Exclude<ChannelChoice, 'none'>) => Promise<StepResult<'reuse' | 'prompt'>>
   runChannelFlow: (choice: ChannelChoice) => Promise<StepResult<CollectedInputs['channelSecrets']>>
-  buildOAuthAuth: (provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]) => LLMAuth
+  runOAuthLogin: (
+    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+    cwd: string,
+    model: KnownModelRef,
+  ) => Promise<OAuthLoginResult>
+  // Asked after a failed OAuth login. `apiKeyAvailable` is true when the
+  // provider also supports api-key auth (so the wizard can offer a fallback
+  // path); false for OAuth-only providers like openai-codex, where the only
+  // options are retry or abort.
+  askOAuthFailureRecovery: (
+    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+    reason: string,
+    apiKeyAvailable: boolean,
+  ) => Promise<OAuthFailureRecovery>
 }
 
+export type OAuthFailureRecovery = 'retry' | 'api-key' | 'abort'
+
 export const defaultWizardPrompts: WizardPrompts = {
   loadCatalog,
   readExistingApiKey: readExistingProviderApiKey,
@@ -326,10 +374,8 @@ export const defaultWizardPrompts: WizardPrompts = {
   hasExistingChannelSecrets,
   askReuseExistingChannel,
   runChannelFlow,
-  buildOAuthAuth: (provider) => ({
-    kind: 'oauth',
-    runLogin: makeOAuthLoginRunner(buildOAuthCallbacks(provider.name)),
-  }),
+  runOAuthLogin: (provider, cwd, model) => makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))({ cwd, model }),
+  askOAuthFailureRecovery,
 }
 
 export async function collectWizardInputs(cwd: string, prompts: WizardPrompts): Promise<CollectedInputs> {
@@ -337,10 +383,15 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
   const state: WizardState = { catalog }
   let step: StepId = 'pick-provider'
   let pendingBackOrigin: StepId | null = null
+  let oauthCredentialsSaved = false
+
+  const abort = (): never => {
+    throw new WizardAbortedError({ oauthCredentialsSaved })
+  }
 
   const onResult = <T>(currentStep: StepId, result: StepResult<T>): StepResult<T> => {
     if (result.kind === 'back') {
-      if (pendingBackOrigin === currentStep) throw new WizardAbortedError()
+      if (pendingBackOrigin === currentStep) abort()
       pendingBackOrigin = currentStep
     } else if (!result.auto) {
       pendingBackOrigin = null
@@ -410,7 +461,32 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
         }
         state.authMethod = result.value
         if (result.value === 'oauth') {
-          state.llmAuth = prompts.buildOAuthAuth(provider)
+          // Run the browser login eagerly so the user sees the OAuth URL the
+          // moment they pick "OAuth (browser login)" — not at the end of the
+          // wizard. On failure we ask the user how to recover (retry / fall
+          // back to API key / abort) instead of dumping them back into the
+          // auth method picker with no guidance.
+          const login = await runOAuthLoginSafely(prompts, provider, cwd, state.model!.ref)
+          if (!login.ok) {
+            const recovery = await prompts.askOAuthFailureRecovery(
+              provider,
+              login.reason,
+              providerSupportsApiKey(provider),
+            )
+            // The recovery prompt is a fresh user decision, so it must clear
+            // any back-token left over from an earlier step. Without this, a
+            // sequence like `enter-api-key → back → autoValue('oauth') →
+            // OAuth fails → recovery=api-key → enter-api-key` would treat the
+            // user's NEXT back press as a double-back and abort the wizard.
+            pendingBackOrigin = null
+            if (recovery === 'abort') abort()
+            state.authMethod = recovery === 'api-key' ? 'api-key' : undefined
+            state.llmAuth = undefined
+            step = recovery === 'api-key' ? 'enter-api-key' : 'pick-auth-method'
+            break
+          }
+          oauthCredentialsSaved = true
+          state.llmAuth = { kind: 'oauth-completed' }
           step = stepAfterDefaultAuth(state)
         } else {
           step = 'enter-api-key'
@@ -498,7 +574,25 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
         }
         state.visionAuthMethod = result.value
         if (result.value === 'oauth') {
-          state.visionLlmAuth = prompts.buildOAuthAuth(provider)
+          // Same eager-login + recovery-prompt rationale as the default-provider branch above.
+          const login = await runOAuthLoginSafely(prompts, provider, cwd, state.visionModel!.ref)
+          if (!login.ok) {
+            const recovery = await prompts.askOAuthFailureRecovery(
+              provider,
+              login.reason,
+              providerSupportsApiKey(provider),
+            )
+            // See the matching pendingBackOrigin reset in the default-provider
+            // branch above — same reasoning applies to vision auth recovery.
+            pendingBackOrigin = null
+            if (recovery === 'abort') abort()
+            state.visionAuthMethod = recovery === 'api-key' ? 'api-key' : undefined
+            state.visionLlmAuth = undefined
+            step = recovery === 'api-key' ? 'enter-vision-api-key' : 'pick-vision-auth-method'
+            break
+          }
+          oauthCredentialsSaved = true
+          state.visionLlmAuth = { kind: 'oauth-completed' }
           step = 'pick-channel'
         } else {
           step = 'enter-vision-api-key'
@@ -570,6 +664,25 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
   }
 }
 
+// Belt-and-suspenders wrapper: `makeOAuthLoginRunner` already catches the
+// upstream pi-ai login flow and returns `{ ok: false, reason }`, but the
+// wizard cannot afford ANY uncaught throw from a custom runner (test seam,
+// future plugin-contributed runner) — it would bubble out of
+// `collectWizardInputs` and exit the whole init. Coerce unexpected throws to
+// the normal failure path so the recovery prompt always fires.
+async function runOAuthLoginSafely(
+  prompts: WizardPrompts,
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  cwd: string,
+  model: KnownModelRef,
+): Promise<OAuthLoginResult> {
+  try {
+    return await prompts.runOAuthLogin(provider, cwd, model)
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
 function finalize(state: WizardState, channelSecrets: CollectedInputs['channelSecrets']): CollectedInputs {
   return {
     model: state.model!,
@@ -768,6 +881,28 @@ async function askApiKey(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]): P
   return value(apiKey)
 }
 
+async function askOAuthFailureRecovery(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  reason: string,
+  apiKeyAvailable: boolean,
+): Promise<OAuthFailureRecovery> {
+  note(reason, `${provider.name} OAuth login failed`)
+  const options: Array<{ value: OAuthFailureRecovery; label: string; hint?: string }> = [
+    { value: 'retry', label: 'Retry OAuth login' },
+  ]
+  if (apiKeyAvailable) {
+    options.push({ value: 'api-key', label: `Use a ${provider.name} API key instead` })
+  }
+  options.push({ value: 'abort', label: 'Abort init', hint: 'you can re-run `typeclaw init` later' })
+  const choice = await select<OAuthFailureRecovery>({
+    message: 'What next?',
+    options,
+    initialValue: 'retry',
+  })
+  if (isCancel(choice)) return 'abort'
+  return choice
+}
+
 async function pickChannel(initial: ChannelChoice | undefined): Promise<StepResult<ChannelChoice>> {
   const choice = await select<ChannelChoice>({
     message: 'Pick a channel to wire (you can add more later by editing typeclaw.json + secrets.json)',
@@ -1261,37 +1396,6 @@ export async function decideExistingApiKeyReuse(
   return reuse === true ? 'reuse' : 'prompt'
 }
 
-// Wraps the OAuth lifecycle into the same clack idiom the rest of the wizard
-// uses: a spinner over the "waiting for login" period, with onAuth printing
-// the URL the user needs to open and onPrompt falling back to a `text`
-// prompt for the manual code path. The spinner is started by onAuth and
-// stopped by the caller (runInit) — we don't try to manage it here because
-// the spinner lifecycle has to span emit('start') -> emit('done').
-function buildOAuthCallbacks(providerName: string) {
-  return {
-    onAuth: (url: string, instructions?: string) => {
-      // Don't put the URL inside note(): clack wraps long lines with the box
-      // border `│` on each wrapped segment, which corrupts the URL when the
-      // user copy-pastes it. Keep instructional text in the box, but print
-      // the URL itself as a bare console.log line that any terminal will
-      // hyperlink intact.
-      const preamble = [`Open this URL in your browser to authorize ${providerName}.`]
-      if (instructions) preamble.push('', instructions)
-      note(preamble.join('\n'), 'Browser login')
-      console.log(url)
-      console.log('')
-    },
-    onProgress: (message: string) => {
-      log.info(message)
-    },
-    onPrompt: async (message: string, placeholder?: string): Promise<string | null> => {
-      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
-      if (isCancel(value)) return null
-      return value
-    },
-  }
-}
-
 function uniqueProviders(options: ModelOption[]): KnownProviderId[] {
   const seen = new Set<KnownProviderId>()
   const out: KnownProviderId[] = []

package/src/cli/model.ts

@@ -157,15 +157,23 @@ const listSub = defineCommand({
     }
 
     const profileWidth = Math.max(7, ...entries.map((e) => e.profile.length))
-    const refWidth = Math.max(3, ...entries.map((e) => e.ref.length))
+    const refDisplay = (e: (typeof entries)[number]): string =>
+      e.refs.length > 1 ? `${e.ref} ${c.dim(`(+${e.refs.length - 1} fallback)`)}` : e.ref
+    const refWidth = Math.max(3, ...entries.map((e) => e.ref.length + (e.refs.length > 1 ? 14 : 0)))
 
     const header = `${'PROFILE'.padEnd(profileWidth)}  ${'REF'.padEnd(refWidth)}  PROVIDER  STATUS`
     console.log(c.dim(header))
     for (const e of entries) {
       const star = e.isDefault ? c.cyan('*') : ' '
       const status = e.credentialStatus === 'available' ? c.green('ok') : c.yellow('missing-credentials')
-      const line = `${star}${e.profile.padEnd(profileWidth - 1)}  ${e.ref.padEnd(refWidth)}  ${e.providerId.padEnd(12)}  ${status}`
+      const line = `${star}${e.profile.padEnd(profileWidth - 1)}  ${refDisplay(e).padEnd(refWidth)}  ${e.providerId.padEnd(12)}  ${status}`
       console.log(line)
+      if (e.refs.length > 1) {
+        for (let i = 1; i < e.refs.length; i++) {
+          const fb = e.refs[i]!
+          console.log(`${' '.padEnd(profileWidth + 2)}↳ ${c.dim(fb)}`)
+        }
+      }
     }
   },
 })

package/src/cli/oauth-callbacks.ts

@@ -0,0 +1,49 @@
+import { isCancel, log, note, text } from '@clack/prompts'
+
+import type { OAuthCallbacks } from '@/init/oauth-login'
+
+// Shared between `typeclaw init` (src/cli/init.ts) and `typeclaw provider
+// add/set` (src/cli/provider.ts). Both call into the same OAuth runner, so
+// they need to render the same UX: a note() box with the URL + cross-device
+// guidance, a `text()` prompt for the post-callback manual fallback, and a
+// concurrent `onManualCodeInput` prompt for users whose browser is on a
+// different host than the CLI. See src/init/oauth-login.ts for the contract
+// on each callback and why onManualCodeInput is required for cross-device.
+export function buildOAuthCallbacks(providerName: string): OAuthCallbacks {
+  return {
+    onAuth: (url, instructions) => {
+      // Don't put the URL inside note(): clack wraps long lines with the box
+      // border `│` on each wrapped segment, which corrupts the URL when the
+      // user copy-pastes it. Keep instructional text in the box, but print
+      // the URL itself as a bare console.log line that any terminal will
+      // hyperlink intact.
+      const preamble = [
+        `Open this URL in your browser to sign in to ${providerName}.`,
+        '',
+        'If your browser shows "this site can\'t be reached" after you sign in,',
+        'copy the full address from the top of the browser and paste it below.',
+      ]
+      if (instructions) preamble.push('', instructions)
+      note(preamble.join('\n'), 'Browser login')
+      console.log(url)
+      console.log('')
+    },
+    onProgress: (message) => {
+      log.info(message)
+    },
+    onPrompt: async (message, placeholder) => {
+      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
+      if (isCancel(value)) return null
+      return value
+    },
+    onManualCodeInput: async () => {
+      const value = await text({
+        message:
+          'If your browser shows "this site can\'t be reached" after you sign in, copy the full address from the top of the browser and paste it here:',
+        placeholder: 'http://localhost:1455/auth/callback?code=...&state=...',
+      })
+      if (isCancel(value)) throw new Error('Login cancelled by user')
+      return value
+    },
+  }
+}

package/src/cli/provider.ts

@@ -1,4 +1,4 @@
-import { cancel, intro, isCancel, log, note, password, select, text } from '@clack/prompts'
+import { cancel, intro, isCancel, log, password, select } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import {
@@ -17,6 +17,7 @@ import {
 import { findAgentDir, isInitialized } from '@/init'
 import { makeOAuthLoginRunner } from '@/init/oauth-login'
 
+import { buildOAuthCallbacks } from './oauth-callbacks'
 import { c, done, errorLine } from './ui'
 
 const addSub = defineCommand({
@@ -366,25 +367,7 @@ async function runOAuthLogin(cwd: string, providerId: KnownProviderId): Promise<
   }
   const modelRef = `${providerId}/${ref}` as const
 
-  const callbacks = {
-    onAuth: (url: string, instructions?: string) => {
-      const preamble = [`Open this URL in your browser to authorize ${provider.name}.`]
-      if (instructions) preamble.push('', instructions)
-      note(preamble.join('\n'), 'Browser login')
-      console.log(url)
-      console.log('')
-    },
-    onProgress: (message: string) => {
-      log.info(message)
-    },
-    onPrompt: async (message: string, placeholder?: string): Promise<string | null> => {
-      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
-      if (isCancel(value)) return null
-      return value
-    },
-  }
-
-  const runner = makeOAuthLoginRunner(callbacks)
+  const runner = makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))
   const result = await runner({ cwd, model: modelRef as Parameters<typeof runner>[0]['model'] })
   if (!result.ok) return { ok: false, reason: result.reason }
   return { ok: true }

package/src/config/config.ts

@@ -103,6 +103,19 @@ const dockerfileObjectSchema = z.object({
   // edit. Opt-out with `cloudflared: false` to skip the ~35MB binary on
   // agents that don't use tunnels.
   cloudflared: z.boolean().default(true),
+  // Install xvfb so the entrypoint shim can spawn an Xvfb virtual X
+  // server and export DISPLAY, giving headed Chrome (agent-browser
+  // --headed, Playwright headful) a real X11 display to connect to.
+  // Default `true` because modern bot detection (Akamai/Cloudflare Bot
+  // Manager) fingerprints `--headless` and `--headless=new` regardless
+  // of UA spoof, and headed-via-Xvfb is the cheapest path to a passing
+  // fingerprint from a container. Opt-out with `xvfb: false` to save
+  // ~5MB image + ~10MB RAM/idle on agents that never touch a browser.
+  // The shim self-heals — when Xvfb isn't on PATH it execs the agent
+  // directly, no other Dockerfile or shim change needed. Boolean-only
+  // because the package has no API-stable versioning that matters
+  // here; xvfb tracks the upstream X server release.
+  xvfb: z.boolean().default(true),
   append: z.array(dockerfileLineSchema).default([]),
 })
 
@@ -278,32 +291,50 @@ const tunnelsArraySchema = z
     }
   })
 
-// `models` is a map from profile name to a single curated model ref. The
+// `models` maps a profile name to one or more curated model refs. The
 // `default` profile is mandatory; every other profile is optional and falls
 // back to `default` at resolution time (see `resolveProfile`).
 //
+// Each value is either a single `KnownModelRef` or a non-empty array of refs
+// forming a fallback chain: when a turn against the first ref fails (hard
+// throw or a soft provider error), the runtime disposes the failed session
+// and replays the same prompt against the next ref. Schema accepts both
+// shapes for ergonomics; the parsed value is always normalised to a
+// non-empty array so downstream consumers read a uniform `KnownModelRef[]`.
+//
 // Profile names are open strings; the runtime recognizes a handful of
 // well-known names by convention (`default`, `fast`, `deep`, `vision`) but
-// any string is valid. Subagents may declare a static profile preference;
-// callers may override per-spawn. Unknown profile names resolve to `default`
-// with a one-time warning at session construction.
+// any string is valid. Unknown profile names resolve to `default` with a
+// one-time warning at session construction.
 //
 // The pre-multi-model schema had a single `model: KnownModelRef` at the top
 // level. `migrateLegacyConfigShape` rewrites that to `models: { default: ... }`
 // on first load (and writes the result back to disk + commits via
 // `persistMigratedConfig`), so every downstream consumer sees the new shape.
+const modelRefOrChainSchema = z
+  .union([
+    z.enum(knownModelRefs),
+    z
+      .array(z.enum(knownModelRefs))
+      .min(1)
+      // Reject exact duplicates in a chain — retrying the same ref after the
+      // same class of failure is almost certainly a config typo, and silently
+      // deduping would mask user intent. Different models from the same
+      // provider (e.g. `["openai/gpt-5.4-nano", "openai/gpt-5.4-mini"]`) are
+      // still valid because they hit distinct upstream endpoints.
+      .refine((arr) => new Set(arr).size === arr.length, {
+        message: 'models chain must not contain duplicate refs',
+      }),
+  ])
+  .transform((value) => (Array.isArray(value) ? value : [value]))
 export const modelsSchema = z
-  .record(z.string().min(1), z.enum(knownModelRefs))
+  .record(z.string().min(1), modelRefOrChainSchema)
   .refine((m) => 'default' in m, { message: 'models.default is required' })
 
-// Zod's `z.record(..., refine)` doesn't refine the inferred type — the inferred
-// shape is `Record<string, KnownModelRef>` where every access is `T | undefined`.
-// The runtime guarantee (the `refine` above) is that `default` is present, so
-// we narrow the type here. Every consumer (auth.ts, agent/index.ts,
-// resolveProfile) reads `models.default` on the hot path; without this
-// narrowing they all have to assert or `?? throw`, which is noise around an
-// invariant the schema already enforces.
-export type Models = Record<string, KnownModelRef> & { default: KnownModelRef }
+// Zod's `z.record(..., refine)` doesn't refine the inferred type. The
+// `default` key is schema-enforced, so we narrow it here to spare every
+// consumer the `T | undefined` assertion noise.
+export type Models = Record<string, KnownModelRef[]> & { default: KnownModelRef[] }
 
 export const configSchema = z
   .object({
@@ -311,8 +342,10 @@ export const configSchema = z
     port: z.number().int().min(1).max(65535).default(DEFAULT_PORT),
     // `default(() => ...)` ensures every parsed config has at least
     // `models.default`. Direct `.default({ default: ... })` would short-circuit
-    // the refinement, so we lean on the lazy thunk form.
-    models: modelsSchema.default(() => ({ default: DEFAULT_MODEL_REF })) as unknown as z.ZodType<Models>,
+    // the refinement, so we lean on the lazy thunk form. The default value is
+    // shaped to match the post-transform output (always `KnownModelRef[]`),
+    // not the user-facing input shape.
+    models: modelsSchema.default(() => ({ default: [DEFAULT_MODEL_REF] })) as unknown as z.ZodType<Models>,
     // Defaults to `[]` so the field can be omitted from `typeclaw.json` (no
     // host paths exposed) without failing the whole config load. `typeclaw
     // init` omits this field so users don't see noise for the empty case.
@@ -345,26 +378,28 @@ export function resolveModel(ref: KnownModelRef): Model<'openai-completions'> |
   return KNOWN_PROVIDERS[providerId].models[modelId as never]
 }
 
-// Resolves a profile name (e.g. `fast`, `deep`, `vision`) to a concrete model
-// ref. Unknown profiles fall back to `default` so callers can pass through
+// Resolves a profile name (e.g. `fast`, `deep`, `vision`) to its fallback
+// chain. Unknown profiles fall back to `default` so callers can pass through
 // arbitrary subagent-declared or user-overridden strings without crashing.
-// Returns the resolved ref plus whether it came from the requested profile or
-// from the `default` fallback, so the caller can warn once per session
-// instead of every prompt.
+// `refs` is non-empty (the schema guarantees `default` exists and every value
+// is at least one ref). `ref` is the head of the chain — the model the
+// session is created with first. Callers that don't implement fallback can
+// keep reading `ref`; fallback-aware callers iterate `refs`.
 export type ResolvedProfile = {
   ref: KnownModelRef
+  refs: KnownModelRef[]
   profile: string
   fellBackToDefault: boolean
 }
 
 export function resolveProfile(models: Models, name: string | undefined): ResolvedProfile {
   const requested = name ?? 'default'
-  const ref = models[requested]
-  if (ref !== undefined) {
-    return { ref, profile: requested, fellBackToDefault: false }
+  const refs = models[requested]
+  if (refs !== undefined) {
+    return { ref: refs[0]!, refs, profile: requested, fellBackToDefault: false }
   }
   const fallback = models.default
-  return { ref: fallback, profile: 'default', fellBackToDefault: true }
+  return { ref: fallback[0]!, refs: fallback, profile: 'default', fellBackToDefault: true }
 }
 
 // Resolves a mount's `path` field to an absolute host path, mirroring shell

package/src/config/models-mutation.ts

@@ -17,8 +17,16 @@ const CONFIG_FILE = 'typeclaw.json'
 
 export type ModelProfileEntry = {
   profile: string
+  // Head of the fallback chain. Kept under the legacy `ref` name so callers
+  // that only care about the active model (the common case) don't need to
+  // dereference `refs[0]`. The chain itself is exposed as `refs`.
   ref: KnownModelRef
+  refs: KnownModelRef[]
   providerId: KnownProviderId
+  // Credential status for every provider referenced by the chain. The chain's
+  // overall status is `available` only when every entry resolves; otherwise
+  // it is `missing-credentials`, and `missingProviders` names which.
+  missingProviders: KnownProviderId[]
   isDefault: boolean
   credentialStatus: 'available' | 'missing-credentials'
 }
@@ -28,14 +36,18 @@ export type ModelMutationResult = { ok: true } | { ok: false; reason: string }
 export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.env): ModelProfileEntry[] {
   const models = loadConfigSync(cwd).models
   const out: ModelProfileEntry[] = []
-  for (const [profile, ref] of Object.entries(models)) {
-    const providerId = providerForModelRef(ref)
+  for (const [profile, refs] of Object.entries(models)) {
+    const headRef = refs[0]!
+    const providerId = providerForModelRef(headRef)
+    const missingProviders = uniqueProviders(refs).filter((p) => !hasUsableCredential(cwd, p, env))
     out.push({
       profile,
-      ref,
+      ref: headRef,
+      refs,
       providerId,
+      missingProviders,
       isDefault: profile === 'default',
-      credentialStatus: hasUsableCredential(cwd, providerId, env) ? 'available' : 'missing-credentials',
+      credentialStatus: missingProviders.length === 0 ? 'available' : 'missing-credentials',
     })
   }
   // `default` always first; remaining profiles alphabetical so output is stable.
@@ -47,6 +59,19 @@ export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.
   return out
 }
 
+function uniqueProviders(refs: ReadonlyArray<KnownModelRef>): KnownProviderId[] {
+  const seen = new Set<KnownProviderId>()
+  const out: KnownProviderId[] = []
+  for (const r of refs) {
+    const p = providerForModelRef(r)
+    if (!seen.has(p)) {
+      seen.add(p)
+      out.push(p)
+    }
+  }
+  return out
+}
+
 export function listAvailableModelRefs(): KnownModelRef[] {
   return listKnownModelRefs()
 }
@@ -158,14 +183,18 @@ export function removeProfile(cwd: string, profile: string): ModelMutationResult
 
 function writeProfile(cwd: string, profile: string, ref: KnownModelRef, message: string): ModelMutationResult {
   const existing = readModelsRaw(cwd)
-  const next = existing === null ? { default: ref } : { ...existing, [profile]: ref }
+  const next: Record<string, string | string[]> = existing === null ? { default: ref } : { ...existing, [profile]: ref }
   if (existing === null && profile !== 'default') {
     next.default = ref
   }
   return writeModels(cwd, next, message)
 }
 
-function writeModels(cwd: string, models: Record<string, string>, commitMessage: string): ModelMutationResult {
+function writeModels(
+  cwd: string,
+  models: Record<string, string | string[]>,
+  commitMessage: string,
+): ModelMutationResult {
   const path = join(cwd, CONFIG_FILE)
   let parsed: Record<string, unknown>
   try {
@@ -207,10 +236,15 @@ function writeModels(cwd: string, models: Record<string, string>, commitMessage:
   return { ok: true }
 }
 
-function readModelsRaw(cwd: string): Record<string, string> | null {
+// Returns the raw `models` block from disk in its on-disk shape: each value
+// is `string | string[]` (the user-facing schema). Writers preserve whichever
+// shape was already present for profiles they don't touch — converting a
+// hand-authored fallback chain back to a single string would silently drop
+// the fallback.
+function readModelsRaw(cwd: string): Record<string, string | string[]> | null {
   try {
     const raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
-    const parsed = JSON.parse(raw) as { models?: Record<string, string> }
+    const parsed = JSON.parse(raw) as { models?: Record<string, string | string[]> }
     return parsed.models ?? null
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null