@semanticist14/clco 0.1.0

package/src/setup.ts

@@ -0,0 +1,218 @@
+// One-time startup preferences, so the flags you always pass don't have to be
+// typed every run. Asked once on the first interactive launch, changed later
+// with `clco setup`, and overridable per run with the --no-* flags.
+
+import * as p from "@clack/prompts"
+import {
+  TOKEN_ENV,
+  browserMcpConfig,
+  extensionInstalled,
+  parseToken,
+  setupNote,
+} from "./browsermcp"
+import { loadPrefs, savePrefs, type SetupPrefs } from "./config"
+
+/** Bump when an option is added, so existing users get told once. */
+export const SETUP_VERSION = 2
+
+export interface SetupOverrides {
+  bypass?: boolean
+  select?: boolean
+  browser?: boolean
+}
+
+// What the first-run prompts come pre-filled with: these are the options
+// people install clco for, so Enter-through should land on the useful setup.
+// A future option added to an EXISTING setup is absent from the stored
+// object, i.e. off, which is the conservative direction for a change nobody
+// asked for.
+export const SETUP_DEFAULTS: Omit<SetupPrefs, "version"> = {
+  bypass: true,
+  select: true,
+  browser: true,
+}
+
+export async function runSetup(): Promise<SetupPrefs> {
+  const prefs = await loadPrefs()
+  const current = prefs.setup ?? { ...SETUP_DEFAULTS, version: SETUP_VERSION }
+
+  p.intro("clco setup - save the flags you would otherwise type every run")
+  const ask = async (message: string, initialValue: boolean): Promise<boolean> => {
+    const answer = await p.confirm({ message, initialValue })
+    if (p.isCancel(answer)) {
+      p.cancel("Cancelled - keeping the previous settings")
+      process.exit(0)
+    }
+    return answer as boolean
+  }
+
+  // Sequential rather than one object literal: the browser follow-ups have to
+  // run between the browser answer and the next question, and inside a literal
+  // every property is evaluated before any code after it.
+  const setup: SetupPrefs = {
+    ...SETUP_DEFAULTS,
+    version: SETUP_VERSION,
+    // Carried regardless of the answers below: turning browser control off for
+    // a while should not make the user paste the token again afterwards.
+    browserToken: current.browserToken,
+  }
+
+  setup.bypass = await ask(
+    "Run without permission prompts? (--dangerously-skip-permissions)",
+    current.bypass,
+  )
+
+  // Claude's own Chrome integration cannot work here, so there is nothing to
+  // ask about it - only an alternative to offer.
+  setup.browser = await ask(
+    "Claude Chrome is not available in clco.\n" +
+      "  Enable Playwright MCP for browser control instead?",
+    current.browser ?? true,
+  )
+  if (setup.browser) {
+    p.note(setupNote(await extensionInstalled()), "Playwright MCP")
+    const token = await p.text({
+      message:
+        `${TOKEN_ENV} (optional) - skips the connect dialog every session.\n` +
+        "  Paste the whole line from the extension, or just the value.\n" +
+        "  Enter to skip, or set it later with: clco token",
+      placeholder: "leave empty to skip",
+      defaultValue: current.browserToken ?? "",
+      // Rejecting here beats storing a stray paste that would never work.
+      validate: (value) =>
+        parseToken(value ?? "") === null
+          ? "That does not look like the token - it is a long string of letters, digits, - and _."
+          : undefined,
+    })
+    if (!p.isCancel(token)) {
+      const parsed = parseToken(String(token))
+      if (parsed) setup.browserToken = parsed
+    }
+  }
+
+  setup.select = await ask(
+    "Pick a model each time clco starts?",
+    current.select,
+  )
+
+  await savePrefs({ ...prefs, setup })
+  p.outro(
+    "Saved. Re-run `clco setup` to change it, or turn one off for a single\n" +
+      "run with --no-bypass / --no-select / --no-browser.",
+  )
+  return setup
+}
+
+/**
+ * The saved setup, or null when it has never been run. Also reports a version
+ * bump once: a new option defaults to off, and saying so beats leaving it
+ * undiscovered — but nagging on every launch afterwards does not.
+ */
+export async function loadSetup(): Promise<SetupPrefs | null> {
+  const prefs = await loadPrefs()
+  if (!prefs.setup) return null
+  if (prefs.setup.version < SETUP_VERSION) {
+    console.error(
+      "[clco] New setup options are available (off by default) - run `clco setup` to enable them",
+    )
+    // Record that the notice was shown; the options themselves stay off.
+    await savePrefs({
+      ...prefs,
+      setup: { ...prefs.setup, version: SETUP_VERSION },
+    }).catch(() => {})
+  }
+  return prefs.setup
+}
+
+/**
+ * Claude flags implied by the saved setup, minus anything the user already
+ * passed by hand or turned off for this run. Passing a flag twice is not
+ * harmless for every claude flag, so each is added only when absent.
+ */
+export function setupClaudeArgs(
+  setup: SetupPrefs | null,
+  overrides: SetupOverrides,
+  claudeArgs: string[],
+  /** Whether the Playwright MCP Bridge extension is installed. */
+  browserExtension = false,
+): string[] {
+  if (!setup) return []
+  // Match the `--flag=value` form too: an exact comparison let a user's own
+  // --mcp-config=x.json through, and clco then injected a second one.
+  const has = (flag: string) =>
+    claudeArgs.some((a) => a === flag || a.startsWith(`${flag}=`))
+  const out: string[] = []
+  if (
+    setup.bypass &&
+    overrides.bypass !== false &&
+    !has("--dangerously-skip-permissions") &&
+    // An explicit permission mode is a deliberate choice; do not override it.
+    !has("--permission-mode")
+  ) {
+    out.push("--dangerously-skip-permissions")
+  }
+  // Registered per session rather than written into the user's MCP config, so
+  // clco never edits configuration that outlives it.
+  if (
+    setup.browser &&
+    overrides.browser !== false &&
+    !has("--mcp-config")
+  ) {
+    const config = browserMcpConfig(browserExtension)
+    if (config) out.push("--mcp-config", config)
+  }
+  return out
+}
+
+/**
+ * Environment the saved setup implies for the claude child.
+ *
+ * The extension token travels here rather than in the --mcp-config payload:
+ * that payload is an argv element, and argv is readable by other local users.
+ * MCP servers inherit claude's environment, so this route reaches the same
+ * place without publishing it.
+ */
+export function setupEnv(
+  setup: SetupPrefs | null,
+  overrides: SetupOverrides,
+): Record<string, string> {
+  if (!setup?.browserToken || overrides.browser === false) return {}
+  // An exported value wins: it is the more immediate intent.
+  if (process.env[TOKEN_ENV]) return {}
+  return { [TOKEN_ENV]: setup.browserToken }
+}
+
+/**
+ * Which model a session runs when the startup prompt is skipped, or undefined
+ * to pass no --model and leave claude on its own default.
+ *
+ * Turning the prompt off means "stop asking me", not "forget what I picked", so
+ * the remembered choice is reused. An explicit `clco --model X` still wins: it
+ * reaches claude through claudeArgs and runClaude stands aside when it sees one.
+ *
+ * Both candidates are checked against what the account actually serves. The
+ * fallback needs it as much as the remembered pick does: discoverModels caches
+ * the model list BEFORE deciding it found no claude-sonnet slug, so a plan
+ * without Claude models yields a non-empty list and a sonnet slot that is only
+ * a default guess. Asserting that as --model would fail a session that used to
+ * work by passing nothing at all.
+ */
+export function modelWithoutPrompt(
+  remembered: string | undefined,
+  /** Slugs the account currently offers, as the picker would list them. */
+  offered: ReadonlyArray<string>,
+  fallback: string,
+): string | undefined {
+  if (remembered && offered.includes(remembered)) return remembered
+  return offered.includes(fallback) ? fallback : undefined
+}
+
+/** Whether to show the startup model picker for this run. */
+export function shouldSelectModel(
+  setup: SetupPrefs | null,
+  overrides: SetupOverrides,
+): boolean {
+  if (overrides.select === false) return false
+  // Before setup runs, keep the long-standing behaviour of asking.
+  return setup === null ? true : setup.select
+}

