typeclaw 0.36.8 → 0.37.1

package/src/cli/init.ts

@@ -1,11 +1,24 @@
 import { randomBytes } from 'node:crypto'
 
-import { cancel, confirm, intro, isCancel, log, note, password, select, spinner, text } from '@clack/prompts'
+import {
+  autocomplete,
+  cancel,
+  confirm,
+  intro,
+  isCancel,
+  log,
+  note,
+  password,
+  select,
+  spinner,
+  text,
+} from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import {
   KNOWN_PROVIDER_VENDORS,
   KNOWN_PROVIDERS,
+  isKnownModelRef,
   listKnownProviderVendorIds,
   providerIdsForVendor,
   supportsApiKey as providerSupportsApiKey,
@@ -35,9 +48,17 @@ import {
   type KakaotalkAuthResult,
   type LLMAuth,
 } from '@/init'
+import {
+  checkpointFromSelections,
+  createLocalWizardCheckpointStore,
+  sanitizeCheckpointAgainstCatalog,
+  type WizardAnswerCheckpointV1,
+  type WizardCheckpointStore,
+} from '@/init/checkpoint'
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
-import { fetchModelOptions, type ModelOption } from '@/init/models-dev'
+import { customModelMetaFromOption, fetchModelOptions, type ModelOption } from '@/init/models-dev'
 import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
+import { detectInitProgress } from '@/init/progress'
 import {
   API_KEY_DASHBOARD_URL,
   MINIMAX_TOKEN_PLAN_DASHBOARD_URL,
@@ -159,9 +180,10 @@ export const init = defineCommand({
     }
     preflightSpinner.stop('Docker is reachable.')
 
+    const checkpointStore = createLocalWizardCheckpointStore()
     let collected: CollectedInputs
     try {
-      collected = await collectWizardInputs(cwd, defaultWizardPrompts, { reset })
+      collected = await collectWizardInputs(cwd, defaultWizardPrompts, { reset, checkpointStore })
     } catch (error) {
       if (error instanceof WizardAbortedError) {
         if (error.oauthCredentialsSaved) {
@@ -189,6 +211,8 @@ export const init = defineCommand({
       kakaotalkPassword,
       github: githubCredentials,
     } = channelSecrets
+    const modelMeta = customModelMetaFromOption(model)
+    const visionModelMeta = vision !== undefined ? customModelMetaFromOption(vision.model) : undefined
 
     // TODO: add remaining wizard steps from TypeClaw.md once their runtime lands:
     //   - git backup (url + PAT) — Phase 10
@@ -213,7 +237,14 @@ export const init = defineCommand({
         cwd,
         llmAuth,
         model: model.ref,
-        ...(vision !== undefined ? { visionModel: vision.model.ref, visionAuth: vision.llmAuth } : {}),
+        ...(modelMeta !== undefined ? { modelMeta } : {}),
+        ...(vision !== undefined
+          ? {
+              visionModel: vision.model.ref,
+              ...(visionModelMeta !== undefined ? { visionModelMeta } : {}),
+              visionAuth: vision.llmAuth,
+            }
+          : {}),
         cliEntry: process.argv[1],
         ...(discordBotToken !== undefined ? { discordBotToken } : {}),
         ...(slackBotToken !== undefined ? { slackBotToken, slackAppToken } : {}),
@@ -271,6 +302,10 @@ export const init = defineCommand({
     }
 
     if (hatchingOk) {
+      // Clear the resume checkpoint only on full success (hatching ok). A
+      // failed install/dockerfile/git/hatching leaves it in place so the next
+      // `typeclaw init` — or `typeclaw start` (PR2) — can resume.
+      await checkpointStore.clear(cwd).catch(() => {})
       const claimableChannel =
         channelChoice !== 'none' && channelChoice !== 'github' ? channelDisplayName(channelChoice) : null
       const hints: Array<{ label: string; command: string }> = []
@@ -380,7 +415,7 @@ export interface WizardPrompts {
   pickModel: (
     options: ModelOption[],
     providerId: KnownProviderId,
-    initial: KnownModelRef | undefined,
+    initial: string | undefined,
   ) => Promise<StepResult<ModelOption>>
   pickAuthMethod: (
     provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
@@ -400,7 +435,7 @@ export interface WizardPrompts {
   pickVisionModel: (
     options: ModelOption[],
     providerId: KnownProviderId,
-    initial: KnownModelRef | undefined,
+    initial: string | undefined,
   ) => Promise<StepResult<ModelOption>>
   pickChannel: (initial: ChannelChoice | undefined) => Promise<StepResult<ChannelChoice>>
   hasExistingChannelSecrets: (cwd: string, channel: Exclude<ChannelChoice, 'none'>) => Promise<boolean>
@@ -408,17 +443,19 @@ export interface WizardPrompts {
   runOAuthLogin: (
     provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
     cwd: string,
-    model: KnownModelRef,
+    model: string,
   ) => Promise<OAuthLoginResult>
   askOAuthFailureRecovery: (
     provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
     reason: string,
     apiKeyAvailable: boolean,
   ) => Promise<OAuthFailureRecovery>
+  confirmResumeCheckpoint: (checkpoint: WizardAnswerCheckpointV1) => Promise<'resume' | 'start-over'>
 }
 
 export type CollectWizardInputsOptions = {
   reset?: boolean
+  checkpointStore?: WizardCheckpointStore
 }
 
 export type OAuthFailureRecovery = 'retry' | 'api-key' | 'abort'
@@ -448,6 +485,7 @@ export const defaultWizardPrompts: WizardPrompts = {
     }
   },
   askOAuthFailureRecovery,
+  confirmResumeCheckpoint,
 }
 
 export async function collectWizardInputs(
@@ -456,12 +494,46 @@ export async function collectWizardInputs(
   options: CollectWizardInputsOptions = {},
 ): Promise<CollectedInputs> {
   const reset = options.reset === true
+  const checkpointStore = options.checkpointStore
   const catalog = await prompts.loadCatalog()
   const state: WizardState = { catalog }
   let step: StepId = 'pick-vendor'
   let pendingBackOrigin: StepId | null = null
   let oauthCredentialsSaved = false
 
+  // Resume saved wizard answers from a prior unfinished init. `--reset` skips
+  // this entirely (the user asked to re-answer everything). Route through the
+  // shared detectInitProgress() predicate so init/start/restart classify a
+  // checkpoint identically: only an `incomplete` init (checkpoint + not
+  // hatched) offers resume; a `complete-stale-checkpoint` (checkpoint that
+  // outlived a hatched agent) is cleared and ignored, matching the contract.
+  if (!reset && checkpointStore !== undefined) {
+    const progress = await detectInitProgress({ cwd, checkpointStore })
+    if (progress.kind === 'complete-stale-checkpoint') {
+      await checkpointStore.clear(cwd).catch(() => {})
+    } else if (progress.kind === 'incomplete') {
+      // Sanitize against the freshly-loaded catalog BEFORE showing the resume
+      // prompt. `load` only validates version/cwd/updatedAt, so a checkpoint
+      // with a since-removed provider/model id reaches here intact; describing
+      // or seeding it raw would crash on `KNOWN_PROVIDERS[providerId]`. Pruning
+      // first means the prompt, the seed, and any partial answers all see only
+      // catalog-valid fields.
+      const catalogRefs = new Set(catalog.options.map((option) => option.ref))
+      const sanitized = sanitizeCheckpointAgainstCatalog(progress.checkpoint, catalogRefs)
+      const decision = await prompts.confirmResumeCheckpoint(sanitized)
+      if (decision === 'resume') {
+        seedWizardState(state, sanitized)
+      } else {
+        await checkpointStore.clear(cwd)
+      }
+    }
+  }
+
+  const persistCheckpoint = async (): Promise<void> => {
+    if (reset || checkpointStore === undefined) return
+    await checkpointStore.save(cwd, projectCheckpoint(cwd, state)).catch(() => {})
+  }
+
   const abort = (): never => {
     throw new WizardAbortedError({ oauthCredentialsSaved })
   }
@@ -492,6 +564,11 @@ export async function collectWizardInputs(
   }
 
   while (true) {
+    // Persist the cumulative selections at the top of every iteration so a
+    // mid-wizard abort keeps everything answered so far. Running it here (not
+    // per-case) means back-navigation — which clears downstream fields before
+    // looping — overwrites the projection too, so stale answers never linger.
+    await persistCheckpoint()
     switch (step) {
       case 'pick-vendor': {
         const result = onResult(step, await prompts.pickVendor(catalog.options, state.vendorId))
@@ -849,7 +926,7 @@ async function runOAuthLoginSafely(
   prompts: WizardPrompts,
   provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
   cwd: string,
-  model: KnownModelRef,
+  model: string,
 ): Promise<OAuthLoginResult> {
   try {
     return await prompts.runOAuthLogin(provider, cwd, model)
@@ -871,6 +948,72 @@ function finalize(state: WizardState, channelSecrets: CollectedInputs['channelSe
   }
 }
 
+async function confirmResumeCheckpoint(checkpoint: WizardAnswerCheckpointV1): Promise<'resume' | 'start-over'> {
+  const summary = describeCheckpoint(checkpoint)
+  const choice = await select({
+    message: 'Found answers from a previous, unfinished init. Resume from them?',
+    options: [
+      { value: 'resume' as const, label: 'Resume', hint: summary },
+      { value: 'start-over' as const, label: 'Start over', hint: 'discard saved answers and pick everything again' },
+    ],
+    initialValue: 'resume' as const,
+  })
+  if (isCancel(choice)) return 'start-over'
+  return choice
+}
+
+function describeCheckpoint(checkpoint: WizardAnswerCheckpointV1): string {
+  const parts: string[] = []
+  // Defense-in-depth: callers sanitize before describing, but a raw provider id
+  // missing from KNOWN_PROVIDERS must degrade to the id string, never throw.
+  if (checkpoint.modelRef !== undefined) parts.push(checkpoint.modelRef)
+  else if (checkpoint.providerId !== undefined) {
+    parts.push(KNOWN_PROVIDERS[checkpoint.providerId]?.name ?? checkpoint.providerId)
+  }
+  if (checkpoint.visionModelRef !== undefined) parts.push(`vision: ${checkpoint.visionModelRef}`)
+  if (checkpoint.channelChoice !== undefined && checkpoint.channelChoice !== 'none') {
+    parts.push(`channel: ${checkpoint.channelChoice}`)
+  }
+  return parts.length > 0 ? parts.join(', ') : 'partial selections'
+}
+
+// Pre-populate wizard state from a sanitized checkpoint so each prompt's
+// `initial` argument fast-forwards the user to their prior choice. Only seeds
+// fields whose upstream selections are all present and catalog-valid; the
+// sanitize pass already dropped stale refs, so a missing field here just means
+// that step prompts fresh.
+function seedWizardState(state: WizardState, checkpoint: WizardAnswerCheckpointV1): void {
+  state.vendorId = checkpoint.vendorId
+  state.providerId = checkpoint.providerId
+  state.model = resolveModelOption(state.catalog, checkpoint.modelRef)
+  state.authMethod = checkpoint.authMethod
+  state.visionVendorId = checkpoint.visionVendorId
+  state.visionProviderId = checkpoint.visionProviderId
+  state.visionModel = resolveModelOption(state.catalog, checkpoint.visionModelRef)
+  state.visionAuthMethod = checkpoint.visionAuthMethod
+  state.channelChoice = checkpoint.channelChoice
+}
+
+function resolveModelOption(catalog: WizardState['catalog'], ref: string | undefined): ModelOption | undefined {
+  if (catalog === undefined || ref === undefined) return undefined
+  return catalog.options.find((option) => option.ref === ref)
+}
+
+function projectCheckpoint(cwd: string, state: WizardState): WizardAnswerCheckpointV1 {
+  return checkpointFromSelections({
+    cwd,
+    ...(state.vendorId !== undefined ? { vendorId: state.vendorId } : {}),
+    ...(state.providerId !== undefined ? { providerId: state.providerId } : {}),
+    ...(state.model?.ref !== undefined ? { modelRef: state.model.ref } : {}),
+    ...(state.authMethod !== undefined ? { authMethod: state.authMethod } : {}),
+    ...(state.visionVendorId !== undefined ? { visionVendorId: state.visionVendorId } : {}),
+    ...(state.visionProviderId !== undefined ? { visionProviderId: state.visionProviderId } : {}),
+    ...(state.visionModel?.ref !== undefined ? { visionModelRef: state.visionModel.ref } : {}),
+    ...(state.visionAuthMethod !== undefined ? { visionAuthMethod: state.visionAuthMethod } : {}),
+    ...(state.channelChoice !== undefined ? { channelChoice: state.channelChoice } : {}),
+  })
+}
+
 function channelDisplayName(choice: Exclude<ChannelChoice, 'none'>): string {
   switch (choice) {
     case 'slack':
@@ -952,8 +1095,9 @@ async function pickVendor(
   initial: KnownProviderVendorId | undefined,
 ): Promise<StepResult<KnownProviderVendorId>> {
   const vendors = uniqueVendors(options)
-  const choice = await select({
+  const choice = await autocomplete({
     message: 'Pick an LLM provider',
+    placeholder: 'Type to search…',
     options: vendors.map((id) => ({
       value: id,
       label: KNOWN_PROVIDER_VENDORS[id].name,
@@ -973,8 +1117,9 @@ async function pickProviderVariant(
   const variants = providersForVendorInCatalog(vendorId, options)
   if (variants.length === 0) throw new Error(`Internal error: vendor ${vendorId} has no providers in the catalog`)
   if (variants.length === 1) return autoValue(variants[0]!)
-  const choice = await select<KnownProviderId>({
+  const choice = await autocomplete<KnownProviderId>({
     message: `Pick a ${KNOWN_PROVIDER_VENDORS[vendorId].name} option`,
+    placeholder: 'Type to search…',
     options: variants.map((id) => {
       const hint = variantHint(vendorId, id)
       return hint !== undefined
@@ -990,15 +1135,16 @@ async function pickProviderVariant(
 async function pickModelForProvider(
   options: ModelOption[],
   providerId: KnownProviderId,
-  initial: KnownModelRef | undefined,
+  initial: string | undefined,
 ): Promise<StepResult<ModelOption>> {
   const candidates = sortRecommendedFirst(options.filter((o) => o.providerId === providerId))
   // select<string>, not select<KnownModelRef>: clack's Option<Value> is a
   // distributive conditional type, so a large KnownModelRef union explodes into
   // a per-literal option union that no longer accepts `value: ref`. The runtime
   // value is the ref string and is re-narrowed via `candidates.find` below.
-  const choice = await select<string>({
+  const choice = await autocomplete<string>({
     message: `Pick a ${KNOWN_PROVIDERS[providerId].name} model`,
+    placeholder: 'Type to search…',
     options: candidates.map((o) => ({
       value: o.ref,
       label: formatModelLabel(o),
@@ -1042,8 +1188,9 @@ async function pickVisionVendor(
     log.warn('No vision-capable models available; skipping vision profile.')
     return autoValue('skip')
   }
-  const choice = await select<KnownProviderVendorId | 'skip'>({
+  const choice = await autocomplete<KnownProviderVendorId | 'skip'>({
     message: 'Your model is text-only. Pick a provider for the `vision` profile (used for image input)',
+    placeholder: 'Type to search…',
     options: [
       ...vendors.map((id) => ({
         value: id as KnownProviderVendorId | 'skip',
@@ -1069,12 +1216,13 @@ async function pickVisionProviderVariant(
 async function pickVisionModel(
   options: ModelOption[],
   providerId: KnownProviderId,
-  initial: KnownModelRef | undefined,
+  initial: string | undefined,
 ): Promise<StepResult<ModelOption>> {
   const candidates = sortRecommendedFirst(options.filter((o) => o.providerId === providerId))
   // select<string> for the same distributive-Option reason as pickModelForProvider.
-  const choice = await select<string>({
+  const choice = await autocomplete<string>({
     message: `Pick a vision-capable ${KNOWN_PROVIDERS[providerId].name} model`,
+    placeholder: 'Type to search…',
     options: candidates.map((o) => ({
       value: o.ref,
       label: formatModelLabel(o),
@@ -1697,12 +1845,12 @@ const RECOMMENDED_MODEL_REFS: ReadonlySet<KnownModelRef> = new Set<KnownModelRef
 ])
 
 export function formatModelLabel(o: ModelOption): string {
-  return RECOMMENDED_MODEL_REFS.has(o.ref) ? `${o.modelName} (Recommended)` : o.modelName
+  return isKnownModelRef(o.ref) && RECOMMENDED_MODEL_REFS.has(o.ref) ? `${o.modelName} (Recommended)` : o.modelName
 }
 
 export function sortRecommendedFirst(options: ModelOption[]): ModelOption[] {
-  const recommended = options.filter((o) => RECOMMENDED_MODEL_REFS.has(o.ref))
-  const rest = options.filter((o) => !RECOMMENDED_MODEL_REFS.has(o.ref))
+  const recommended = options.filter((o) => isKnownModelRef(o.ref) && RECOMMENDED_MODEL_REFS.has(o.ref))
+  const rest = options.filter((o) => !isKnownModelRef(o.ref) || !RECOMMENDED_MODEL_REFS.has(o.ref))
   return [...recommended, ...rest]
 }
 

package/src/cli/inspect.ts

@@ -3,6 +3,7 @@ import { defineCommand } from 'citty'
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
 import {
+  fetchLiveSessions,
   listViewerItems,
   openViewerItem,
   parseDuration,
@@ -150,7 +151,8 @@ export async function runInspectViewer(opts: RunInspectViewerOptions): Promise<n
 
   const interactive = Boolean(process.stdin.isTTY)
   const liveHint = interactive ? escHintLine(color) : undefined
-  const liveSource = containerRunning ? await buildLiveSource(cwd) : undefined
+  const inspectUrl = containerRunning ? await resolveInspectUrl(cwd) : undefined
+  const liveSource = inspectUrl !== undefined ? buildLiveSource(inspectUrl) : undefined
 
   const stdout = (line: string): void => {
     process.stdout.write(`${line}\n`)
@@ -186,6 +188,7 @@ export async function runInspectViewer(opts: RunInspectViewerOptions): Promise<n
         onWarn: stderr,
       }
       if (sinceMs !== undefined) listOpts.sinceMs = sinceMs
+      if (inspectUrl !== undefined) listOpts.liveSessions = await fetchLiveSessions({ url: inspectUrl })
       return (await listViewerItems(listOpts)).items
     },
     keyOf: (item) => (item.kind === 'logs' ? 'logs' : item.summary.sessionId),
@@ -223,12 +226,15 @@ async function resolveTuiUrl(cwd: string): Promise<string> {
   return url.toString()
 }
 
-async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefined> {
+async function resolveInspectUrl(cwd: string): Promise<string> {
   const port = await resolveHostPort({ cwd })
   const token = await resolveTuiToken({ cwd })
   const baseUrl = new URL(`ws://127.0.0.1:${port}/inspect`)
   if (token !== null) baseUrl.searchParams.set('token', token)
-  const url = baseUrl.toString()
+  return baseUrl.toString()
+}
+
+function buildLiveSource(url: string): LiveSourceFactory {
   return ({ sessionId, sinceMs, signal, onSubscribed }) =>
     streamLive({
       url,
@@ -325,8 +331,8 @@ function itemHint(item: ViewerItem): { hint: string } {
 function sessionRowLabel(s: SessionSummary): string {
   const id = shortSessionId(s.sessionId)
   const label = s.origin === null ? '(unknown origin)' : originLabel(s.origin)
-  const when = formatRelative(s.mtimeMs)
-  return `${c.cyan(id)}  ${label}  ${c.dim(when)}`
+  const when = s.live === true ? c.green('live · replying') : c.dim(formatRelative(s.mtimeMs))
+  return `${c.cyan(id)}  ${label}  ${when}`
 }
 
 function formatRelative(ms: number): string {

package/src/cli/model.ts

@@ -1,6 +1,7 @@
-import { cancel, intro, isCancel, log, select } from '@clack/prompts'
+import { autocomplete, cancel, intro, isCancel, log, select } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
+import type { CustomModelMeta } from '@/config'
 import {
   addProfile,
   listModelProfiles,
@@ -9,19 +10,25 @@ import {
   setProfile,
 } from '@/config/models-mutation'
 import {
+  isKnownModelRef,
   KNOWN_PROVIDERS,
-  listKnownModelRefs,
   providerForModelRef,
   type KnownModelRef,
   type KnownProviderId,
 } from '@/config/providers'
 import { findAgentDir, isInitialized } from '@/init'
+import { customModelMetaFromOption, fetchModelOptions, type ModelOption } from '@/init/models-dev'
 
 import { runProviderAddFlow } from './provider'
 import { c, done, errorLine } from './ui'
 
 const ADD_PROVIDER_SENTINEL = '__add-provider__'
 
+type PickedModelRef = {
+  ref: string
+  meta?: CustomModelMeta
+}
+
 const setSub = defineCommand({
   meta: {
     name: 'set',
@@ -47,18 +54,21 @@ const setSub = defineCommand({
   async run({ args }) {
     const cwd = ensureAgentDir()
     const profile = args.profile ?? (await pickProfileName())
-    const ref = args.ref ?? (await pickModelRef(cwd))
+    const picked = args.ref !== undefined ? await resolveExplicitRef(args.ref) : await pickModelRef(cwd)
 
-    intro(`Setting model profile: ${profile} → ${ref}`)
+    intro(`Setting model profile: ${profile} → ${picked.ref}`)
 
-    const result = setProfile(cwd, profile, ref, { force: args.force === true })
+    const result = setProfile(cwd, profile, picked.ref, {
+      force: args.force === true,
+      ...(picked.meta !== undefined ? { meta: picked.meta } : {}),
+    })
     if (!result.ok) {
       console.error(errorLine(result.reason))
       process.exit(1)
     }
     done({
       title: c.green(`Profile "${profile}" set.`),
-      details: `${profile} → ${ref}`,
+      details: `${profile} → ${picked.ref}`,
       hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
     })
   },
@@ -88,18 +98,21 @@ const addSub = defineCommand({
   },
   async run({ args }) {
     const cwd = ensureAgentDir()
-    const ref = args.ref ?? (await pickModelRef(cwd))
+    const picked = args.ref !== undefined ? await resolveExplicitRef(args.ref) : await pickModelRef(cwd)
 
-    intro(`Adding model profile: ${args.profile} → ${ref}`)
+    intro(`Adding model profile: ${args.profile} → ${picked.ref}`)
 
-    const result = addProfile(cwd, args.profile, ref, { force: args.force === true })
+    const result = addProfile(cwd, args.profile, picked.ref, {
+      force: args.force === true,
+      ...(picked.meta !== undefined ? { meta: picked.meta } : {}),
+    })
     if (!result.ok) {
       console.error(errorLine(result.reason))
       process.exit(1)
     }
     done({
       title: c.green(`Profile "${args.profile}" added.`),
-      details: `${args.profile} → ${ref}`,
+      details: `${args.profile} → ${picked.ref}`,
       hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
     })
   },
@@ -146,7 +159,7 @@ const listSub = defineCommand({
   },
   async run({ args }) {
     if (args.available === true) {
-      printAvailableRefs()
+      await printAvailableRefs()
       return
     }
     const cwd = ensureAgentDir()
@@ -218,7 +231,7 @@ async function pickProfileName(): Promise<string> {
   return choice
 }
 
-async function pickModelRef(cwd: string): Promise<string> {
+async function pickModelRef(cwd: string): Promise<PickedModelRef> {
   while (true) {
     const refs = listRegisteredModelRefs(cwd)
     if (refs.length === 0) {
@@ -234,13 +247,15 @@ async function pickModelRef(cwd: string): Promise<string> {
     // distributive conditional type and a large ref union breaks `value: ref`
     // assignability. Values are ref strings (+ the sentinel) and stay correct
     // at runtime — the sentinel check and `return choice` below are unaffected.
-    const choice = await select<string>({
+    const modelOptions = await listCredentialedModelOptions(refs)
+    const choice = await autocomplete<string>({
       message: 'Pick a model',
+      placeholder: 'Type to search…',
       options: [
-        ...refs.map((ref) => ({
-          value: ref,
-          label: describeRef(ref),
-          hint: ref,
+        ...modelOptions.map((option) => ({
+          value: option.ref,
+          label: describeRef(option.ref),
+          hint: option.ref,
         })),
         {
           value: ADD_PROVIDER_SENTINEL,
@@ -248,13 +263,18 @@ async function pickModelRef(cwd: string): Promise<string> {
           hint: 'configure a new provider',
         },
       ],
-      initialValue: refs[0],
+      initialValue: modelOptions[0]?.ref ?? refs[0],
     })
     if (isCancel(choice)) {
       cancel('Aborted.')
       process.exit(0)
     }
-    if (choice !== ADD_PROVIDER_SENTINEL) return choice
+    if (choice !== ADD_PROVIDER_SENTINEL) {
+      const option = modelOptions.find((candidate) => candidate.ref === choice)
+      if (option === undefined) return { ref: choice }
+      const meta = customModelMetaFromOption(option)
+      return { ref: option.ref, ...(meta !== undefined ? { meta } : {}) }
+    }
     const added = await runProviderAddFlow(cwd, {})
     if (!added.ok) {
       console.error(errorLine(added.reason))
@@ -263,29 +283,88 @@ async function pickModelRef(cwd: string): Promise<string> {
   }
 }
 
-function describeRef(ref: KnownModelRef): string {
-  const providerId = providerForModelRef(ref)
-  const modelId = ref.slice(providerId.length + 1)
-  const provider = KNOWN_PROVIDERS[providerId]
-  const model = (provider.models as Record<string, { name: string }>)[modelId]
-  return model ? `${provider.name} · ${model.name}` : ref
+// Non-interactive `<ref>` path. Curated refs resolve from KNOWN_PROVIDERS, so
+// they need no metadata. Non-curated refs are looked up in the live catalog so
+// `customModels[ref]` carries the same metadata the interactive picker would
+// persist; without it `resolveModel` silently falls back to defaults. A
+// catalog miss (offline / unknown id) still writes the ref, but warns first.
+export async function resolveExplicitRef(
+  ref: string,
+  loadCatalog: () => Promise<{ options: ModelOption[] }> = fetchModelOptions,
+): Promise<PickedModelRef> {
+  if (isKnownModelRef(ref)) return { ref }
+  const { options } = await loadCatalog()
+  const option = options.find((candidate) => candidate.ref === ref)
+  if (option === undefined) {
+    log.warn(
+      `"${ref}" isn't in the live catalog; saving the ref without metadata. ` +
+        `The agent will use fallback defaults (reasoning off, text-only input, zero cost, provider-default context).`,
+    )
+    return { ref }
+  }
+  const meta = customModelMetaFromOption(option)
+  return { ref, ...(meta !== undefined ? { meta } : {}) }
+}
+
+export type { PickedModelRef }
+
+async function listCredentialedModelOptions(refs: KnownModelRef[]): Promise<ModelOption[]> {
+  const credentialedProviders = new Set<KnownProviderId>(refs.map((ref) => providerForModelRef(ref)))
+  const catalog = await fetchModelOptions()
+  const options = catalog.options.filter((option) => credentialedProviders.has(option.providerId))
+  if (options.length > 0) return options
+  return refs.map((ref) => {
+    const providerId = providerForModelRef(ref)
+    const modelId = ref.slice(providerId.length + 1)
+    const model = (
+      KNOWN_PROVIDERS[providerId].models as Record<
+        string,
+        { name: string; reasoning?: boolean; contextWindow?: number; input?: ReadonlyArray<string> }
+      >
+    )[modelId]
+    return {
+      ref,
+      providerId,
+      providerName: KNOWN_PROVIDERS[providerId].name,
+      modelId,
+      modelName: model?.name ?? modelId,
+      reasoning: model?.reasoning ?? false,
+      contextWindow: model?.contextWindow ?? null,
+      curated: true,
+      supportsVision: model?.input?.includes('image') ?? false,
+    }
+  })
+}
+
+function describeRef(ref: string): string {
+  try {
+    const providerId = providerForModelRef(ref)
+    const modelId = ref.slice(providerId.length + 1)
+    const provider = KNOWN_PROVIDERS[providerId]
+    const model = (provider.models as Record<string, { name: string }>)[modelId]
+    return `${provider.name} · ${model?.name ?? modelId}`
+  } catch {
+    return ref
+  }
 }
 
-function printAvailableRefs(): void {
-  const refs = listKnownModelRefs()
-  if (refs.length === 0) {
+async function printAvailableRefs(): Promise<void> {
+  const { options, source, warning } = await fetchModelOptions()
+  if (options.length === 0) {
     console.log(c.dim('No models registered.'))
     return
   }
   console.log(c.dim('Use `typeclaw model set <profile> <ref>` to apply.'))
-  let lastProvider: KnownProviderId | null = null
-  for (const ref of refs) {
-    const providerId = providerForModelRef(ref)
-    if (providerId !== lastProvider) {
-      console.log('')
-      console.log(c.cyan(KNOWN_PROVIDERS[providerId].name))
-      lastProvider = providerId
+  if (source === 'curated' && warning !== undefined) {
+    console.log(c.dim(`Using built-in catalog (models.dev unavailable: ${warning}).`))
+  }
+  for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
+    const providerOptions = options.filter((option) => option.providerId === providerId)
+    if (providerOptions.length === 0) continue
+    console.log('')
+    console.log(c.cyan(KNOWN_PROVIDERS[providerId].name))
+    for (const option of providerOptions) {
+      console.log(`  ${option.ref}`)
     }
-    console.log(`  ${ref}`)
   }
 }