codemax-cli 0.1.3 → 0.1.5

package/src/engines/codex.ts

@@ -1,8 +1,9 @@
 import type { AgentId } from "../adapters/types.ts";
-import type { Engine, EngineEvent, EngineInfo, EngineSessionRef, EngineStartOptions, PermissionRequest, StopReason, ToolStatus } from "./types.ts";
+import type { Engine, EngineEvent, EngineInfo, EngineOption, EngineSessionRef, EngineStartOptions, PermissionRequest, StopReason, ToolStatus } from "./types.ts";
 import { agentEnv } from "./env.ts";
 import { platformArgv } from "../core/spawn.ts";
 import { classifyError } from "./errors.ts";
+import pkg from "../../package.json" with { type: "json" };
 
 export interface CodexEngineOptions {
   /** Command for the app server. Default: codex app-server. */
@@ -18,6 +19,10 @@ export interface CodexEngineOptions {
  * `answerPermission`.
  */
 export class CodexEngine implements Engine {
+  /** Models this account can use, from `model/list`. */
+  private catalog: { id: string; name: string; efforts: string[]; defaultEffort?: string }[] = [];
+  /** Reasoning effort chosen with /effort (sent with each turn); undefined = the model's default. */
+  private effort: string | undefined;
   readonly agent: AgentId = "codex";
   info: EngineInfo | null = null;
   session: EngineSessionRef | null = null;
@@ -32,7 +37,8 @@ export class CodexEngine implements Engine {
   private threadId: string | null = null;
   private cwd = "";
   private model: string | undefined;
-  private lastTotals = { inputTokens: 0, cachedInputTokens: 0, cacheWriteInputTokens: 0, outputTokens: 0 };
+  /** Cumulative token totals per thread (the main one and each spawned agent's), to emit deltas. */
+  private lastTotals = new Map<string, { inputTokens: number; cachedInputTokens: number; cacheWriteInputTokens: number; outputTokens: number }>();
 
   constructor(private opts: CodexEngineOptions = {}) {}
 
@@ -49,7 +55,7 @@ export class CodexEngine implements Engine {
     this.cwd = o.cwd;
     this.transport = this.opts.transport ?? this.spawn(o.cwd);
     this.transport.onLine((line) => this.onLine(line));
-    const init = await this.request("initialize", { clientInfo: { name: "codemax", version: "0.3.0" }, capabilities: {} });
+    const init = await this.request("initialize", { clientInfo: { name: "codemax", version: pkg.version }, capabilities: {} });
     this.notify("initialized", {});
 
     let thread: any;
@@ -65,6 +71,9 @@ export class CodexEngine implements Engine {
     this.model = thread.model ?? undefined;
     this.session = { agent: "codex", id: thread.id, cwd: o.cwd, startedAt: Date.now(), lastUsedAt: Date.now() };
     const account: any = await this.request("account/read", {}).catch(() => null);
+    // The models this account can use, straight from Codex: never a list of our own.
+    // An older Codex without model/list must not hold up startup: give it a few seconds.
+    this.catalog = await Promise.race([this.listModels(), Bun.sleep(4000).then(() => [])]).catch(() => []);
     this.info = {
       agent: "codex",
       name: "Codex",
@@ -74,8 +83,9 @@ export class CodexEngine implements Engine {
         { id: "never", name: "full auto (no approvals)" },
       ],
       currentMode: "on-request",
-      models: [...new Set([this.model, "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5"].filter(Boolean))].map((id) => ({ id: id!, name: id! })),
+      models: this.catalog.length ? this.catalog.map((m) => ({ id: m.id, name: m.name })) : this.model ? [{ id: this.model, name: this.model }] : [],
       currentModel: this.model,
+      options: this.effortOptions(),
       plan: account?.account?.planType ? `chatgpt ${account.account.planType}` : undefined,
     };
     this.emit({ type: "session", ref: this.session });
@@ -183,7 +193,63 @@ export class CodexEngine implements Engine {
     this.transport!.send(JSON.stringify({ jsonrpc: "2.0", id: m.id, error: { code: -32601, message: `codemax does not handle ${method}` } }));
   }
 
+  /**
+   * Token usage of one thread. Totals are cumulative per thread; the delta is emitted. A spawned
+   * agent's thread counts too: it runs on the same Codex plan, so /usage and budgets include it.
+   * Codex's inputTokens include cached ones.
+   */
+  private usageFrom(p: any, thread: string) {
+    const rl = p.rateLimits ?? p.tokenUsage?.rateLimits;
+    const used = rl?.primary?.usedPercent ?? rl?.primary?.used_percent;
+    const t = p.tokenUsage?.total;
+    const main = thread === (this.threadId ?? "main");
+    if (!t) {
+      if (typeof used === "number") this.emit({ type: "usage", usedPercent: used });
+      return;
+    }
+    const last = this.lastTotals.get(thread) ?? { inputTokens: 0, cachedInputTokens: 0, cacheWriteInputTokens: 0, outputTokens: 0 };
+    const d = {
+      inputTokens: Math.max(0, (t.inputTokens ?? 0) - last.inputTokens),
+      cachedInputTokens: Math.max(0, (t.cachedInputTokens ?? 0) - last.cachedInputTokens),
+      cacheWriteInputTokens: Math.max(0, (t.cacheWriteInputTokens ?? 0) - last.cacheWriteInputTokens),
+      outputTokens: Math.max(0, (t.outputTokens ?? 0) - last.outputTokens),
+    };
+    this.lastTotals.set(thread, { inputTokens: t.inputTokens ?? 0, cachedInputTokens: t.cachedInputTokens ?? 0, cacheWriteInputTokens: t.cacheWriteInputTokens ?? 0, outputTokens: t.outputTokens ?? 0 });
+    if (!d.inputTokens && !d.outputTokens) return;
+    this.emit({
+      type: "usage",
+      inputTokens: Math.max(0, d.inputTokens - d.cachedInputTokens),
+      cacheReadTokens: d.cachedInputTokens,
+      cacheWriteTokens: d.cacheWriteInputTokens,
+      outputTokens: d.outputTokens,
+      model: main ? this.model : (p.tokenUsage?.model ?? this.model),
+      usedPercent: typeof used === "number" ? used : undefined,
+      // Context fill is the main thread's; a helper's window says nothing about it.
+      contextSize: main ? p.tokenUsage?.modelContextWindow : undefined,
+    });
+  }
+
+  /** Notifications from a spawned agent's thread: start, latest step, usage, end. */
+  private onChildThread(method: string, p: any, id: string) {
+    if (method === "thread/tokenUsage/updated" || method === "turn/tokenUsage/updated") return this.usageFrom(p, id);
+    if (method === "thread/started") {
+      const t = p.thread ?? {};
+      this.emit({ type: "subagent", id, name: t.agentRole ?? t.agentNickname, task: t.agentNickname && t.agentRole ? t.agentNickname : undefined, status: "running" });
+    } else if (method === "item/started") {
+      const it = p.item ?? {};
+      const step = it.type === "commandExecution" ? `$ ${Array.isArray(it.command) ? it.command.join(" ") : it.command ?? ""}` : it.type === "fileChange" ? `edit ${(it.changes ?? []).map((c: any) => c.path).join(", ")}` : it.type === "mcpToolCall" ? `${it.server}/${it.tool}` : undefined;
+      if (step) this.emit({ type: "subagent", id, activity: step });
+    } else if (method === "turn/completed") {
+      const status = p.turn?.status;
+      this.emit({ type: "subagent", id, status: status === "failed" || p.turn?.error ? "failed" : "done" });
+    }
+  }
+
   private onNotification(method: string, p: any) {
+    // A spawned agent runs on its own thread over this connection: its messages, tools and
+    // turn end must never land in (or end) the main turn. They become subagent activity.
+    const thread = p?.threadId ?? p?.turn?.threadId ?? (method === "thread/started" ? p?.thread?.id : undefined);
+    if (thread && this.threadId && thread !== this.threadId) return this.onChildThread(method, p, thread);
     switch (method) {
       case "item/agentMessage/delta":
         this.emit({ type: "text_delta", text: p.delta ?? "" });
@@ -198,6 +264,10 @@ export class CodexEngine implements Engine {
       case "item/updated": {
         const it = p.item ?? {};
         if (it.type === "agentMessage" || it.type === "userMessage" || it.type === "reasoning") break;
+        if (it.type === "subAgentActivity") {
+          if (it.agentThreadId) this.emit({ type: "subagent", id: it.agentThreadId, name: agentName(it.agentPath), status: it.kind === "completed" ? "done" : it.kind === "failed" ? "failed" : "running" });
+          break;
+        }
         const status: ToolStatus = method === "item/started" ? "in_progress" : it.status === "failed" || it.status === "declined" ? "failed" : method === "item/completed" ? "completed" : "in_progress";
         const title = it.type === "commandExecution" ? `$ ${Array.isArray(it.command) ? it.command.join(" ") : it.command ?? ""}` : it.type === "fileChange" ? `edit ${(it.changes ?? []).map((c: any) => c.path).join(", ")}` : it.type === "mcpToolCall" ? `${it.server}/${it.tool}` : it.type ?? "tool";
         const detail = it.aggregatedOutput ? String(it.aggregatedOutput).slice(-800) : undefined;
@@ -217,34 +287,9 @@ export class CodexEngine implements Engine {
         this.emit({ type: "plan", entries: (p.plan ?? p.entries ?? []).map((e: any) => ({ content: e.step ?? e.content, status: e.status })) });
         break;
       case "thread/tokenUsage/updated":
-      case "turn/tokenUsage/updated": {
-        const rl = p.rateLimits ?? p.tokenUsage?.rateLimits;
-        const used = rl?.primary?.usedPercent ?? rl?.primary?.used_percent;
-        const t = p.tokenUsage?.total;
-        if (t) {
-          // Totals are cumulative for the thread; emit the delta. Codex's inputTokens include cached ones.
-          const d = {
-            inputTokens: Math.max(0, (t.inputTokens ?? 0) - this.lastTotals.inputTokens),
-            cachedInputTokens: Math.max(0, (t.cachedInputTokens ?? 0) - this.lastTotals.cachedInputTokens),
-            cacheWriteInputTokens: Math.max(0, (t.cacheWriteInputTokens ?? 0) - this.lastTotals.cacheWriteInputTokens),
-            outputTokens: Math.max(0, (t.outputTokens ?? 0) - this.lastTotals.outputTokens),
-          };
-          this.lastTotals = { inputTokens: t.inputTokens ?? 0, cachedInputTokens: t.cachedInputTokens ?? 0, cacheWriteInputTokens: t.cacheWriteInputTokens ?? 0, outputTokens: t.outputTokens ?? 0 };
-          if (d.inputTokens || d.outputTokens) {
-            this.emit({
-              type: "usage",
-              inputTokens: Math.max(0, d.inputTokens - d.cachedInputTokens),
-              cacheReadTokens: d.cachedInputTokens,
-              cacheWriteTokens: d.cacheWriteInputTokens,
-              outputTokens: d.outputTokens,
-              model: this.model,
-              usedPercent: typeof used === "number" ? used : undefined,
-              contextSize: p.tokenUsage?.modelContextWindow,
-            });
-          }
-        } else if (typeof used === "number") this.emit({ type: "usage", usedPercent: used });
+      case "turn/tokenUsage/updated":
+        this.usageFrom(p, this.threadId ?? "main");
         break;
-      }
       case "turn/completed": {
         const status = p.turn?.status;
         const err = p.turn?.error;
@@ -281,7 +326,7 @@ export class CodexEngine implements Engine {
     const done = new Promise<StopReason>((resolve) => (this.turn = { resolve }));
     try {
       const approvalPolicy = this.info?.currentMode === "never" ? "never" : "on-request";
-      const res = await this.request("turn/start", { threadId: this.threadId, cwd: this.cwd, input: [{ type: "text", text }], model: this.model, approvalPolicy });
+      const res = await this.request("turn/start", { threadId: this.threadId, cwd: this.cwd, input: [{ type: "text", text }], model: this.model, approvalPolicy, ...(this.effort ? { effort: this.effort } : {}) });
       if (this.turn) this.turn.id = res?.turn?.id;
     } catch (e: any) {
       const msg = `${e?.message ?? e} ${JSON.stringify(e?.data ?? "")}`.trim();
@@ -314,6 +359,46 @@ export class CodexEngine implements Engine {
   async setModel(modelId: string) {
     this.model = modelId;
     if (this.info) this.info.currentModel = modelId;
+    // Reasoning efforts differ per model: keep the chosen one only if the new model has it.
+    const efforts = this.catalog.find((m) => m.id === modelId)?.efforts ?? [];
+    if (this.effort && !efforts.includes(this.effort)) this.effort = undefined;
+    if (this.info) this.info.options = this.effortOptions();
+  }
+
+  async setOption(optionId: string, value: string) {
+    if (optionId !== "effort") return;
+    this.effort = value;
+    if (this.info) this.info.options = this.effortOptions();
+  }
+
+  /** `model/list`, all pages, hidden models left out. */
+  private async listModels(): Promise<{ id: string; name: string; efforts: string[]; defaultEffort?: string }[]> {
+    const out: { id: string; name: string; efforts: string[]; defaultEffort?: string }[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < 10; page++) {
+      const r: any = await this.request("model/list", cursor ? { cursor } : {});
+      for (const m of r?.data ?? []) {
+        if (m?.hidden) continue;
+        const id = String(m.model ?? m.id ?? "");
+        if (!id) continue;
+        out.push({
+          id,
+          name: String(m.displayName ?? id),
+          efforts: (m.supportedReasoningEfforts ?? []).map((e: any) => String(e?.reasoningEffort ?? e)).filter(Boolean),
+          defaultEffort: m.defaultReasoningEffort ? String(m.defaultReasoningEffort) : undefined,
+        });
+      }
+      cursor = r?.nextCursor ?? undefined;
+      if (!cursor) break;
+    }
+    return out;
+  }
+
+  /** The current model's reasoning efforts, as Codex lists them. */
+  private effortOptions(): EngineOption[] {
+    const m = this.catalog.find((x) => x.id === this.model);
+    if (!m?.efforts.length) return [];
+    return [{ id: "effort", name: "Reasoning effort", category: "thought_level", current: this.effort ?? m.defaultEffort ?? "default", values: m.efforts.map((e) => ({ value: e, name: e })) }];
   }
 
   async close() {
@@ -328,3 +413,8 @@ export class CodexEngine implements Engine {
 function classify(msg: string) {
   return classifyError(msg);
 }
+
+/** "/root/explorer" → "explorer". */
+function agentName(path: unknown): string | undefined {
+  return typeof path === "string" && path ? path.split("/").filter(Boolean).pop() : undefined;
+}

package/src/engines/elicitation.ts

@@ -0,0 +1,60 @@
+import type { QuestionAnswer, QuestionField, QuestionRequest } from "./types.ts";
+
+/**
+ * ACP form elicitations → questions codemax can ask in its own dialog.
+ *
+ * Agents ask through a JSON-schema form (`requestedSchema`). The Claude
+ * adapter uses it for AskUserQuestion: one `question_<n>` field per question
+ * (a `oneOf` pick, or an array of `anyOf` picks for multi-select) followed by
+ * a free-text `question_<n>_custom` "Other" field. MCP servers and other
+ * agents may send any flat schema, so every property type is handled; an
+ * unknown one is asked as text.
+ */
+export function parseElicitation(id: string, p: any): QuestionRequest {
+  const schema = p?.requestedSchema ?? {};
+  const props: Record<string, any> = schema.properties ?? {};
+  const required = new Set<string>(Array.isArray(schema.required) ? schema.required : []);
+  const keys = Object.keys(props);
+  const isSelect = (k: string) => !!props[k] && (opts(props[k]).length > 0 || props[k].type === "boolean");
+  // `<key>_custom` (the adapter's per-question "Other" box) folds into its question.
+  const companion = (k: string) => k.endsWith("_custom") && isSelect(k.slice(0, -"_custom".length)) && (props[k]?.type ?? "string") === "string";
+  const fields: QuestionField[] = [];
+  for (const key of keys) {
+    if (companion(key)) continue;
+    const s = props[key] ?? {};
+    const options = opts(s);
+    const kind: QuestionField["kind"] = s.type === "array" ? "multi" : s.type === "boolean" ? "boolean" : options.length ? "single" : s.type === "number" || s.type === "integer" ? "number" : "text";
+    const other = keys.find((k) => k === `${key}_custom`);
+    fields.push({
+      key,
+      title: str(s.title),
+      question: str(s.description) ?? (keys.filter((k) => !companion(k)).length === 1 ? String(p?.message ?? "") : str(s.title) ?? key),
+      kind,
+      options: kind === "boolean" ? [{ value: "true", label: "Yes" }, { value: "false", label: "No" }] : options,
+      otherKey: other && kind !== "boolean" ? other : undefined,
+      required: required.has(key),
+      integer: s.type === "integer" || undefined,
+    });
+  }
+  return { id, message: String(p?.message ?? ""), fields, toolCallId: p?.toolCallId };
+}
+
+/** The ACP response for an answer (`content` keys are the schema's property names). */
+export function elicitationResponse(a: QuestionAnswer): { action: string; content?: Record<string, unknown> } {
+  return a.action === "accept" ? { action: "accept", content: a.content } : { action: a.action };
+}
+
+function opts(s: any): { value: string; label: string; description?: string }[] {
+  const list = s?.oneOf ?? s?.anyOf ?? s?.items?.oneOf ?? s?.items?.anyOf;
+  if (Array.isArray(list)) return list.filter((o) => o && o.const !== undefined).map((o) => ({ value: String(o.const), label: str(o.title) ?? String(o.const), description: str(o.description) }));
+  const en = s?.enum ?? s?.items?.enum;
+  if (Array.isArray(en)) {
+    const names = s?.enumNames ?? s?.items?.enumNames;
+    return en.map((v: unknown, i: number) => ({ value: String(v), label: Array.isArray(names) && names[i] ? String(names[i]) : String(v) }));
+  }
+  return [];
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim() ? v : undefined;
+}

package/src/engines/index.ts

@@ -6,6 +6,7 @@ import type { Engine, EngineFactory } from "./types.ts";
 import { AcpEngine, type UsageSample } from "./acp.ts";
 import { CodexEngine } from "./codex.ts";
 import { ClaudeUsageTail } from "../transcripts/claude-usage.ts";
+import { antigravityServer } from "./antigravity.ts";
 
 /** Grok writes ~/.grok/sessions/<encoded cwd>/<session>/usage.json with per-turn totals. */
 function grokUsageTail(cwd: string, sessionId: string): { read(): UsageSample[] } {
@@ -115,9 +116,11 @@ const factories: EngineFactory[] = [
     create: () => new AcpEngine({ agent: "cursor", name: "Cursor Agent", cmd: ["cursor-agent", "acp"] }),
   },
   {
-    agent: "gemini",
-    available: async () => !!Bun.which("gemini"),
-    create: () => new AcpEngine({ agent: "gemini", name: "Gemini CLI", cmd: ["gemini", "--experimental-acp"] }),
+    agent: "antigravity",
+    // Google's ACP server for Antigravity (installed on request, see antigravity.ts), driven over
+    // plain pipes and signed in with the user's Google account only, never an API key.
+    available: async () => !!Bun.which("agy") && !!antigravityServer(),
+    create: () => new AcpEngine({ agent: "antigravity", name: "Antigravity CLI", cmd: antigravityServer()!.cmd, plainPipes: true, signIn: ["oauth-personal", "oauth-business"] }),
   },
 ];
 

package/src/engines/types.ts

@@ -12,6 +12,10 @@ export type EngineEvent =
   | { type: "tool_call"; id: string; title: string; kind?: string; status: ToolStatus; detail?: string; input?: unknown; output?: string; files?: string[] }
   | { type: "tool_update"; id: string; status?: ToolStatus; title?: string; detail?: string; input?: unknown; output?: string; files?: string[] }
   | { type: "permission_request"; request: PermissionRequest }
+  /** A subagent the main agent spawned (Task/Agent tool…): started, doing something, or finished. */
+  | SubagentEvent
+  /** The agent asks the user something (Claude's AskUserQuestion, MCP forms). Answer with `answerQuestion`. */
+  | { type: "question_request"; request: QuestionRequest }
   | { type: "plan"; entries: { content: string; status: string; priority?: string }[] }
   | { type: "mode"; modeId: string }
   | { type: "commands"; commands: { name: string; description?: string }[] }
@@ -27,6 +31,8 @@ export type EngineEvent =
       costUsd?: number;
       /** Rate-limit window consumption, when the agent exposes it. */
       usedPercent?: number;
+      /** Subscription plan limits the agent reported (Claude: 5-hour, weekly…), one entry per window. */
+      planLimits?: PlanLimit[];
       /** Context window fill, when reported (tokens used / size). */
       contextUsed?: number;
       contextSize?: number;
@@ -36,6 +42,15 @@ export type EngineEvent =
   | { type: "error"; kind: ErrorKind; message: string }
   | { type: "log"; level: "info" | "warn" | "error"; message: string };
 
+export interface PlanLimit {
+  /** e.g. "five_hour", "seven_day", "seven_day_opus". */
+  window: string;
+  usedPercent?: number;
+  resetsAt?: number;
+  /** "allowed" | "allowed_warning" | "rejected" (out of this window's quota). */
+  status?: string;
+}
+
 export type ToolStatus = "pending" | "in_progress" | "completed" | "failed";
 export type StopReason = "end_turn" | "max_tokens" | "cancelled" | "refusal" | "error" | "other";
 export type ErrorKind = "quota" | "auth" | "protocol" | "crashed" | "other";
@@ -57,6 +72,43 @@ export interface PermissionRequest {
   options: PermissionOption[];
 }
 
+export interface SubagentEvent {
+  type: "subagent";
+  /** Stable id (the launching tool call's id). */
+  id: string;
+  /** Agent type or name ("Explore", "general-purpose"). */
+  name?: string;
+  /** What it was asked to do (short description). */
+  task?: string;
+  /** Its latest step ("Grep(requireAuth)"). */
+  activity?: string;
+  status?: "running" | "done" | "failed";
+}
+
+export interface QuestionField {
+  /** Property name in the agent's form; the answer is keyed by it. */
+  key: string;
+  /** Short label ("Database"), when the agent gives one. */
+  title?: string;
+  question: string;
+  kind: "single" | "multi" | "text" | "number" | "boolean";
+  options: { value: string; label: string; description?: string }[];
+  /** Companion free-text field the agent accepts as "Other". */
+  otherKey?: string;
+  required?: boolean;
+  integer?: boolean;
+}
+
+export interface QuestionRequest {
+  id: string;
+  message: string;
+  fields: QuestionField[];
+  toolCallId?: string;
+}
+
+/** accept = answered; decline = the user skipped (the agent carries on); cancel = abort the request. */
+export type QuestionAnswer = { action: "accept"; content: Record<string, string | number | boolean | string[]> } | { action: "decline" } | { action: "cancel" };
+
 export interface EngineSessionRef {
   agent: AgentId;
   /** Vendor session / thread id, used to resume. */
@@ -73,6 +125,8 @@ export interface EngineMode {
 }
 
 export interface EngineStartOptions {
+  /** Let the agent ask the user questions (form elicitation). Off: the agent decides on its own. */
+  questions?: boolean;
   cwd: string;
   /** Resume a previous session instead of starting a new one. */
   resume?: EngineSessionRef;
@@ -115,6 +169,8 @@ export interface Engine {
   /** Send one user turn. Resolves when the turn ends (turn_end has been emitted). */
   prompt(text: string): Promise<StopReason>;
   answerPermission(requestId: string, optionId: string): void;
+  /** Engines that can ask the user questions (`question_request`) answer them here. */
+  answerQuestion?(requestId: string, answer: QuestionAnswer): void;
   cancel(): Promise<void>;
   setMode?(modeId: string): Promise<void>;
   setModel?(modelId: string): Promise<void>;

package/src/tui/app.ts

@@ -68,10 +68,15 @@ export class App {
     this.setStatus("");
   }
 
-  async start(agent: AgentId, fresh: boolean) {
+  /** `explicit`: the user named this agent (--agent), so never start a different one. */
+  async start(agent: AgentId, fresh: boolean, o: { explicit?: boolean } = {}) {
     await this.refreshDetect();
-    const first = this.detect.get(agent)?.installed ? agent : this.firstInstalled();
+    const installed = this.detect.get(agent)?.installed;
+    if (!installed && o.explicit) throw new Error(`${agent} is not installed. Installed: ${this.installedList() || "none"}`);
+    const first = installed ? agent : this.firstInstalled();
     if (!first) throw new Error("no supported agent CLI found on PATH");
+    // Under tests a fallback must never reach a real agent (no logins, no quota).
+    if (first !== agent && process.env.NODE_ENV === "test") throw new Error(`test asked for ${agent}, which is not available; refusing to fall back to ${first}`);
     if (first !== agent) this.setStatus(`${agent} not found, starting ${first}`);
     await this.launch(getAdapter(first), { fresh });
     return this.done;
@@ -282,6 +287,10 @@ export class App {
     );
   }
 
+  private installedList(): string {
+    return [...this.detect.entries()].filter(([, d]) => d.installed).map(([id]) => id).join(", ");
+  }
+
   private firstInstalled(): AgentId | undefined {
     return listAdapters(this.config.order).find((a) => this.detect.get(a.id)?.installed)?.id;
   }
@@ -360,11 +369,11 @@ export class App {
 }
 
 /** Run codemax on the real terminal until the user quits. */
-export async function runApp(config: Config, ledger: Ledger, cwd: string, agent: AgentId, fresh: boolean) {
+export async function runApp(config: Config, ledger: Ledger, cwd: string, agent: AgentId, fresh: boolean, explicit = false) {
   const renderer = await createCliRenderer({ exitOnCtrlC: false, exitSignals: ["SIGTERM", "SIGHUP"], useMouse: true, targetFps: 60 });
   const app = new App(renderer, config, ledger, cwd);
   try {
-    await app.start(agent, fresh);
+    await app.start(agent, fresh, { explicit });
   } finally {
     renderer.destroy();
     try {