mulmoterminal 4.23.0 → 4.25.0

package/README.md

@@ -58,8 +58,10 @@ ping to your phone when a task finishes. One `npx` command, no Electron, no conf
 npx mulmoterminal@latest        # starts on http://localhost:34567 and opens your browser
 ```
 
-Requires **Node ≥ 22.12** and the [`claude`](https://claude.com/claude-code) CLI on your
-`PATH`, already logged in. `npx mulmoterminal@latest init` reports what it can't find.
+Requires **Node ≥ 22.12**, and by default the [`claude`](https://claude.com/claude-code) CLI —
+on your `PATH` or named by `CLAUDE_BIN`, already logged in. Declare a different default agent
+(`--agent codex`, or `"defaultAgent"` in `~/.mulmoterminal/config.json`) and start-up checks that
+one instead. `npx mulmoterminal@latest init` reports what it can't find.
 
 ### Why not tmux + iTerm panes?
 
@@ -255,7 +257,7 @@ more.
 
 ## Install & run
 
-Needs **Node ≥ 22.12**, plus these CLIs on your `PATH`:
+Needs **Node ≥ 22.12**, plus these CLIs — on your `PATH`, or named by the matching `<AGENT>_BIN`:
 
 > **Never installed any of this before?** The guide walks it end to end, macOS and Windows,
 > assuming no command-line experience:
@@ -264,7 +266,7 @@ Needs **Node ≥ 22.12**, plus these CLIs on your `PATH`:
 
 | | Tool | What it gives you | Install |
 | --- | --- | --- | --- |
-| **Required** | [`claude`](https://claude.com/claude-code) | every Claude session — this app is a cockpit for it | `npm i -g @anthropic-ai/claude-code`, then run `claude` once to log in |
+| **Required** *(unless you declare another)* | [`claude`](https://claude.com/claude-code) | every Claude session — this app is a cockpit for it. Start-up requires it **by default**; declare a default agent and it checks that one instead — `npx mulmoterminal --agent codex`, or `"defaultAgent": "codex"` in `~/.mulmoterminal/config.json` (#2082). `CLAUDE_BIN` is honoured, so an install off `PATH` counts | `npm i -g @anthropic-ai/claude-code`, then run `claude` once to log in |
 | **Required** | `git` | [worktree isolation](#git-worktrees--pull-requests), each cell's branch / unsaved-dot / diff readout, the PR footer | `brew install git` · `sudo apt install git` · `sudo dnf install git` · Windows: [git-scm.com](https://git-scm.com/download/win) |
 | **Required** | `gh` | the cross-repo **PRs & Issues** view and one-click PR creation — it uses your `gh` login, so no token is stored | [cli.github.com](https://cli.github.com), then `gh auth login` |
 | Optional | `glab` | the same for **GitLab** projects (#981) — gitlab.com, and a self-hosted instance you declare in `gitlabHosts` (#1332). Same arrangement: the CLI holds the credentials, this app stores no token | `brew install glab`, then `glab auth login` (self-hosted: `glab auth login --hostname gitlab.example.com`) |
@@ -276,7 +278,10 @@ Needs **Node ≥ 22.12**, plus these CLIs on your `PATH`:
 
 The server starts without any of the non-required rows; you just lose that row's feature,
 and the header/panel for it says so. `git` and `gh` are marked required because losing them
-costs whole views rather than one button. `npx mulmoterminal@latest init` (below) reports which of
+costs whole views rather than one button. `claude` is required only until you name a different
+default agent — see
+[Starting without Claude Code](https://receptron.github.io/mulmoterminal/guide/en/agents.html#default-agent)
+· [日本語](https://receptron.github.io/mulmoterminal/guide/ja/agents.html#default-agent). `npx mulmoterminal@latest init` (below) reports which of
 these it can find.
 
 ```bash