package/src/spawn.ts

@@ -0,0 +1,453 @@
+// Launch the stock claude CLI pointed at the local adapter. Endpoint and
+// model overrides are injected via `claude --settings '<json>'`, which ranks
+// above user/project settings (so an existing ~/.claude/settings.json env
+// block cannot swallow it) without touching any config file. The same env is
+// also merged into the child process environment.
+
+import { readFile, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import {
+  advertisedId,
+  familyOf,
+  loadCatalog,
+  resolveBehavesAs,
+} from "./catalog"
+import {
+  modelInfo,
+  upstreamModels,
+  type ModelMapping,
+  type UpstreamModel,
+} from "./token"
+import { prepareClaudeHome } from "./claudehome"
+import { normalizeModel } from "./translate"
+import { ONE_MILLION_TOKENS, fallbackInputWindow } from "./tokens"
+
+/** Endpoints a model must serve to hold a conversation at all. */
+const CHAT_ENDPOINTS = ["/v1/messages", "/responses", "/chat/completions"]
+
+// Copilot plumbing that answers like a model but is not one to pick: these
+// declare a role as their capability family ("search-agent") where a real
+// model declares its own name ("gpt-4o"). Hidden by default; CLCO_SHOW_INTERNAL
+// brings them back, which matters on plans where little else is available.
+const INTERNAL_FAMILIES = new Set([
+  "search-agent",
+  "exec-agent",
+  "trajectory-compaction",
+])
+const CLAUDE_COMPACT_FLOOR = 100_000
+
+export function windowOf(m: UpstreamModel): number | undefined {
+  return m.maxPromptTokens ?? m.maxContextTokens
+}
+
+/** Reject a known custom model that Claude's global compact setting cannot represent. */
+export function validateModelSelection(
+  selected: string | undefined,
+  list: UpstreamModel[],
+): void {
+  if (!selected) return
+  const normalized = normalizeModel(selected)
+  const model = list.find(
+    (candidate) =>
+      normalizeModel(candidate.id) === normalized ||
+      advertisedId(candidate.id) === normalized,
+  )
+  if (!model || advertisedId(model.id)) return
+  const window = windowOf(model)
+  if (window !== undefined && window < CLAUDE_COMPACT_FLOOR) {
+    throw new Error(
+      `model ${selected} has a ${Math.round(window / 1000)}k context window, below Claude Code's 100k compact floor; choose another model`,
+    )
+  }
+}
+
+function smallestWindow(windows: Array<number | undefined>): number {
+  const fallback = fallbackInputWindow([])
+  const safe = windows.map((n) =>
+    n !== undefined && Number.isFinite(n) && n > 0 ? n : fallback,
+  )
+  return safe.length > 0 ? Math.min(...safe) : fallback
+}
+
+export function buildSettingsEnv(
+  baseUrl: string,
+  models: ModelMapping,
+  defaultModel?: string,
+  /** Defaults to the discovery cache; injected directly in tests. */
+  modelMeta?: UpstreamModel | null,
+): Record<string, string> {
+  const selected = defaultModel
+  // The selection may be an advertised catalog-form id; the discovery cache
+  // is keyed by upstream slug, so resolve before looking it up.
+  const info =
+    modelMeta === undefined ? (selected ? modelInfo(normalizeModel(selected)) : undefined) : modelMeta
+  // Claude models are served through Copilot's native Anthropic endpoint, so
+  // the adapter forwards thinking blocks untouched; only the translation
+  // dialects need them suppressed.
+  const native = info?.endpoints.includes("/v1/messages") === true
+  const compactWindow = modelMeta === undefined
+    ? compactWindowFor(upstreamModels())
+    : modelMeta === null
+      ? fallbackInputWindow([])
+      : advertisedId(modelMeta.id)
+        ? undefined
+        : Math.max(100_000, smallestWindow([windowOf(modelMeta)]))
+  return {
+    ANTHROPIC_BASE_URL: baseUrl,
+    ANTHROPIC_AUTH_TOKEN: "clco-local",
+    // ANTHROPIC_MODEL is deliberately NOT set: it pins the session model, so
+    // claude reports "ANTHROPIC_MODEL is set to X — new sessions use that
+    // while it is set" and every /model switch becomes cosmetic. The startup
+    // choice travels as `--model` instead, which /model can override.
+    ANTHROPIC_DEFAULT_OPUS_MODEL: models.opus,
+    ANTHROPIC_DEFAULT_SONNET_MODEL: models.sonnet,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: models.haiku,
+    ANTHROPIC_DEFAULT_FABLE_MODEL: models.fable,
+    // Gateway discovery is deliberately NOT enabled: Claude Code keeps only
+    // ids matching /claude|anthropic/i, so it would add nothing the picker
+    // lineup does not already carry — while writing a stale adapter port
+    // into the user's own ~/.claude/cache/gateway-models.json.
+    // Keep traffic contained: no auto-update, telemetry, or side calls.
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+    DISABLE_TELEMETRY: "1",
+    DISABLE_AUTOUPDATER: "1",
+    DISABLE_NON_ESSENTIAL_MODEL_CALLS: "1",
+    // Translation dialects drop thinking blocks; the native one keeps them.
+    ...(native ? {} : { CLAUDE_CODE_DISABLE_THINKING: "1" }),
+    // Catalog-known rows let Claude Code recalculate the effective window
+    // when /model switches. Non-catalog rows borrow Claude handling and need
+    // a conservative ceiling because Claude cannot know their real limit.
+    CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT: "1",
+    ...(compactWindow === undefined
+      ? {}
+      : { CLAUDE_CODE_AUTO_COMPACT_WINDOW: String(compactWindow) }),
+    // Slow upstream: never abort a stream for idling.
+    API_FORCE_IDLE_TIMEOUT: "0",
+    API_TIMEOUT_MS: "3000000",
+  }
+}
+
+let resolvedClaude: string | null = null
+
+// Resolve and verify the claude binary. Called before the adapter binds a
+// port so a missing binary fails fast with an actionable message.
+export async function resolveClaude(): Promise<string> {
+  if (resolvedClaude) return resolvedClaude
+  const candidate = Bun.which("claude") ?? `${homedir()}/.local/bin/claude`
+  if (!(await Bun.file(candidate).exists())) {
+    throw new Error(
+      `claude executable not found: ${candidate} (check PATH or ~/.local/bin)`,
+    )
+  }
+  resolvedClaude = candidate
+  // Read the model catalog out of the binary we are about to launch, so the
+  // picker tracks the installed version rather than whatever was current when
+  // clco shipped. Cached per binary; a failure keeps the built-in fallback.
+  await loadCatalog(candidate)
+  return candidate
+}
+
+// One process-level SIGTERM handler tracking the current child — registering
+// per runClaude call would stack handlers whose stale closures can kill a
+// newer run.
+let currentChild: Bun.Subprocess<"inherit", "inherit", "inherit"> | null = null
+let escalateTimer: ReturnType<typeof setTimeout> | undefined
+function shutdown(signal: NodeJS.Signals, code: number): void {
+  if (!currentChild) process.exit(code) // serve mode: no child to forward to
+  try {
+    currentChild.kill(signal)
+  } catch {
+    // already exited
+  }
+  escalateTimer ??= setTimeout(() => {
+    try {
+      currentChild?.kill("SIGKILL")
+    } catch {
+      // already exited
+    }
+    process.exit(code)
+  }, 5000)
+}
+
+process.on("SIGTERM", () => shutdown("SIGTERM", 143))
+process.on("SIGHUP", () => shutdown("SIGHUP", 129))
+process.on("SIGINT", () => shutdown("SIGINT", 130))
+
+// Claude Code's /model lineup. The picker row shape is the one the binary
+// validates against: { model, label?, description?, behavesAs? }, plus a
+// sibling `replaceBuiltInOptions`. Rows are validated individually — a row
+// the binary rejects is dropped with a warning while the rest still apply,
+// so depending on `behavesAs` degrades gracefully if the schema changes.
+interface PickerOption {
+  model: string
+  label?: string
+  description?: string
+  behavesAs?: string
+}
+
+interface ModelPicker {
+  options: PickerOption[]
+  replaceBuiltInOptions: true
+}
+
+function routeOf(m: UpstreamModel): string {
+  if (m.endpoints.includes("/v1/messages")) return "native"
+  if (m.endpoints.includes("/responses")) return "responses"
+  return "chat"
+}
+
+// Copilot's `model_picker_enabled` is VS Code UI metadata, not an
+// entitlement — GitHub currently returns false for every model, which is why
+// filtering on it emptied the lineup entirely. Filter on declared capability
+// instead: `capabilities.type` is "chat" for everything you can hold a turn
+// with, which drops embeddings and nothing else. Older entries omit both that
+// and `supported_endpoints`; Copilot serves those over /chat/completions, and
+// so does the adapter, so absent metadata must not exclude them.
+function conversational(m: UpstreamModel): boolean {
+  if (
+    m.family &&
+    INTERNAL_FAMILIES.has(m.family) &&
+    !process.env.CLCO_SHOW_INTERNAL
+  ) {
+    return false
+  }
+  if (m.type) return m.type === "chat"
+  if (m.endpoints.length === 0) return true
+  return m.endpoints.some((e) => CHAT_ENDPOINTS.includes(e))
+}
+
+export function buildModelPickerFrom(
+  list: UpstreamModel[],
+  opts?: { selected?: string; sessionWindow?: number },
+): ModelPicker | null {
+  const floor = Number(process.env.CLCO_MIN_WINDOW ?? "0")
+  const usable = list.filter(
+    (m) => conversational(m) && (windowOf(m) ?? 0) >= floor,
+  )
+  const ids = list.map((m) => m.id)
+  const selected = opts?.selected ? normalizeModel(opts.selected) : undefined
+
+  const options: PickerOption[] = []
+  for (const m of usable) {
+    const advertised = advertisedId(m.id)
+    // A row whose id Claude Code cannot resolve is silently not offered
+    // unless it carries `behavesAs`, so every non-catalog row borrows one.
+    const borrowed = advertised ? null : resolveBehavesAs(familyOf(m.id), ids)
+
+    const ctx = windowOf(m)
+    // Claude Code's global auto-compact override cannot represent a window
+    // below 100k. Do not expose a custom row whose known limit is smaller;
+    // catalog-known rows remain safe because Claude owns their per-model
+    // context handling.
+    if (borrowed && ctx !== undefined && ctx < 100_000) continue
+    // [1m] is the only per-row window channel the schema has, and it is
+    // binary: 200k or 1M, nothing between. The real window goes in the
+    // description instead.
+    const suffix = (ctx ?? 0) >= ONE_MILLION_TOKENS ? "[1m]" : ""
+    // Several slugs share one display name (five are "GPT-4o", two are
+    // "GPT-5.6 Luna"), so the subtitle leads with the id: it tells the rows
+    // apart without cluttering every title with a parenthetical.
+    const parts = [m.id, routeOf(m)]
+    if (ctx) parts.push(`${Math.round(ctx / 1000)}k`)
+    // Claude offers effort tiers to any row with behavesAs; say so where the
+    // upstream model will just ignore them.
+    if (!m.efforts) parts.push("no effort tiers")
+    // Only the shrinking direction is a hazard: the session's auto-compact
+    // budget is fixed at launch, so a smaller model can sail past its real
+    // limit. A larger one merely leaves headroom unused. Warning on both
+    // would mark nearly every row and stop meaning anything.
+    if (ctx && opts?.sessionWindow && ctx < opts.sessionWindow) {
+      parts.push(`! caps at ${Math.round(ctx / 1000)}k`)
+    }
+    options.push({
+      model: (advertised ?? m.id) + suffix,
+      ...(m.name && m.name !== m.id ? { label: m.name } : {}),
+      description: parts.join(" · "),
+      ...(borrowed ? { behavesAs: borrowed } : {}),
+    })
+  }
+
+  if (options.length === 0) return null
+  options.sort((a, b) => rank(a, list, selected) - rank(b, list, selected))
+  // Only ever set with a non-empty lineup: replacing the built-in options
+  // while offering none of our own leaves /model completely empty.
+  return { options: options.slice(0, 200), replaceBuiltInOptions: true }
+}
+
+/**
+ * A global compact ceiling is needed only when the exact selectable lineup
+ * contains a custom row. Catalog-known rows are handled by Claude Code's own
+ * per-model context table after a /model switch.
+ */
+export function compactWindowFor(list: UpstreamModel[]): number | undefined {
+  if (list.length === 0) return fallbackInputWindow([])
+  const picker = buildModelPickerFrom(list)
+  if (!picker) return fallbackInputWindow([])
+  if (!picker.options.some((option) => option.behavesAs)) {
+    return undefined
+  }
+  const byId = new Map(list.map((model) => [normalizeModel(model.id), model]))
+  const windows = picker.options.map((option) => {
+    const model = byId.get(normalizeModel(option.model))
+    return model ? windowOf(model) : undefined
+  })
+  return Math.max(100_000, smallestWindow(windows))
+}
+
+// Selected model first, then native rows, then widest window first.
+function rank(
+  o: PickerOption,
+  list: UpstreamModel[],
+  selected?: string,
+): number {
+  const id = normalizeModel(o.model)
+  if (selected && id === selected) return -1_000_000
+  const m = list.find((u) => u.id === id)
+  if (!m) return 0
+  return (routeOf(m) === "native" ? -100_000 : 0) - (windowOf(m) ?? 0) / 1000
+}
+
+function buildModelPicker(selected?: string, sessionWindow?: number) {
+  return buildModelPickerFrom(upstreamModels(), { selected, sessionWindow })
+}
+
+// The documented channel for "this provider id is really that model": a map
+// from the id clco advertises to the slug the upstream wants. Where it is
+// honoured the adapter receives the upstream slug directly; where it is not,
+// translate.ts's alias table catches the same case. They compose.
+export function buildModelOverridesFrom(
+  list: UpstreamModel[],
+): Record<string, string> | null {
+  const out: Record<string, string> = {}
+  for (const m of list) {
+    const advertised = advertisedId(m.id)
+    if (advertised && advertised !== m.id) out[advertised] = m.id
+  }
+  return Object.keys(out).length > 0 ? out : null
+}
+
+/** What the launch needs, minus anything that touches the filesystem. */
+export interface LaunchPlan {
+  baseUrl: string
+  models: ModelMapping
+  defaultModel?: string
+  claudeArgs: string[]
+  /** The private CLAUDE_CONFIG_DIR, or null when clco could not build one. */
+  configDir?: string | null
+}
+
+/**
+ * The argv clco hands claude, as a pure function.
+ *
+ * Extracted from runClaude so the settings blob can be asserted without
+ * spawning a process: the model-pinning bug below was invisible to tests
+ * precisely because this was tangled up with Bun.spawn.
+ */
+export function buildLaunchArgs(plan: LaunchPlan): string[] {
+  const userPickedModel = plan.claudeArgs.some(
+    (a) => a === "--model" || a.startsWith("--model="),
+  )
+  const userModelIndex = plan.claudeArgs.findIndex(
+    (a) => a === "--model" || a.startsWith("--model="),
+  )
+  const userModel = userModelIndex < 0
+    ? undefined
+    : plan.claudeArgs[userModelIndex]!.startsWith("--model=")
+      ? plan.claudeArgs[userModelIndex]!.slice("--model=".length)
+      : plan.claudeArgs[userModelIndex + 1]
+  validateModelSelection(userModel ?? plan.defaultModel, upstreamModels())
+  const env = buildSettingsEnv(plan.baseUrl, plan.models, plan.defaultModel)
+  const picker = buildModelPicker(plan.defaultModel ?? plan.models.sonnet)
+  const overrides = buildModelOverridesFrom(upstreamModels())
+  const configDir = plan.configDir ?? undefined
+  // The model rides in the settings blob as well as in --model, because
+  // CLAUDE_CONFIG_DIR only moves the USER settings file. Claude Code also
+  // reads a PROJECT settings file at ./.claude/settings.json, which the
+  // private config dir does not touch - and when the working directory is the
+  // home directory those are the same file, so the user's real
+  // ~/.claude/settings.json comes back in through the project tier and its
+  // `model` key pins the session. Observed: clco printed
+  // "+ model: gpt-4.1-2025-04-14" while /model reported ".claude/settings.json
+  // pins Claude Fable 5.1". The binary's own settings docs say projectSettings
+  // and localSettings are repo-controllable and only policy/user/flag settings
+  // outrank them, so the --settings tier is the one that wins.
+  //
+  // Not written into the private settings FILE: that would persist, and a
+  // /model pick landing there for good is what the private config dir exists
+  // to prevent.
+  const settings = JSON.stringify({
+    env: { ...env, ...(configDir ? { CLAUDE_CONFIG_DIR: configDir } : {}) },
+    ...(picker ? { modelPicker: picker } : {}),
+    ...(overrides ? { modelOverrides: overrides } : {}),
+    ...(userPickedModel || !plan.defaultModel ? {} : { model: plan.defaultModel }),
+  })
+  // Seeded rather than pinned (see buildSettingsEnv); a --model the user
+  // passed themselves always wins.
+  const modelArgs =
+    userPickedModel || !plan.defaultModel ? [] : ["--model", plan.defaultModel]
+  return ["--settings", settings, ...modelArgs, ...plan.claudeArgs]
+}
+
+/** The child environment, kept next to the argv it belongs with. */
+export function buildLaunchEnv(
+  plan: LaunchPlan,
+  extraEnv?: Record<string, string>,
+): Record<string, string | undefined> {
+  const userModelIndex = plan.claudeArgs.findIndex(
+    (a) => a === "--model" || a.startsWith("--model="),
+  )
+  const userModel = userModelIndex < 0
+    ? undefined
+    : plan.claudeArgs[userModelIndex]!.startsWith("--model=")
+      ? plan.claudeArgs[userModelIndex]!.slice("--model=".length)
+      : plan.claudeArgs[userModelIndex + 1]
+  validateModelSelection(userModel ?? plan.defaultModel, upstreamModels())
+  const env = buildSettingsEnv(plan.baseUrl, plan.models, plan.defaultModel)
+  const configDir = plan.configDir ?? undefined
+  const childEnv: Record<string, string | undefined> = {
+    ...process.env,
+    ...env,
+    ...extraEnv,
+    ...(configDir ? { CLAUDE_CONFIG_DIR: configDir } : {}),
+  }
+  // Never let a parent-exported key override the adapter routing.
+  delete childEnv.ANTHROPIC_API_KEY
+  return childEnv
+}
+
+export async function runClaude(opts: {
+  baseUrl: string
+  models: ModelMapping
+  defaultModel?: string
+  claudeArgs: string[]
+  /** Extra environment the saved setup implies (see setupEnv). */
+  extraEnv?: Record<string, string>
+}): Promise<number> {
+  const claude = await resolveClaude()
+  // Claude persists a /model pick into its config dir. Give it a private one
+  // so that write can never reach the user's ~/.claude.
+  const configDir = await prepareClaudeHome()
+  const plan: LaunchPlan = { ...opts, configDir }
+  const launchArgs = buildLaunchArgs(plan)
+  const childEnv = buildLaunchEnv(plan, opts.extraEnv)
+
+  const proc = Bun.spawn(
+    [claude, ...launchArgs],
+    {
+      stdio: ["inherit", "inherit", "inherit"],
+      env: childEnv,
+    },
+  )
+  currentChild = proc
+
+  const code = await proc.exited
+  if (currentChild === proc) {
+    currentChild = null
+    if (escalateTimer) {
+      clearTimeout(escalateTimer)
+      escalateTimer = undefined
+    }
+  }
+  return code ?? 0
+}