mulmoterminal 1.5.0 → 1.6.0

package/README.md

@@ -94,6 +94,19 @@ listener and needs a browser **on the host**. Either way it needs a Desktop OAut
 as `~/.secrets/client_secret_*.json`; the refresh token lands in `~/.config/mulmo/google-token.json`
 and is **shared with MulmoClaude**, so one link per machine covers both apps.
 
+**Local models (optional).** The package also ships `claude-ollama` — a one-command launcher that
+runs Claude Code **fully locally against an [Ollama](https://ollama.com) model** (no cloud, no API
+key). It starts a large-context Ollama server and launches `claude` with a minimal system prompt so
+small models aren't drowned:
+
+```bash
+ollama pull qwen3:4b
+npx -p mulmoterminal claude-ollama qwen3:4b   # or, if installed globally: claude-ollama qwen3:4b
+```
+
+See [Local models with claude-ollama](https://receptron.github.io/mulmoterminal/guide/en/claude-ollama.html)
+for the details and model notes.
+
 > **Already linked before the calendar-list / colour features?** They need a read scope your existing
 > link doesn't have, so `listCalendars` (and, in practice, `colors`) fail with an insufficient-scope
 > 403 until you re-authorize: **Settings → Google account → Unlink**, then sign in again (or re-run
@@ -225,6 +238,17 @@ today — **Claude Code** (the default) and **Codex**.
 cell's launch form and the Collections browser carry a **Claude / Codex** toggle (your
 choice is remembered).
 
+**Other models.**
+Claude Code can run against any **Anthropic-compatible** backend (OpenRouter, Moonshot, a
+LiteLLM gateway). Backends are listed in `~/.mulmoterminal/config.json` under `providers`,
+and their **keys are read from the server's environment** — never from a file the app
+serves. A directory sets its default in `.mulmoterminal.json` (`provider` / `model`), and
+each grid cell's launch form has a **MODEL** select that overrides it for one session,
+listing ~27 curated models with the measured pass rate of a real tool-using task beside
+each. A provider whose token can't be resolved **refuses to start** rather than falling
+back to Anthropic, and providers can't be combined with the Docker sandbox. Full walkthrough — setup, the measured model list, adding your own models, troubleshooting:
+[Using another model via OpenRouter](https://receptron.github.io/mulmoterminal/guide/en/providers.html).
+
 **Skills for Codex.** Codex has no `/<slug>` slash commands, so on session setup
 MulmoTerminal **mirrors the workspace's `.claude/skills` into `~/.codex/skills`** (each
 mirrored directory carries a `.mt-mirror` marker so a re-sync overwrites what MulmoTerminal
@@ -668,8 +692,10 @@ Each grid cell's header shows two badges for its session, refreshed when a turn
 
 - **Context badge** — e.g. `Opus · ctx 35%`: the model family plus how full its context
   window is (the *last* turn's input + cache tokens ÷ the model's window — **1M** for
-  current-gen Opus / Sonnet / Fable, **200k** otherwise; an unknown model shows the label
-  with no %).
+  current-gen Opus / Sonnet / Fable, **200k** otherwise). A session running on a
+  [provider model](#agents-claude--codex) shows that model's name and its published window
+  (`Kimi K2.7 Code · ctx 12%`); a model in neither list keeps the label and hides the %,
+  since the window is never guessed.
 - **Token badge** — `⇡<in> ⇣<out>`: cumulative input (fresh + cache-read + cache-creation)
   and output tokens for the session, k/M-formatted, with a full breakdown in the tooltip.
 
@@ -938,8 +964,9 @@ same-origin-guarded.
 
 | Endpoint | Purpose |
 | -------- | ------- |
-| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `prRepos`, `launchers`, `userMcpServers`). |
+| `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `prRepos`, `launchers`, `userMcpServers`, `providers`). |
 | `GET /api/sound` · `/api/dir-sound?cwd=` · `/api/dir-config?cwd=` | Custom / per-directory attention sound + per-dir config. |
+| `GET /api/launch-options` | The Anthropic-compatible backends this server can reach, each with its models and — when it can't — the reason. Reports the **name** of the env var a key is read from, never the key. |
 | `GET /api/notifications`(`/history`) · `POST /api/notifications/:id/clear` | Notification feed. |
 | `POST /api/transcribe`(`/model`…) | Voice-input transcription (Whisper, macOS). |
 | `POST /api/translation` | Runtime UI-string translation. |

package/bin/claude-ollama.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+// `claude-ollama <model> [claude args…]` — run Claude Code fully locally against an
+// Ollama-served model. Ollama 0.31+ serves a native Anthropic-compatible `/v1/messages`, so
+// Claude Code connects directly; this launcher just sets up the three things that make it
+// actually work with a small local model:
+//   1. a dedicated large-context `ollama serve` (the 4096 default overflows Claude's prompt),
+//   2. `--bare --disable-slash-commands` so the system prompt is small enough for the model,
+//   3. the env recipe (unset ANTHROPIC_API_KEY, point ANTHROPIC_BASE_URL at the local server).
+
+import { execSync, spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { get as httpGet } from "node:http";
+import { parseClaudeOllamaArgs, buildClaudeEnv, buildOllamaServeEnv, buildClaudeArgs, modelIsInstalled, OLLAMA_CONTEXT_LENGTH } from "./ollama-launch.js";
+
+const log = (msg) => console.log(`\x1b[36m[claude-ollama]\x1b[0m ${msg}`);
+const error = (msg) => console.error(`\x1b[31m[claude-ollama]\x1b[0m ${msg}`);
+
+const READY_TIMEOUT_MS = 20_000;
+const READY_POLL_MS = 400;
+
+function printHelp() {
+  console.log(
+    [
+      "Usage: claude-ollama <model> [claude args…]",
+      "",
+      "Run Claude Code against a local Ollama model — no cloud, no API key.",
+      "Starts a dedicated large-context Ollama server on a private port and launches",
+      "Claude Code with a minimal system prompt (--bare) so small models aren't drowned.",
+      "",
+      "Examples:",
+      "  claude-ollama qwen3:4b",
+      '  claude-ollama qwen3:30b-a3b "refactor this module"',
+      "",
+      "Notes:",
+      "  - The model must be pulled first:  ollama pull <model>",
+      "  - Validate a model through a real multi-turn tool run; small ones vary.",
+    ].join("\n"),
+  );
+}
+
+function hasCommand(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// A free TCP port for the private ollama server, so an Ollama the user already runs (11434)
+// is left alone.
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const probe = createServer();
+    probe.once("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+      const { port } = probe.address();
+      probe.close(() => resolve(port));
+    });
+  });
+}
+
+// GET a small JSON endpoint on the local server, best-effort (null on any failure).
+function getJson(port, path, timeout_ms = 2000) {
+  return new Promise((resolve) => {
+    const req = httpGet({ host: "127.0.0.1", port, path, timeout: timeout_ms }, (res) => {
+      let body = "";
+      res.on("data", (chunk) => (body += chunk));
+      res.on("end", () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+async function waitUntilReady(port) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < READY_TIMEOUT_MS) {
+    if (await getJson(port, "/api/version")) return true;
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+  return false;
+}
+
+function requireCommands() {
+  if (!hasCommand("ollama")) {
+    error("`ollama` not found on PATH. Install it: https://ollama.com/download");
+    process.exit(1);
+  }
+  if (!hasCommand("claude")) {
+    error("`claude` (Claude Code) not found. Install it: npm install -g @anthropic-ai/claude-code");
+    process.exit(1);
+  }
+}
+
+// Start the private ollama server and return a `stop` that kills it. The stop is wired to
+// this process's own exit and signals so the server never outlives the launcher.
+function startPrivateOllama(host) {
+  const serve = spawn("ollama", ["serve"], {
+    stdio: "ignore",
+    env: buildOllamaServeEnv(process.env, host, OLLAMA_CONTEXT_LENGTH),
+  });
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    try {
+      serve.kill("SIGTERM");
+    } catch {
+      // already gone
+    }
+  };
+  process.on("exit", stop);
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      stop();
+      process.exit(signal === "SIGINT" ? 130 : 143);
+    });
+  }
+  serve.on("error", (e) => {
+    error(`failed to start ollama serve: ${e.message}`);
+    process.exit(1);
+  });
+  return stop;
+}
+
+// Hand off to interactive Claude Code; exit with its code and stop our server behind it.
+function runClaude(model, baseUrl, claudeArgs, stopServe) {
+  log(`launching Claude Code on ${model} (minimal prompt: --bare --disable-slash-commands)`);
+  const claude = spawn("claude", buildClaudeArgs(claudeArgs), {
+    stdio: "inherit",
+    env: buildClaudeEnv(process.env, model, baseUrl),
+  });
+  claude.on("error", (e) => {
+    error(`failed to launch claude: ${e.message}`);
+    stopServe();
+    process.exit(1);
+  });
+  claude.on("exit", (code) => {
+    stopServe();
+    process.exit(code ?? 0);
+  });
+}
+
+async function main() {
+  const { help, model, claudeArgs } = parseClaudeOllamaArgs(process.argv.slice(2));
+  if (help || !model) {
+    printHelp();
+    process.exit(help ? 0 : 1);
+  }
+  requireCommands();
+  const port = await findFreePort();
+  const host = `127.0.0.1:${port}`;
+  log(`starting a private Ollama server on ${host} (context ${OLLAMA_CONTEXT_LENGTH})…`);
+  const stopServe = startPrivateOllama(host);
+  if (!(await waitUntilReady(port))) {
+    error("the Ollama server did not become ready in time");
+    stopServe();
+    process.exit(1);
+  }
+  const tags = await getJson(port, "/api/tags");
+  if (tags && !modelIsInstalled(tags, model)) {
+    error(`model '${model}' is not installed. Pull it first:  ollama pull ${model}`);
+    stopServe();
+    process.exit(1);
+  }
+  runClaude(model, `http://${host}`, claudeArgs, stopServe);
+}
+
+main().catch((e) => {
+  error(e?.message || String(e));
+  process.exit(1);
+});

package/bin/cli-args.d.ts

@@ -0,0 +1,11 @@
+export type PortChoice = { port: number; explicit: boolean } | { error: string };
+export type CwdChoice = { path: string; mustExist: boolean } | { error: string };
+export declare function parsePortArg(args: string[], defaultPort: number): PortChoice;
+export declare function chooseCwd(args: string[], env: Record<string, string | undefined>): CwdChoice;
+export declare function portInUseMessage(port: number, explicit: boolean): string;
+export declare function portInUseAction(explicit: boolean, isTTY: boolean | undefined): "ask" | "stop";
+export declare function secondInstancePrompt(port: number): string;
+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;

package/bin/cli-args.js

@@ -0,0 +1,135 @@
+// What the launcher decides before it starts anything, kept out of the executable so each
+// decision can be checked without a process to exit or a terminal to type into.
+//
+// `--cwd` picks the workspace claude runs in and whose sessions the sidebar lists, so it is
+// a data-scope boundary: getting it wrong points the whole app at someone else's project.
+// `--port` decides whether a clash is a hard error or a silent retry. Both used to be
+// decided inside the executable, where they exit the process on a bad value and so could not
+// be checked at all (#611 A3).
+//
+// These return a decision; the caller prints and exits. Nothing here reads argv, the
+// environment or the filesystem.
+
+/**
+ * Which port the launcher should ask for.
+ * `--port` must be a plain integer in range: a value that merely starts with digits ("80x")
+ * or carries a sign or padding ("+80", "080") is a typo, and silently launching on 80 is
+ * worse than saying so.
+ */
+export function parsePortArg(args, defaultPort) {
+  const at = args.indexOf("--port");
+  if (at === -1) return { port: defaultPort, explicit: false };
+  const raw = args[at + 1];
+  const parsed = Number.parseInt(raw ?? "", 10);
+  if (!Number.isInteger(parsed) || String(parsed) !== raw || parsed < 1 || parsed > 65535) {
+    return { error: `Invalid --port value: "${raw ?? ""}" (expected integer 1..65535)` };
+  }
+  return { port: parsed, explicit: true };
+}
+
+/**
+ * Which directory to run in, before it is made absolute.
+ * Precedence: `--cwd` (relative allowed) > CLAUDE_CWD > the directory the launcher was run
+ * from. `mustExist` is set only for `--cwd`: a typo there should stop the launch, while a
+ * CLAUDE_CWD naming a directory that isn't there yet is the managed-workspace case the
+ * server creates on boot.
+ */
+export function chooseCwd(args, env) {
+  const at = args.indexOf("--cwd");
+  if (at === -1) return { path: env.CLAUDE_CWD ?? ".", mustExist: false };
+  const value = args[at + 1];
+  // A missing value swallows the next flag ("--cwd --port 3000" would run in a directory
+  // called "--port"), so anything flag-shaped is treated as absent.
+  if (value === undefined || value.startsWith("-")) return { error: "--cwd requires a directory path" };
+  return { path: value, mustExist: true };
+}
+
+/**
+ * What to say when the port is taken.
+ *
+ * Running a second server is not a supported setup: both share ~/.mulmoterminal and the
+ * workspace, but each keeps its own PTYs, pub/sub and in-memory caches, so the two disagree
+ * about state neither can see the other change. Starting one silently on another port —
+ * which is what a plain second `npx mulmoterminal` used to do — is how someone ends up in
+ * that setup without knowing (#611).
+ *
+ * So the message has to answer the two things the user actually wants: where the running one
+ * is, and how to insist if a second is really wanted.
+ */
+export function portInUseMessage(port, explicit) {
+  const lines = [`Port ${port} is already in use.`];
+  lines.push(`  If that is MulmoTerminal, it is already running at http://localhost:${port}`);
+  lines.push(explicit ? "  Pick a different --port, or stop the other process." : "  To start a second one anyway: --port <number>");
+  return lines.join("\n");
+}
+
+/**
+ * What to do when the wanted port is taken: "ask" whether to start a second instance,
+ * or "stop".
+ *
+ * Two conditions rule the question out. An explicit --port already named the port that
+ * was wanted, so offering a different one answers a question nobody asked; and with no
+ * terminal to type into (a script, a service, CI) a prompt has nobody to answer it and
+ * would hang the start instead of failing it.
+ */
+export function portInUseAction(explicit, isTTY) {
+  return explicit || !isTTY ? "stop" : "ask";
+}
+
+/**
+ * The question asked when the default port is taken and there is somebody to answer.
+ *
+ * Two servers is not a supported setup (#611), but it is a legitimate thing to want on
+ * purpose — so the answer is a question rather than a refusal, and the default is no.
+ */
+export function secondInstancePrompt(port) {
+  return [`Port ${port} is already in use — MulmoTerminal may already be running at http://localhost:${port}`, "Start a second instance anyway? [y/N] "].join(
+    "\n",
+  );
+}
+
+/**
+ * Whether an answer to that question is a yes.
+ *
+ * Only an explicit yes counts. The prompt says [y/N], so Enter — and anything unrecognised —
+ * means no: starting a second server by misreading a stray keystroke is the outcome worth
+ * avoiding, and saying no costs one retyped command.
+ */
+export function saysYes(answer) {
+  return /^y(es)?$/i.test(String(answer ?? "").trim());
+}
+
+/**
+ * What someone who said yes should know before the second one comes up.
+ *
+ * One line, and only the part that is still true: config and the hidden-session list are
+ * safe across instances, but a session's tool history is cached per process and its live
+ * updates never cross — so the instance that did not start a session shows a frozen history
+ * for it (#611).
+ */
+export const SECOND_INSTANCE_NOTE = [
+  "  Note: both share ~/.mulmoterminal. A session's tool history does not live-update",
+  "  in the instance that did not start it.",
+].join("\n");
+
+const MIN_NODE_MAJOR = 22;
+const MIN_NODE_MINOR = 9;
+
+/**
+ * The lowest Node the `init` check reports as good, for the "needs ≥ x.y" line.
+ */
+export const MIN_NODE_LABEL = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}`;
+
+/**
+ * Whether the running Node is new enough for the `init` pre-flight tick.
+ *
+ * `process.versions.node` is "major.minor.patch", with a "-prerelease" tag on the patch for
+ * nightlies ("22.9.0-nightly…"). Only major.minor gate, and Number.parseInt stops at the
+ * first non-digit, so that tag never reaches the comparison. A string that is not a version
+ * parses to NaN, and every comparison against NaN is false, so an unreadable version reads as
+ * "below minimum" — the safe direction for a display-only check.
+ */
+export function nodeMeetsMinimum(version) {
+  const [major, minor] = version.split(".").map((part) => Number.parseInt(part, 10));
+  return major > MIN_NODE_MAJOR || (major === MIN_NODE_MAJOR && minor >= MIN_NODE_MINOR);
+}

package/bin/mulmoterminal.js

@@ -13,14 +13,24 @@ import { createServer } from "node:net";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
-import { fetchLatestVersion, isNewerVersion } from "./update-check.js";
+import { computeUpdateNotice, isUpdateCheckDisabled } from "./update-check.js";
+import {
+  chooseCwd,
+  parsePortArg,
+  portInUseAction,
+  portInUseMessage,
+  saysYes,
+  secondInstancePrompt,
+  SECOND_INSTANCE_NOTE,
+  nodeMeetsMinimum,
+  MIN_NODE_LABEL,
+} from "./cli-args.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_DIR = join(__dirname, "..");
 const SERVER_ENTRY = join(PKG_DIR, "server", "index.ts");
 const DEFAULT_PORT = 34567;
 const READY_TIMEOUT_MS = 15_000;
-const MAX_BIND_RETRIES = 5;
 // Server exit code meaning "port taken at bind time" — keep in sync with
 // server/index.ts (PORT_IN_USE_EXIT_CODE).
 const PORT_IN_USE_EXIT_CODE = 75;
@@ -32,19 +42,18 @@ const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 const log = (msg) => console.log(`\x1b[36m[mulmoterminal]\x1b[0m ${msg}`);
 const error = (msg) => console.error(`\x1b[31m[mulmoterminal]\x1b[0m ${msg}`);
 
-// Non-blocking notice when a newer version is published — `npm i -g` never
-// auto-updates. Opt out via MULMOTERMINAL_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER.
-function checkForUpdate() {
-  if (process.env.MULMOTERMINAL_NO_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER) return;
-  fetchLatestVersion()
-    .then((latest) => {
-      if (latest && isNewerVersion(latest, VERSION)) {
-        log(`\x1b[33mUpdate available: ${VERSION} → ${latest}  ·  run: npm i -g mulmoterminal\x1b[0m`);
-      }
-    })
-    .catch(() => {
-      // best-effort; never disrupt startup
-    });
+// Non-blocking console notice that a newer version exists — neither `npm i -g` nor a git
+// checkout auto-updates. Opt out via MULMOTERMINAL_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER. The
+// same check runs in the server for the web-header badge (the launcher isn't involved under
+// `yarn dev`), sharing computeUpdateNotice so the two never drift.
+async function checkForUpdate() {
+  if (isUpdateCheckDisabled(process.env)) return;
+  try {
+    const notice = await computeUpdateNotice(PKG_DIR, VERSION);
+    if (notice) log(`\x1b[33m${notice}\x1b[0m`);
+  } catch {
+    // best-effort; never disrupt startup
+  }
 }
 
 // Detect a CLI on the user's PATH by asking for its version. Intentionally resolves from
@@ -52,7 +61,6 @@ function checkForUpdate() {
 // `init` checks.
 function hasCommand(cmd, versionArg = "--version") {
   try {
-    // eslint-disable-next-line sonarjs/no-os-command-from-path
     execSync(`${cmd} ${versionArg}`, { stdio: "pipe" });
     return true;
   } catch {
@@ -69,7 +77,7 @@ function promptYesNo(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     rl.question(question, (answer) => {
       rl.close();
-      res(/^y(es)?$/i.test(answer.trim()));
+      res(saysYes(answer));
     });
   });
 }
@@ -80,9 +88,8 @@ function promptYesNo(question) {
 async function runInit(initArgs) {
   log("Setting up MulmoTerminal…\n");
 
-  const [maj, min] = process.versions.node.split(".").map((n) => Number.parseInt(n, 10));
-  const nodeOk = maj > 22 || (maj === 22 && min >= 9);
-  console.log(nodeOk ? `  ✓ Node ${process.versions.node}` : `  ✗ Node ${process.versions.node} — MulmoTerminal needs ≥ 22.9`);
+  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();
   if (hasClaude) {
@@ -120,7 +127,6 @@ async function runInit(initArgs) {
   // must never block waiting on stdin.
   if (hasClaude && process.stdin.isTTY && (await promptYesNo("\nConfigure interactively now with the /mulmoterminal-config skill? [y/N] "))) {
     log("Launching Claude — use  /mulmoterminal-config  (or just ask it to configure MulmoTerminal).");
-    // eslint-disable-next-line sonarjs/no-os-command-from-path
     spawn("claude", ["Use the mulmoterminal-config skill to configure MulmoTerminal."], { stdio: "inherit" });
     return;
   }
@@ -164,23 +170,6 @@ function isPortFree(port) {
   });
 }
 
-// Ask the OS for a free port (listen on 0) and return the one it assigned, or
-// null. An effectively-random fallback when the preferred port is taken; the
-// bind-retry in main() closes the small probe-to-bind race so concurrent starts
-// don't clash.
-function findEphemeralPort() {
-  return new Promise((resolve) => {
-    const probe = createServer();
-    probe.once("error", () => resolve(null));
-    probe.once("listening", () => {
-      const addr = probe.address();
-      const assigned = addr && typeof addr === "object" ? addr.port : null;
-      probe.close(() => resolve(assigned));
-    });
-    probe.listen(0);
-  });
-}
-
 // Poll the server until it answers, then call onReady; give up after the timeout
 // so the launcher never hangs on a crash loop. Returns a cancel function — a
 // raced/abandoned attempt stops polling so it can't fire a stale banner.
@@ -220,60 +209,65 @@ function printReadyBanner(url) {
   console.log(`${bar}\n`);
 }
 
-function parsePortArg(args) {
-  const idx = args.indexOf("--port");
-  if (idx === -1) return { requestedPort: DEFAULT_PORT, portExplicit: false };
-  const raw = args[idx + 1];
-  const parsed = Number.parseInt(raw ?? "", 10);
-  if (!Number.isInteger(parsed) || String(parsed) !== raw || parsed < 1 || parsed > 65535) {
-    error(`Invalid --port value: "${raw ?? ""}" (expected integer 1..65535)`);
+// The two flag decisions live in cli-args.js so they can be checked without a process to
+// exit; this turns a decision into the message and the exit.
+function decideOrExit(choice) {
+  if ("error" in choice) {
+    error(choice.error);
     process.exit(1);
   }
-  return { requestedPort: parsed, portExplicit: true };
+  return choice;
 }
 
 // Resolve the workspace directory claude runs in (and whose sessions the sidebar
-// lists). Precedence: --cwd (relative paths allowed) > CLAUDE_CWD env > the
-// directory npx was run from. Always returned absolute. An explicit --cwd that
-// isn't an existing directory is a hard error (catches typos before launch).
+// lists), always absolute. An explicit --cwd that isn't an existing directory is a hard
+// error (catches typos before launch); an inherited one is the workspace the server creates.
 function resolveCwd(args) {
-  const idx = args.indexOf("--cwd");
-  let flagValue;
-  if (idx !== -1) {
-    flagValue = args[idx + 1];
-    if (flagValue === undefined || flagValue.startsWith("-")) {
-      error("--cwd requires a directory path");
-      process.exit(1);
-    }
-  }
-  const chosen = flagValue ?? process.env.CLAUDE_CWD ?? ".";
+  const { path: chosen, mustExist } = decideOrExit(chooseCwd(args, process.env));
   const abs = resolve(process.cwd(), chosen);
-  if (idx !== -1 && (!existsSync(abs) || !statSync(abs).isDirectory())) {
+  if (mustExist && (!existsSync(abs) || !statSync(abs).isDirectory())) {
     error(`--cwd is not a directory: ${abs}`);
     process.exit(1);
   }
   return abs;
 }
 
+// Ask the OS for a free port (listen on 0) and return the one it assigned, or null. Only
+// reached once someone has said yes to a second instance.
+function findEphemeralPort() {
+  return new Promise((resolve) => {
+    const probe = createServer();
+    probe.once("error", () => resolve(null));
+    probe.once("listening", () => {
+      const { port } = probe.address();
+      probe.close(() => resolve(port));
+    });
+    probe.listen(0);
+  });
+}
+
 async function choosePort(requested, explicit) {
   if (await isPortFree(requested)) return requested;
-  if (explicit) {
-    error(`Port ${requested} is already in use. Stop the other process or pick a different --port.`);
+  // No SILENT fallback: starting a second server on another port without saying so is how
+  // someone ends up with two sharing one home directory without knowing (#611).
+  if (portInUseAction(explicit, process.stdin.isTTY) === "stop") {
+    error(portInUseMessage(requested, explicit));
     process.exit(1);
   }
+  if (!(await promptYesNo(secondInstancePrompt(requested)))) process.exit(1);
   const fallback = await findEphemeralPort();
   if (fallback === null) {
-    error(`Port ${requested} is in use and no free port could be found.`);
+    error("No free port could be found for a second instance.");
     process.exit(1);
   }
-  log(`Port ${requested} busy → using ${fallback} instead. (Pass --port <N> to pin.)`);
+  log(SECOND_INSTANCE_NOTE);
   return fallback;
 }
 
 // Spawn the server on `port` and report the child via `onChild` (so signal
 // handlers target the live process). Resolves only when the server exits because
 // the port was taken at bind time before it became ready — the caller then
-// retries on a fresh port. In every other case (clean shutdown, fatal error,
+// 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, noOpen, cwd, onChild) {
   return new Promise((resolveExit) => {
@@ -326,7 +320,9 @@ Commands:
 
 Options:
   --cwd <dir>       Working directory claude runs in (default: current directory; relative paths allowed)
-  --port <number>   Server port (default: ${DEFAULT_PORT}; a free port is chosen if it's busy)
+  --port <number>   Server port (default: ${DEFAULT_PORT}). If it is in use, you are asked
+                    whether to start a second instance on a free port; with --port, or
+                    with no terminal to ask, startup stops instead.
   --no-open         Don't open the browser automatically
   --version         Show version
   --help            Show this help
@@ -369,7 +365,7 @@ async function main() {
     process.exit(1);
   }
 
-  const { requestedPort, portExplicit } = parsePortArg(args);
+  const { port: requestedPort, explicit: portExplicit } = decideOrExit(parsePortArg(args, DEFAULT_PORT));
   const noOpen = args.includes("--no-open");
   const cwd = resolveCwd(args);
   log(`Workspace: ${cwd}`);
@@ -383,27 +379,14 @@ async function main() {
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
 
-  // Start on the chosen port; if the server loses the rare probe-to-bind race,
-  // fall back to a fresh OS-assigned port and retry. An explicit --port is not
-  // second-guessed. `runServer` only returns when the port was raced.
-  let port = await choosePort(requestedPort, portExplicit);
-  for (let attempt = 0; attempt <= MAX_BIND_RETRIES; attempt++) {
-    await runServer(port, noOpen, cwd, (c) => {
-      child = c;
-    });
-    if (portExplicit) {
-      error(`Port ${port} is already in use. Stop the other process or pick a different --port.`);
-      process.exit(1);
-    }
-    const next = await findEphemeralPort();
-    if (next === null) {
-      error("No free port available to retry on.");
-      process.exit(1);
-    }
-    log(`Port ${port} was taken at bind time → retrying on ${next}.`);
-    port = next;
-  }
-  error(`Could not bind a free port after ${MAX_BIND_RETRIES + 1} attempts.`);
+  // The probe above can still lose to something binding the port in the same instant, in
+  // which case the server exits 75 and runServer returns. Same answer as the probe: say who
+  // has it rather than moving to a port nobody asked for.
+  const port = await choosePort(requestedPort, portExplicit);
+  await runServer(port, noOpen, cwd, (c) => {
+    child = c;
+  });
+  error(portInUseMessage(port, portExplicit));
   process.exit(1);
 }