@@ -346,8 +351,8 @@ npx mulmoterminal@latest --cwd ./my-project   # work in a specific directory
 ```
 
 The published package ships the server (run via `tsx`) plus the pre-built web UI;
-`npx mulmoterminal@latest` checks for the `claude` CLI, picks a free port, starts the
-server, and opens the browser. For local development from a clone, see
+`npx mulmoterminal@latest` checks for the `claude` CLI — or for whichever agent you set as the
+default — picks a free port, starts the server, and opens the browser. For local development from a clone, see
 [Running](#running).
 
 **Won't start with `ERR_MODULE_NOT_FOUND`?** If a first `npx` run was interrupted, a half-unpacked `~/.npm/_npx/<hash>` cache can remain and a later run fails at startup — a corrupted npx cache, not a bug in the published package.
@@ -650,7 +655,10 @@ detects `tmux` on `PATH` at startup and uses it automatically when present.
 | Plugins  | GUI-protocol Vue plugins (`@mulmoclaude/*`, `@mulmochat-plugin/*`): markdown, form, image, chart, HTML, collection, accounting, mulmoscript (MulmoCast video/slides), google |
 | Tests    | Vitest + @vue/test-utils + jsdom |
 
-Requires **Node ≥ 22.12** (uses `node --env-file-if-exists`) and the `claude` CLI on `PATH`.
+Requires **Node ≥ 22.12** (uses `node --env-file-if-exists`) and, by default, the `claude` CLI —
+found on `PATH` or named by `CLAUDE_BIN`. Declaring a different default agent (`--agent codex`, or
+`"defaultAgent"` in `~/.mulmoterminal/config.json`) makes start-up check that agent instead (#2082):
+see [Starting without Claude Code](https://receptron.github.io/mulmoterminal/guide/en/agents.html#default-agent).
 
 ---
 

package/bin/agent-bins.d.ts

@@ -0,0 +1,15 @@
+// Types for bin/agent-bins.js — hand-written for the reason every other bin/*.d.ts is: the file is
+// plain JS because it runs before tsx does, and the specs and the server are TypeScript.
+import type { TerminalAgent } from "../common/sessionAgent.js";
+
+export interface AgentBinSpec {
+  /** The environment variable that overrides the command, e.g. `CLAUDE_BIN`. */
+  env: string;
+  /** The command as installed. NOT always the agent id — agy and cursor-agent are the commands. */
+  bin: string;
+}
+
+export declare const AGENT_BIN_SPEC: Record<TerminalAgent, AgentBinSpec>;
+export declare function agentBin(agent: string, env?: Record<string, string | undefined>): string | null;
+/** Only the agents this repository documents an install command for. */
+export declare const AGENT_INSTALL_HINT: Partial<Record<TerminalAgent, string>>;

package/bin/agent-bins.js

@@ -0,0 +1,38 @@
+// Which binary each hosted agent runs, and the environment variable that overrides it.
+//
+// Here in `bin/` rather than in `server/` because the CLI needs it BEFORE the server exists: the
+// start-up gate has to decide whether the declared agent is installed, and it runs under plain node
+// with no tsx. The server imports from `bin/` already (bin/instances.js), so this direction is the
+// established one.
+//
+// The table is duplicated knowledge by construction — `server/config/agent-bins.ts` builds the same
+// mapping out of the adapters — so a spec pins the two together rather than a comment asking the
+// next person to keep them in sync.
+//
+// The KEY is the agent id and the `bin` is NOT always the same word: agy and cursor-agent are the
+// commands, `antigravity` and `cursor` are what the rest of the app calls them.
+export const AGENT_BIN_SPEC = {
+  claude: { env: "CLAUDE_BIN", bin: "claude" },
+  codex: { env: "CODEX_BIN", bin: "codex" },
+  antigravity: { env: "ANTIGRAVITY_BIN", bin: "agy" },
+  grok: { env: "GROK_BIN", bin: "grok" },
+  muse: { env: "MUSE_BIN", bin: "muse" },
+  copilot: { env: "COPILOT_BIN", bin: "copilot" },
+  cursor: { env: "CURSOR_BIN", bin: "cursor-agent" },
+};
+
+/** The command that actually runs for `agent`, honouring its `<AGENT>_BIN` override. */
+export function agentBin(agent, env = process.env) {
+  const spec = AGENT_BIN_SPEC[agent];
+  if (spec === undefined) return null;
+  return env[spec.env] || spec.bin;
+}
+
+/** The install command for the agents this repository actually documents one for — Claude Code in
+ *  the start-up gate's own message, codex in PATH_TOOLS. The other five are deliberately ABSENT
+ *  rather than guessed: an install line that is wrong is worse than none, because it is the one
+ *  thing a stuck user will paste. They get the binary name and the guide link instead. */
+export const AGENT_INSTALL_HINT = {
+  claude: "npm install -g @anthropic-ai/claude-code  &&  claude auth login",
+  codex: "npm install -g @openai/codex",
+};

package/bin/cli-args.d.ts

@@ -16,7 +16,7 @@ export declare function saysYes(answer: unknown): boolean;
 export declare const SECOND_INSTANCE_NOTE: string;
 export declare const MIN_NODE_LABEL: string;
 export declare function nodeMeetsMinimum(version: string): boolean;
-export declare function serverNodeArgs(serverEntry: string, launchDir: string, port: number): string[];
+export declare function serverNodeArgs(serverEntry: string, launchDir: string, port: number, declaredAgent?: string | null): string[];
 export declare function serverSpawnEnv(env: Record<string, string | undefined>, cwd: string): Record<string, string | undefined>;
 export interface RunningInstance {
   pid: number;

package/bin/cli-args.js

@@ -426,9 +426,14 @@ export function nodeMeetsMinimum(version) {
  * MulmoTerminal's own port (#1857). Renaming it would only move that: `MULMOTERMINAL_PORT` is
  * deliberately given to PTYs (server/session/mcp-config.ts) for the MCP URLs, so a server
  * reading it as its bind port would clash with itself the moment `yarn dev` ran inside a cell.
+ *
+ * `--agent` rides the same channel for the same reason (#2082): it is a preference, and a
+ * preference in the environment would reach every terminal in every cell exactly as the port did.
+ * Omitted entirely when nothing was declared, so the server falls through to its config file.
  */
-export function serverNodeArgs(serverEntry, launchDir, port) {
-  return ["--import", "tsx", `--env-file-if-exists=${join(launchDir, ".env")}`, serverEntry, "--port", String(port)];
+export function serverNodeArgs(serverEntry, launchDir, port, declaredAgent = null) {
+  const base = ["--import", "tsx", `--env-file-if-exists=${join(launchDir, ".env")}`, serverEntry, "--port", String(port)];
+  return declaredAgent === null ? base : [...base, "--agent", declaredAgent];
 }
 
 /**

package/bin/default-agent.d.ts

@@ -0,0 +1,19 @@
+// Types for bin/default-agent.js. See that file for why the gate works the way it does.
+import type { TerminalAgent } from "../common/sessionAgent.js";
+
+export interface StartupGate {
+  /** Whose binary start-up must find. */
+  agent: TerminalAgent;
+  /** Always true today; named so a future "warn instead" cannot be added by accident. */
+  required: boolean;
+  /** Whether the user asked for this agent, which changes what the failure says. */
+  declared: boolean;
+}
+
+export declare function isKnownAgent(value: unknown): value is TerminalAgent;
+/** The raw token after `--agent`, `""` for a valueless flag, or null when absent. */
+export declare function parseAgentArg(args: readonly string[]): string | null;
+export declare function resolveDeclaredAgent(input?: { cliAgent?: string | null; configAgent?: string | null }): string | null;
+export declare function gateFor(declaredAgent: string | null): StartupGate;
+export declare function configuredDefaultAgent(parsedConfig: unknown): string | null;
+export declare function missingAgentMessage(gate: StartupGate, bin: string | null): string[];

package/bin/default-agent.js

@@ -0,0 +1,99 @@
+// Which agent the CLI is being asked to treat as the default, and what the start-up gate must
+// therefore check. Pure — no PATH lookup, no filesystem — so every combination is testable
+// without a machine that has or lacks a given CLI.
+//
+// THE RULE (issue #2082): Claude Code stays REQUIRED while nothing is declared, because that is the
+// setup the overwhelming majority of users have and a silent fallback would leave them wondering
+// which agent they are talking to. Declare a default and the gate follows the declaration instead:
+// it stops asking about claude entirely and asks about the agent that was named.
+//
+// WHAT THIS IS NOT: it does not decide what an EXISTING cell runs. On disk and on the wire, an
+// absent `agent` field means claude (src/components/gridTabs.ts says so), and that is a storage
+// format rather than a preference — repointing it at this setting would silently re-launch every
+// saved Claude cell as something else. This value is read when a NEW session starts, and nowhere
+// in the path that restores an old one.
+import { AGENT_BIN_SPEC, AGENT_INSTALL_HINT } from "./agent-bins.js";
+
+export const isKnownAgent = (value) => typeof value === "string" && Object.prototype.hasOwnProperty.call(AGENT_BIN_SPEC, value);
+
+/** `--agent <name>`, or `--agent=<name>`. Returns the raw token so the caller can reject an unknown
+ *  one by name rather than silently ignoring a typo. `null` when the flag is absent; `""` when it
+ *  is present with nothing after it, which is a usage error rather than "no preference". */
+export function parseAgentArg(args) {
+  const joined = args.find((a) => a.startsWith("--agent="));
+  if (joined !== undefined) return joined.slice("--agent=".length);
+  const i = args.indexOf("--agent");
+  if (i === -1) return null;
+  return args[i + 1] !== undefined && !args[i + 1].startsWith("-") ? args[i + 1] : "";
+}
+
+/**
+ * The declared default agent, or null when nothing declares one.
+ *
+ * Two channels only — the flag and the config file — and the flag wins, which is the ordinary
+ * shape: the most local statement of intent beats the most durable one.
+ *
+ * Deliberately NOT a third, environment channel. The launcher hands its own environment to the
+ * server, which hands it to every PTY it spawns, so a variable added here reaches every terminal in
+ * every cell — the shape of #955 (NODE_ENV) and #1857 (PORT). `--port` was moved OUT of the
+ * environment for that reason (server/config/port-from-argv.ts), and this follows it.
+ */
+export function resolveDeclaredAgent({ cliAgent = null, configAgent = null } = {}) {
+  const declared = cliAgent ?? configAgent ?? null;
+  return declared === null || declared === undefined || declared === "" ? null : declared;
+}
+
+/**
+ * What the start-up gate should require, given the declaration.
+ *
+ * `{ agent, required }` — WHICH agent's binary to look for, and whether a miss stops start-up.
+ * A declared agent is required for the same reason claude was: the user named it, so a machine
+ * without it cannot do what they asked, and saying so beats an empty grid (issue #2082, decision 1).
+ */
+export function gateFor(declaredAgent) {
+  return declaredAgent === null ? { agent: "claude", required: true, declared: false } : { agent: declaredAgent, required: true, declared: true };
+}
+
+/** `defaultAgent` out of a parsed `~/.mulmoterminal/config.json`, or null. Pure: the caller owns the
+ *  read and the JSON parse, because a config this CLI cannot read must not stop it starting. An
+ *  unknown name is returned as-is so the caller reports the typo rather than ignoring it. */
+export function configuredDefaultAgent(parsedConfig) {
+  if (parsedConfig === null || typeof parsedConfig !== "object" || Array.isArray(parsedConfig)) return null;
+  const value = Object.prototype.hasOwnProperty.call(parsedConfig, "defaultAgent") ? parsedConfig.defaultAgent : null;
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+// The SECTION, not the guide index: someone reading this message is stuck on exactly one question,
+// and a link to the front page makes them hunt for the answer they were sent to find.
+const GUIDE = {
+  en: "https://receptron.github.io/mulmoterminal/guide/en/agents.html#default-agent",
+  ja: "https://receptron.github.io/mulmoterminal/guide/ja/agents.html#default-agent",
+};
+
+/**
+ * What to print when the gate's agent is not installed.
+ *
+ * Short on purpose. The rule here surprises people — Claude Code is required, and yet the app hosts
+ * seven agents — so the message has to answer "why me?" and "what do I type?" in the terminal, and
+ * send the rest to the guide. Everything longer than this belongs on that page (issue #2082).
+ */
+export function missingAgentMessage(gate, bin) {
+  const lines = [];
+  if (gate.declared) {
+    lines.push(`${gate.agent} is set as the default agent, but its command "${bin}" was not found.`);
+    lines.push(`Install it and make sure "${bin}" is on PATH, or set ${AGENT_BIN_SPEC[gate.agent]?.env ?? "the agent's *_BIN"} to its full path.`);
+  } else {
+    lines.push(`Claude Code CLI not found (looked for "${bin}").`);
+    const hint = AGENT_INSTALL_HINT.claude;
+    lines.push(`Install it:  ${hint}`);
+    lines.push("");
+    lines.push("Or, if you use a different agent, declare it and this check is skipped:");
+    lines.push("  npx mulmoterminal --agent codex");
+    lines.push('  ~/.mulmoterminal/config.json:  { "defaultAgent": "codex" }');
+    lines.push(`  agents: ${Object.keys(AGENT_BIN_SPEC).join(", ")}`);
+  }
+  lines.push("");
+  lines.push(`Details:  ${GUIDE.en}`);
+  lines.push(`日本語:    ${GUIDE.ja}`);
+  return lines;
+}

package/bin/has-command.d.ts

@@ -0,0 +1,9 @@
+export interface CommandProbe {
+  isFile: (candidate: string) => boolean;
+  isExecutable: (candidate: string) => boolean;
+}
+
+export declare function hasCommand(
+  cmd: string,
+  options?: { platform?: NodeJS.Platform; env?: Record<string, string | undefined>; probe?: CommandProbe },
+): boolean;

package/bin/has-command.js

@@ -0,0 +1,120 @@
+// Is this command present and runnable?
+//
+// RESOLVED, never executed. That is the whole design, and it is what makes both of the bugs this
+// file was created for impossible rather than handled:
+//
+//   1. INJECTION. The command can be a `<AGENT>_BIN` the user set (#2082). The original probe ran
+//      `execSync(`${cmd} ${arg}`)`, so a shell both SPLIT it and INTERPRETED it — measured:
+//        CLAUDE_BIN="/…/My Tools/claude"  -> REFUSED, split at the space
+//        CLAUDE_BIN="true; touch /tmp/X"  -> the `touch` RAN
+//   2. WINDOWS `.cmd`. `execFileSync` cannot launch a `.bat`/`.cmd` at all — node documents it,
+//      and node refuses it outright since CVE-2024-27980. An npm-installed `codex` on Windows IS
+//      `codex.cmd`, so an argv probe reports it missing on the one platform where the shell probe
+//      used to work (Codex round 2 of #2084).
+//
+// A file lookup has neither problem: nothing is interpreted, it is just candidate names on disk.
+// WHICH candidates is the whole remaining question, and it is not this file's to invent — it is
+// `server/infra/has-binary.ts`'s, because "can we launch it" and "what would we launch" must not
+// answer differently. `test/bin/gate-agrees-with-spawn.spec.ts` compares the two over generated
+// machines rather than trusting these comments.
+//
+// The trade, said out loud: this reports a binary that EXISTS and is executable, not one that
+// exits 0. A present-but-broken install now reads as present. That is what the server's own
+// pre-spawn check already concluded, and the alternative is executing a string the user supplied.
+import { accessSync, constants, statSync } from "node:fs";
+import path from "node:path";
+
+// The candidate names node-pty can actually START on Windows — `.exe`/`.com` as PE images, and
+// `.cmd`/`.bat` through the cmd.exe wrapper resolve-bin builds. Deliberately NOT the user's
+// PATHEXT: a stock one also carries `.VBS`, `.JS`, `.WSF`, `.MSC`, none of which CreateProcessW
+// will run, so honouring it passed a machine whose every session then died with node-pty's empty
+// `File not found:`. Reading it also cut the list the other way — `PATHEXT=.PS1` hid a real
+// `claude.exe` — which is why the answer is a closed set and not an environment variable.
+//
+// `""` belongs to it for the reason resolve-bin states: node-pty's own pre-spawn lookup compares
+// file names EXACTLY, so an extension-less PE image on PATH is one it finds, and refusing it would
+// refuse a host that spawns fine today.
+const WINDOWS_LAUNCHABLE_EXTENSIONS = ["", ".exe", ".com", ".cmd", ".bat"];
+
+/** A name CreateProcess/execvp resolves itself rather than by searching PATH. */
+const namesAPath = (cmd) => cmd.includes("/") || cmd.includes("\\");
+
+const realProbe = {
+  isFile: (candidate) => {
+    try {
+      return statSync(candidate).isFile();
+    } catch {
+      return false;
+    }
+  },
+  // Windows has no execute bit that means anything here — the file TYPE is what decides, and the
+  // extension loop has already applied it.
+  isExecutable: (candidate) => {
+    try {
+      accessSync(candidate, constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+// "" first so an explicit `foo.exe` is found as itself rather than as `foo.exe.EXE`.
+const extensionsFor = (platform) => (platform === "win32" ? WINDOWS_LAUNCHABLE_EXTENSIONS : [""]);
+
+// A Windows PATH entry may be QUOTED — `"C:\Program Files\tools"` — which the shells strip and a
+// plain join would not, leaving a path that matches nothing. Same rule as the server's
+// `windowsSearchDirectories` (server/infra/resolve-bin.ts); `C:\Program Files` is the canonical
+// path that needs the quotes, so this is the common case rather than an exotic one.
+// The current directory is on neither platform's list. cmd.exe searches it and POSIX shells do
+// not, but what launches an agent is node-pty on both — and the directory THIS process sits in is
+// the launch directory, never the one the PTY will run in.
+const searchDirectories = (platform, env) => {
+  const raw = env.PATH || env.Path || "";
+  if (platform === "win32") {
+    return raw
+      .split(";")
+      .map((entry) => entry.replace(/^"(.*)"$/, "$1"))
+      .filter((entry) => entry !== "");
+  }
+  return raw.split(":").filter((entry) => entry !== "");
+};
+
+// Can this process enumerate everything execvp would search? Two cases where it cannot, both taken
+// from server/infra/has-binary.ts, which reasoned them out first:
+//
+//   - an UNSET PATH is not an empty one. execvp falls back to its own built-in default
+//     (confstr _CS_PATH), which is not readable from here.
+//   - a NON-ABSOLUTE entry — `tools`, `.`, `../bin`, and the EMPTY entry, which POSIX reads as the
+//     current directory (`PATH=/usr/bin:`, `/a::/b`) — is resolved against the CHILD's working
+//     directory, not this process's.
+//
+// This matters because this gate REFUSES START-UP. The repo's own rule for a preflight in that
+// position: one that cannot answer must never be the thing that says no (Codex round 6 of #2084,
+// which measured /bin/sh running ./faux with PATH=":/usr/bin").
+const canEnumeratePosixPath = (env) => env.PATH !== undefined && env.PATH.split(":").every((entry) => entry.startsWith("/"));
+
+/**
+ * True when `cmd` names something this machine could launch.
+ *
+ * `platform`, `env` and `probe` are injected so the WINDOWS rules are testable from any host —
+ * which matters more than usual here, because the Windows branch is the one that regressed and the
+ * one no developer on macOS can exercise (reveal-argv.spec.ts makes the same argument).
+ */
+export function hasCommand(cmd, { platform = process.platform, env = process.env, probe = realProbe } = {}) {
+  if (typeof cmd !== "string" || cmd === "") return false;
+  const runnable = (candidate) => probe.isFile(candidate) && (platform === "win32" || probe.isExecutable(candidate));
+  // EXACTLY, with no extension appended. Handed a path, node-pty checks that path and nothing else
+  // (CreateProcessW's own `.exe` guess never runs, because the spawn dies at node-pty's check
+  // first) — so `CLAUDE_BIN=C:\tools\claude` beside a `claude.exe` is a setup that does not work,
+  // and a gate that passed it would only move the failure to the first session.
+  if (namesAPath(cmd)) return runnable(cmd);
+  const extensions = extensionsFor(platform);
+  // Answered BEFORE the search, because the answer is "we cannot tell" rather than "not found".
+  if (platform !== "win32" && !canEnumeratePosixPath(env)) return true;
+  // The path module has to MATCH the platform being asked about, not the one this process runs on.
+  // Without it the Windows branch builds `C:\npm/codex.cmd` when exercised from macOS — which is
+  // how the Windows tests here found their own harness bug before they found a real one.
+  const join = platform === "win32" ? path.win32.join : path.posix.join;
+  return searchDirectories(platform, env).some((dir) => extensions.some((ext) => runnable(join(dir, cmd + ext))));
+}

package/bin/mulmoterminal.js

@@ -6,10 +6,10 @@
 // runs the server via tsx. Mirrors the mulmoclaude launcher.
 
 import { execSync, spawn } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { createServer } from "node:net";
-import { release } from "node:os";
+import { homedir, release } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
@@ -36,7 +36,10 @@ import {
   serverNodeArgs,
   serverSpawnEnv,
 } from "./cli-args.js";
+import { hasCommand } from "./has-command.js";
 import { liveInstances } from "./instances.js";
+import { agentBin, AGENT_BIN_SPEC } from "./agent-bins.js";
+import { configuredDefaultAgent, gateFor, isKnownAgent, missingAgentMessage, parseAgentArg, resolveDeclaredAgent } from "./default-agent.js";
 import { setProcessTitle } from "./process-title.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -88,47 +91,55 @@ async function checkForUpdate() {
   }
 }
 
-// Detect a CLI on the user's PATH by asking for its version. Intentionally resolves from
-// PATH — detecting the user's installed tools is the whole point of the pre-flight /
-// `init` checks.
-function hasCommand(cmd, versionArg = "--version") {
+const CONFIG_FILE = join(homedir(), ".mulmoterminal", "config.json");
+const KNOWN_AGENTS = Object.keys(AGENT_BIN_SPEC);
+
+// `defaultAgent` out of the user's config, or null. EVERY failure is null: a config file that is
+// missing, unreadable or malformed must not stop the app starting, because the whole point of this
+// setting is to get people INTO the app. A malformed file is the server's to complain about, where
+// the message can be a real one.
+function readConfiguredDefaultAgent() {
   try {
-    execSync(`${cmd} ${versionArg}`, { stdio: "pipe" });
-    return true;
+    return configuredDefaultAgent(JSON.parse(readFileSync(CONFIG_FILE, "utf8")));
   } catch {
-    return false;
+    return null;
   }
 }
 
-function claudeInstalled() {
-  return hasCommand("claude");
+// The command for `agent`, honouring its `<AGENT>_BIN` override.
+//
+// The override is the point rather than a detail: the gate used to look for the literal word
+// `claude` on PATH while the server ran `process.env.CLAUDE_BIN || "claude"`
+// (server/agents/claude.ts). A user who set CLAUDE_BIN to a real install was refused start-up by a
+// check asking a different question than the thing it was gating (#2082).
+function agentInstalled(agent) {
+  const bin = agentBin(agent);
+  return bin === null ? false : hasCommand(bin);
 }
 
 // PATH tools the app shells out to; mirrors the requirements table in README.md. `required`
 // ones back the core grid — without them a developer loses whole views rather than one
 // feature — so a miss is an ✗, not an ○.
 const PATH_TOOLS = [
-  { cmd: "git", versionArg: "--version", required: true, why: "worktrees, per-cell branch/diff, PR footer", hint: "brew install git  ·  apt install git" },
-  { cmd: "gh", versionArg: "--version", required: true, why: "PRs & Issues view + one-click PRs", hint: "https://cli.github.com  (then: gh auth login)" },
+  { cmd: "git", required: true, why: "worktrees, per-cell branch/diff, PR footer", hint: "brew install git  ·  apt install git" },
+  { cmd: "gh", required: true, why: "PRs & Issues view + one-click PRs", hint: "https://cli.github.com  (then: gh auth login)" },
   // Optional rather than a second required tool: github.com is what the app is built around, and a
   // user with no GitLab project should not be told they are missing something (#981).
   {
     cmd: "glab",
-    versionArg: "--version",
     required: false,
     why: "the PRs & Issues view for gitlab.com projects",
     hint: "brew install glab  (then: glab auth login)",
   },
-  { cmd: "tmux", versionArg: "-V", required: false, why: "sessions survive a restart", hint: "brew install tmux  ·  apt install tmux" },
-  { cmd: "codex", versionArg: "--version", required: false, why: "run OpenAI Codex as an agent", hint: "npm install -g @openai/codex" },
+  { cmd: "tmux", required: false, why: "sessions survive a restart", hint: "brew install tmux  ·  apt install tmux" },
+  { cmd: "codex", required: false, why: "run OpenAI Codex as an agent", hint: "npm install -g @openai/codex" },
   {
     cmd: "ffmpeg",
-    versionArg: "-version",
     required: false,
     why: "video rendering in the mulmo-script panel",
     hint: "brew install ffmpeg  ·  apt install ffmpeg",
   },
-  { cmd: "ollama", versionArg: "--version", required: false, why: "a fully local model via claude-ollama", hint: "https://ollama.com/download" },
+  { cmd: "ollama", required: false, why: "a fully local model via claude-ollama", hint: "https://ollama.com/download" },
 ];
 
 // The variables WSL exports into a login shell, then the kernel that names itself
@@ -150,7 +161,6 @@ function fileDialogTool() {
   if (isWslHost()) {
     return {
       cmd: "powershell.exe",
-      versionArg: "-NoProfile -Command exit",
       required: false,
       why: `${why}, using the Windows dialog`,
       hint: "enable WSL interop (wsl.conf), or: sudo apt install zenity",
@@ -158,15 +168,14 @@ function fileDialogTool() {
   }
   return {
     cmd: "zenity",
-    versionArg: "--version",
     required: false,
     why: `${why} (kdialog / qarma / yad also work)`,
     hint: "sudo apt install zenity  ·  sudo dnf install zenity",
   };
 }
 
-function toolCheckLine({ cmd, versionArg, required, why, hint }) {
-  if (hasCommand(cmd, versionArg)) return `  ✓ ${cmd} — ${why}`;
+function toolCheckLine({ cmd, required, why, hint }) {
+  if (hasCommand(cmd)) return `  ✓ ${cmd} — ${why}`;
   const head = required ? `  ✗ ${cmd} — not found, needed for ${why}` : `  ○ ${cmd} — optional (${why})`;
   return `${head}\n      → ${hint}`;
 }
@@ -181,6 +190,36 @@ function promptYesNo(question) {
   });
 }
 
+// Which agent this machine is being asked to run by default, and therefore which binary has to be
+// there. Claude Code stays REQUIRED while nothing is declared — that is the setup nearly everyone
+// has, and a silent fallback would leave them guessing which agent answered. Declare one and the
+// gate follows the declaration instead (#2082).
+//
+// Exits rather than returning a failure: every branch here is "this machine cannot do what was
+// asked", and the caller has nothing to add. Returns the declaration so the server can be told.
+function passStartupGate(args) {
+  const cliAgent = parseAgentArg(args);
+  if (cliAgent !== null && !isKnownAgent(cliAgent)) {
+    error(cliAgent === "" ? "--agent needs an agent name." : `Unknown agent for --agent: ${cliAgent}`);
+    error(`Agents:  ${KNOWN_AGENTS.join(", ")}`);
+    process.exit(1);
+  }
+  const configAgent = readConfiguredDefaultAgent();
+  if (configAgent !== null && !isKnownAgent(configAgent)) {
+    error(`Unknown "defaultAgent" in ${CONFIG_FILE}: ${configAgent}`);
+    error(`Agents:  ${KNOWN_AGENTS.join(", ")}`);
+    process.exit(1);
+  }
+  const declaredAgent = resolveDeclaredAgent({ cliAgent, configAgent });
+  const gate = gateFor(declaredAgent);
+  if (!agentInstalled(gate.agent)) {
+    missingAgentMessage(gate, agentBin(gate.agent)).forEach((line) => error(line));
+    process.exit(1);
+  }
+  log(gate.declared ? `Default agent: ${gate.agent} ✓` : "Claude Code CLI ✓");
+  return declaredAgent;
+}
+
 // `npx mulmoterminal init` — idempotent first-run setup. Environment/CLI checks + the
 // optional interactive-config launch live here (PATH-command detection); the config
 // derivation + write is the tsx-run server/cli-init.ts.
@@ -190,7 +229,7 @@ async function runInit(initArgs) {
   const nodeOk = nodeMeetsMinimum(process.versions.node);
   console.log(nodeOk ? `  ✓ Node ${process.versions.node}` : `  ✗ Node ${process.versions.node} — MulmoTerminal needs ≥ ${MIN_NODE_LABEL}`);
 
-  const hasClaude = claudeInstalled();
+  const hasClaude = agentInstalled("claude");
   if (hasClaude) {
     console.log("  ✓ Claude Code CLI");
   } else {
@@ -436,7 +475,8 @@ function announceReady(url, note, noOpen) {
 // the port was taken at bind time before it became ready — the caller then
 // reports that and stops. In every other case (clean shutdown, fatal error,
 // or the server simply running) the process exits with the server's code.
-function runServer(port, probedAddress, localhostIsUnambiguous, noOpen, cwd, onChild) {
+function runServer(port, probedAddress, localhostIsUnambiguous, noOpen, launch, onChild) {
+  const { cwd, declaredAgent } = launch;
   return new Promise((resolveExit) => {
     log(`Starting MulmoTerminal on port ${port}...`);
     // stderr is piped (and passed through) so a fatal boot error can be inspected once the
@@ -444,7 +484,7 @@ function runServer(port, probedAddress, localhostIsUnambiguous, noOpen, cwd, onC
     // and without reading stderr the launcher cannot tell that from a real bug.
     // The .env comes from where the user ran the command — the spawn's own cwd is the
     // package directory, so serverNodeArgs makes that path absolute (#795).
-    const server = spawn(process.execPath, serverNodeArgs(SERVER_ENTRY, process.cwd(), port), {
+    const server = spawn(process.execPath, serverNodeArgs(SERVER_ENTRY, process.cwd(), port, declaredAgent), {
       cwd: PKG_DIR,
       env: serverSpawnEnv(process.env, cwd),
       // "ipc" is the fourth entry and the reason the readiness check can stop guessing: the
@@ -552,6 +592,10 @@ Commands:
                     Needs a running server
 
 Options:
+  --agent <id>      Which agent a new cell starts as, and the one start-up checks for
+                    instead of Claude Code (claude, codex, antigravity, grok, muse,
+                    copilot, cursor). Also settable as "defaultAgent" in
+                    ~/.mulmoterminal/config.json; this flag wins and is not saved.
   --cwd <dir>       Working directory claude runs in (default: current directory; relative paths allowed)
   --port <number>   Server port (default: ${DEFAULT_PORT}; the PORT environment variable is
                     used when this flag is absent). If it is in use, you are asked
@@ -618,12 +662,7 @@ async function main() {
 
   checkForUpdate();
 
-  if (!claudeInstalled()) {
-    error("Claude Code CLI not found.");
-    error("Install it first:  npm install -g @anthropic-ai/claude-code  &&  claude auth login");
-    process.exit(1);
-  }
-  log("Claude Code CLI ✓");
+  const declaredAgent = passStartupGate(args);
 
   if (!existsSync(SERVER_ENTRY)) {
     error(`Server entry not found at ${SERVER_ENTRY}`);
@@ -662,7 +701,7 @@ async function main() {
   // loses this terminal has something to search for (#1820). The server child names itself the
   // same, so `pkill mulmoterminal` reaches whichever half is found first.
   setProcessTitle(port);
-  await runServer(port, probedAddress, localhostIsUnambiguous, noOpen, cwd, (c) => {
+  await runServer(port, probedAddress, localhostIsUnambiguous, noOpen, { cwd, declaredAgent }, (c) => {
     child = c;
   });
   error(portInUseMessage(port, portExplicit));