multiclaw 0.3.2 → 0.4.0

package/README.md

@@ -9,13 +9,21 @@ Multi-agent orchestration CLI. Define a pipeline of AI agents, give them a requi
 
 ## Prerequisites
 
-At least one AI runtime must be installed:
-
-| Runtime | Install |
-|---------|---------|
-| `claude` (default) | `npm install -g @anthropic-ai/claude-code` |
-
-> **Future support:** We plan to add support for additional runtimes (Codex, OpenCode, Cursor) in upcoming releases.
+multiclaw orchestrates agents from any installed **provider**. Every provider talks
+to multiclaw over the same [Agent Client Protocol (ACP)](https://agentclientprotocol.com)
+— the underlying *runtime* is always `acp`; the **provider** is the agent product you
+choose. Install one or more:
+
+| Provider | CLI | Install |
+|----------|-----|---------|
+| OpenCode | `opencode` | `npm install -g opencode` |
+| Claude | `claude-agent-acp` (bundled) | install the Claude Code CLI (`claude`) and run `claude` to log in |
+| Codex | `codex-acp` (bundled) | install the Codex CLI (`codex`) and run `codex login` |
+| Cursor | `cursor-agent` | `curl https://cursor.com/install \| bash` |
+
+`multiclaw init` auto-detects which providers are installed and only offers those;
+`multiclaw doctor` shows the full picture (installed versions, auth hints, available
+models). Codex and Cursor need an API key or login before they can run.
 
 ## Install
 
@@ -29,11 +37,15 @@ npm install -g multiclaw
 # 1. Scaffold a config in the current directory
 multiclaw init
 
-# 2. Run an orchestration
-multiclaw run "Build a REST API for a todo list" --ui
+# 2. Open the interactive console
+multiclaw
+
+# ...or run a single orchestration headlessly
+multiclaw run "Build a REST API for a todo list"
 ```
 
-`--ui` opens a real-time Dashboard in the browser. Omit it to run headless.
+`multiclaw` with no subcommand opens a full-screen terminal console. Use `multiclaw run` for
+headless execution (CI, piped output).
 
 ## Commands
 
@@ -45,6 +57,20 @@ Prompts:
 - **Project name** — defaults to the current directory name
 - **Preset** — pipeline template (see [Presets](#presets))
 - **Work directory** — where agents read and write files
+- **Provider** — which agent product to use (`claude`, `opencode`, `codex`, `cursor`). Only installed providers are offered; missing ones are listed with install hints.
+- **Model preference** — role-based tier defaults (recommended) or a specific tier/model
+- **Per-agent overrides** (optional) — pick individual agents and set a model for each
+
+### `multiclaw doctor`
+
+Diagnose the local environment: which providers are installed (with versions), what auth
+each needs, how many models each exposes, and whether the current config's agents all
+resolve to an installed provider. Exits non-zero if no provider is available.
+
+```bash
+multiclaw doctor            # full environment check
+multiclaw doctor --config ./multiclaw.config.ts   # also validates the config
+```
 
 ### `multiclaw run <requirement> [options]`
 
@@ -53,24 +79,11 @@ Runs the orchestration defined in your config file.
 | Option | Description |
 |--------|-------------|
 | `--config <path>` | Path to config file. Auto-discovers `multiclaw.config.ts` if omitted. |
-| `--ui` | Start the Dashboard server and open it in the browser. |
-| `--port <port>` | Dashboard port. Requires `--ui`. Default: `3210`. |
-| `--server-url <url>` | Stream events to a running `multiclaw serve` instance. |
-| `--no-leader` | Skip the leader agent and use the default pipeline directly. |
+| `--no-leader` | (Batch mode only) Skip the leader and run the full configured team. Has no effect in the interactive console — the leader is always used there. |
 
 The `<requirement>` string is injected into every agent's prompt as `{{requirement}}`.
 
-Each run creates an isolated timestamped subdirectory inside `workDir` (e.g. `workspace/run-2026-10-08T12-00-00`).
-
-### `multiclaw serve [options]`
-
-Start a persistent Dashboard server. Useful for CI or when you want a permanent URL to monitor runs.
-
-| Option | Description |
-|--------|-------------|
-| `--port <port>` | Port to listen on. Default: `3210`. |
-
-Connect a run to it with `multiclaw run "..." --server-url http://localhost:3210`.
+Each run creates an isolated timestamped subdirectory inside `workDir` (e.g. `workspace/.multiclaw/runs/run-2026-10-08T12-00-00`).
 
 ## Config file
 
@@ -96,18 +109,21 @@ export default defineConfig({
   continueOnError: false,   // optional; keep running if an agent fails
   maxConcurrency: 4,        // optional; max agents running at once
 
-  dashboard: {
-    port: 3210,
-    autoOpen: true,
+  // Project-wide defaults applied to every agent that doesn't override them.
+  // One line replaces repeating provider/model across all preset agents.
+  defaults: {
+    provider: "claude",     // which agent product runs the team
+    model: "sonnet",        // default model (overridable per agent)
   },
 
   agents: [
     {
       id: "architect",        // unique identifier, used in dependsOn
       name: "Architect",      // display name
-      icon: "◆",              // optional; shown in terminal and dashboard
-      runtime: "claude",      // optional; default: "claude"
-      model: "opus",          // optional; override default model for this agent
+      icon: "◆",              // optional; shown in the console
+      provider: "claude",     // optional; default: config.defaults.provider
+      modelTier: "strong",    // optional; "strong" | "balanced" | "fast"
+      model: "opus",          // optional; overrides tier/default for this agent
       systemPrompt: "You are a software architect.", // optional
       taskPrompt: `Design the system for {{requirement}}.
 Read the brief at {{file:brief.md}} and write architecture.md.`,
@@ -133,30 +149,32 @@ Read the brief at {{file:brief.md}} and write architecture.md.`,
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `name` | string | ✓ | Project name, shown in the dashboard. |
-| `workDir` | string | ✓ | Base directory where agents read and write files. |
+| `name` | string | ✓ | Project name, shown in the console header. |
+| `workDir` | string | ✓ | Base directory where agents read and write files. Every console turn shares it. |
 | `agents` | AgentDefinition[] | ✓ | The agent pipeline (see Agent fields below). |
 | `leader` | AgentDefinition | | Optional routing agent (see [Leader](#leader)). |
 | `useLeader` | boolean | | Enable or disable the leader agent. Default: `true` when leader is configured. |
+| `defaults` | object | | Project-wide `{ provider?, model?, command? }` applied to every agent that does not override them. Keeps generated configs short. |
 | `context` | Record<string, string> | | Variables available as `{{key}}` in every prompt. `requirement` is injected automatically. |
 | `logDir` | string | | Log output directory. Default: `workDir/.multiclaw/logs`. |
 | `continueOnError` | boolean | | Keep running when an agent fails. Default: `false`. |
 | `maxConcurrency` | number | | Max agents running in parallel. Default: unlimited. |
-| `dashboard.port` | number | | Dashboard port. Default: `3210`. |
-| `dashboard.autoOpen` | boolean | | Open the dashboard in a browser automatically. Default: `true`. |
 
 ### Agent fields
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `id` | string | ✓ | Unique identifier. Used in `dependsOn`. |
-| `name` | string | ✓ | Display name shown in terminal and dashboard. |
+| `name` | string | ✓ | Display name shown in the agent list. |
 | `taskPrompt` | string | ✓ | Prompt sent to the AI runtime. Supports template variables. |
 | `systemPrompt` | string | | Optional system prompt prepended to `taskPrompt`. |
 | `icon` | string | | Unicode icon shown next to the agent name. |
-| `runtime` | string | | `claude` (default). Additional runtimes coming soon. |
-| `model` | string | | Override the default model for this agent. E.g. `"opus"`, `"sonnet"`, `"haiku"`. Takes precedence over `models`. |
-| `models` | Record<string, string> | | Map of runtime names to model names. Used when `model` is not set. E.g. `{ claude: "opus", openai: "gpt-4" }`. |
+| `description` | string | | One-line role, shown beside the agent's name on the console's first screen. Every built-in preset sets one. |
+| `provider` | string | | Agent product this agent runs on: `claude`, `opencode`, `codex`, or `cursor`. Defaults to `config.defaults.provider`. All providers speak the same `acp` runtime. |
+| `runtime` | string | | **Legacy.** Always `"acp"` today. Use `provider` instead. Retained for backward compatibility. |
+| `modelTier` | `"strong"` \| `"balanced"` \| `"fast"` | | Declares the capability this agent needs; the catalog maps each tier to a provider-specific model id. Ignored when `model` is set. |
+| `model` | string | | Override the model id for this agent (provider-specific, e.g. `"opus"`, `"sonnet"`, `"haiku"` for Claude). Takes precedence over `modelTier` and `models`. |
+| `models` | Record<string, string> | | Map of provider id (or the legacy `"acp"`) to a model id, e.g. `{ claude: "sonnet", opencode: "opencode/big-pickle" }`. Used when `model`/`modelTier` are unset. |
 | `tools` | string[] | | Allowed tools. Default: `["Read", "Write", "Bash"]`. |
 | `dependsOn` | string[] | | Agent ids that must complete before this agent starts. |
 | `timeout` | number | | Per-agent timeout in ms. Default: `600000` (10 min). |
@@ -184,16 +202,122 @@ Stage 3:  backend-developer  │  ui-designer      ← parallel
 Stage 4:  code-reviewer      │  devops            ← parallel
 ```
 
-## Dashboard
+## Interactive console
 
-The real-time web UI shows:
+`multiclaw` with no subcommand opens a full-screen terminal console. It is a **turn-based
+conductor loop**, not a chat: each turn you type is one complete orchestration run of the whole
+pipeline, and the console stays open so you can run the next one.
 
-- Stage timeline with agent status (running / done / failed / skipped)
-- Live streaming logs per agent
-- Per-agent duration and retry count
-- Elapsed time while running; total time on completion
+```
+◆ multiclaw · dev-team                                          turn 2 · 00:12
+────────────────────────────────────────────────────────────────────────────
+✓ ◆ Leader  ──▸ ① ⠹ ◇ Architect  ──▸ ② ○ ◇ Developer  ──▸ ③ ○ ◇ Reviewer
+
+TEAM                1/4 │ Architect · sonnet-4 · ⠹ running          4.2s ▼
+  ✓ ◆ Leader       3.1s │ Read packages/core/src/orchestrator/…
+› ⠹ ◇ Architect    4.2s │ Grep "withTimeout" in packages/core/src
+  ○ ◇ Developer       — │ Edit utils/timeout.ts — abort-safe
+  ○ ◇ Reviewer        — │ Bash pnpm -r test
+
+» also add tests
+› type to queue a follow-up…
+⠹ running 4.2s · 1/4 agents · 1 queued          enter queues · ctrl+c cancel
+```
 
-Start it with `--ui` on `run`, or run `multiclaw serve` for a persistent instance.
+| Region | Shows |
+|--------|-------|
+| Header | Project name, turn number, and the phase or elapsed time |
+| Pipeline rail | The leader, then each stage in order, joined by `──▸` |
+| Team panel | One row per agent: status glyph, name, live time, and progress (`1/4`) |
+| Stream panel | Live output of the focused agent, with a `▼` live / `⏸` parked marker |
+| Reply panel | What the leader answered, when a turn needed no pipeline |
+| Review banner | `viewing turn N …` while a past turn is open |
+| Queue strip | Follow-ups typed mid-run, in the order they will run |
+| Prompt | Where you type — live even while a turn is running |
+| Hint bar | Aggregate status on the left, the keys that work *right now* on the right |
+
+Status glyphs: `○` queued · `◐` running (a spinner while live) · `↻` retrying · `✓` done ·
+`✗` failed · `⊘` skipped.
+
+**First run.** Before the first turn the body shows the team from your config — each agent with the
+`description` of what it is for — rather than an empty pane. `tab` moves the `›` caret down the list;
+once a turn is running the caret follows whichever agent is speaking.
+
+**Not every turn needs the team.** The leader decides that first. Ask it a question, or say hello,
+and it answers in prose: the body swaps to the reply, the footer reads `✓ answered`, and no agent
+runs. When the request is a real task but too vague to plan, the leader asks instead — the footer
+reads `? needs your input` and your next line is the answer.
+
+### Keys
+
+The prompt always holds focus, so exactly two keys are reserved: `?` and `/`, and only while the
+line is empty *and* the console is idle. Everything else is a named key or an ordinary character,
+which is what keeps typing a requirement from tripping over shortcuts.
+
+| Key | Action |
+|-----|--------|
+| `enter` | Run the typed requirement — or queue it while a turn is running |
+| `tab` / `shift+tab` | Cycle the focused agent |
+| `↑` `↓` `pgup` `pgdn` | Scroll the focused agent's stream |
+| `←` `→` `home` `end` | Move the caret |
+| `esc` | Stop reading a past turn, clear the line, or close an overlay |
+| `?` | Key map (idle, empty line only) |
+| `/` | Command menu (empty line only) |
+| `ctrl+l` | Clear the focused agent's log |
+| `ctrl+c` | Cancel the running turn *and its queue*; again when idle to quit |
+
+Scrolling up parks the stream and scrolling back to the bottom resumes it, so there is no follow
+toggle to remember. While a turn runs the pane follows whichever agent starts next, until you cycle
+the focus by hand.
+
+**Typing while the team works.** The prompt stays live. Anything you submit mid-run joins the queue
+strip above it and starts as the next turn the moment the console goes idle — so a thought you have
+while watching the output is never lost. Cancelling drops the queue with the turn, since "cancel"
+should mean stop.
+
+Cancelling aborts the in-flight agents and their child processes rather than leaving them running in
+the background.
+
+### Commands
+
+Type `/` on an empty line for a filtered list.
+
+| Command | Action |
+|---------|--------|
+| `/agents` | List the configured team |
+| `/focus <id>` | Focus an agent by id |
+| `/clear` | Clear the focused agent's log |
+| `/history` | Browse finished turns |
+| `/cancel` | Cancel the running turn and its queue |
+| `/help` | Key map |
+| `/quit` | Exit |
+
+The console renders on the alternate screen buffer, so your shell scrollback is preserved.
+
+### Workspace
+
+The console is iterative, so every turn runs against the **same** `workDir` — a follow-up like "now
+add tests for that" sees the files the previous turn wrote. `task-plan.json` is cleared at the start
+of each turn so a plan left over from an earlier requirement can never be re-applied. Only the logs
+are per-run: `workDir/.multiclaw/runs/run-<timestamp>/logs/`.
+
+`multiclaw run` is deliberately different: it sandboxes each invocation in its own
+`run-<timestamp>/` directory.
+
+### History
+
+`/history` lists finished turns newest first, with each turn's outcome, duration, agent count and
+requirement. `↑` `↓` select and `enter` opens one for reading — the panes render that turn behind a
+`viewing turn N` banner, and `esc` returns to the live turn. Scrolling and `tab` apply to what you
+are reading, never to the turn that is still running. The turn on screen is not listed, and the last
+20 finished turns are kept.
+
+On a narrow terminal (under 72 columns) the team panel is dropped and the stream takes the full
+width; on a short one (under 16 rows) the pipeline rail goes too. The header, prompt and hint bar are
+never dropped.
+
+> **No TTY?** The console needs an interactive terminal. In CI, in a pipe, or over a non-TTY SSH
+> session it exits with a message pointing at `multiclaw run`, which runs the same pipeline headless.
 
 ## Logs
 
@@ -229,7 +353,24 @@ Presets are pipeline templates you can pick during `multiclaw init`:
 
 ## Leader
 
-The `leader` field adds a routing agent that runs **before** the main pipeline. It reads the requirement and inspects the codebase, then decides which agents are actually needed for this task. Agents the leader omits are skipped.
+The `leader` field adds a routing agent that runs **before** the main pipeline. It reads the requirement and inspects the codebase, then decides what the turn actually needs:
+
+| Decision | Meaning |
+|----------|---------|
+| `run` | It is a task the leader can scope — name the minimum set of agents needed |
+| `reply` | A greeting or a question it can answer on the spot; no agent runs |
+| `ask` | A real task, but too vague to plan; it asks the one question that unblocks it |
+
+The leader is asked for a single JSON object:
+
+```json
+{"mode": "run", "run": ["backend-developer", "code-reviewer"]}
+{"mode": "reply", "message": "Hi — ask me for a change to this project."}
+{"mode": "ask", "message": "Which database should I target?"}
+```
+
+A bare `{"run": [...]}` with no `mode` is still accepted as a run. Anything else the leader writes is
+treated as its answer, so a leader that replies in prose still ends the turn in words.
 
 ```typescript
 export default defineConfig({
@@ -243,9 +384,9 @@ export default defineConfig({
 })
 ```
 
-For a minor bug fix the leader might decide only `backend-developer` and `code-reviewer` are needed, skipping the design stages. For a greenfield feature it runs the full pipeline.
+For a minor bug fix the leader might decide only `backend-developer` and `code-reviewer` are needed, skipping the design stages. For a greenfield feature it runs the full pipeline. For `hello` it answers, and nobody is spent on it.
 
-If the leader fails or produces invalid output, multiclaw falls back to running all agents.
+Agent IDs are always a **subset** of the configured team: an invented id is reported and dropped, never added. A `run` naming no configured agent is a failure, not a green "done". If the leader cannot be reached at all, multiclaw warns and falls back to the full configured team.
 
 ### Disabling the leader
 
@@ -319,7 +460,8 @@ See [`examples/dev-team/`](https://github.com/shipengqi/multiclaw/tree/main/exam
 
 ```bash
 cd examples/dev-team
-pnpm dev
+pnpm dev        # opens the interactive console
+pnpm run run    # ...or one headless run
 ```
 
 ## License

package/dist/index.js

@@ -1,19 +1,25 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command } from "commander";
 import { readFileSync } from "fs";
 import { dirname as dirname2, join as join3 } from "path";
 import { fileURLToPath } from "url";
+import { Command } from "commander";
 
-// src/commands/run.ts
-import * as path3 from "path";
-import { Orchestrator as OrchestratorImpl, runtimeRegistry } from "@multiclawcli/core";
+// src/commands/doctor.ts
+import {
+  detectProviders,
+  presentProviders,
+  resolveProvider,
+  specForProvider
+} from "@multiclawcli/core";
 
 // src/loader/loadConfig.ts
-import * as path from "path";
 import * as fs from "fs";
+import { createRequire } from "module";
+import * as path from "path";
 var DEFAULT_CONFIG_NAMES = ["multiclaw.config.ts", "multiclaw.config.js"];
+var CONFIG_HELPER_SPECIFIERS = ["multiclaw", "@multiclawcli/core"];
 function findConfig(configPath) {
   if (configPath) {
     const abs = path.resolve(process.cwd(), configPath);
@@ -24,19 +30,51 @@ function findConfig(configPath) {
     const abs = path.resolve(process.cwd(), name);
     if (fs.existsSync(abs)) return abs;
   }
-  throw new Error(`No config file found. Create multiclaw.config.ts in the current directory or use --config to specify a path.`);
+  throw new Error(
+    `No config file found. Create multiclaw.config.ts in the current directory or use --config to specify a path.`
+  );
 }
-async function loadConfig(configPath, requirement) {
-  const absPath = findConfig(configPath);
-  const { register } = await import("tsx/esm/api");
-  const unregister = register();
-  let mod;
+function resolveHelpersEntry() {
   try {
-    mod = await import(absPath);
-  } finally {
-    unregister();
+    return createRequire(import.meta.url).resolve("@multiclawcli/core");
+  } catch {
+    return void 0;
+  }
+}
+async function importConfig(absPath) {
+  const { createJiti } = await import("jiti");
+  const helpers = resolveHelpersEntry();
+  const jiti = createJiti(import.meta.url, {
+    interopDefault: true,
+    ...helpers ? { alias: Object.fromEntries(CONFIG_HELPER_SPECIFIERS.map((name) => [name, helpers])) } : {}
+  });
+  try {
+    return await jiti.import(absPath);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      [
+        `Failed to load config: ${absPath}`,
+        `  ${detail.split("\n")[0]}`,
+        `  Check the file for syntax errors, and that every package it imports is installed.`
+      ].join("\n")
+    );
   }
-  const config = mod.default ?? mod.config;
+}
+function unwrapConfig(mod) {
+  let value = mod;
+  for (let depth = 0; depth < 3; depth += 1) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) break;
+    const record = value;
+    const next = "default" in record ? record.default : record.config;
+    if (!next || typeof next !== "object" || Array.isArray(next)) break;
+    value = next;
+  }
+  return value;
+}
+async function loadConfig(configPath, requirement) {
+  const absPath = findConfig(configPath);
+  const config = unwrapConfig(await importConfig(absPath));
   if (!config || !Array.isArray(config.agents)) {
     throw new Error(`Invalid config format \u2014 expected: export default defineConfig({...})`);
   }
@@ -48,6 +86,361 @@ async function loadConfig(configPath, requirement) {
   return config;
 }
 
+// src/commands/doctor.ts
+function buildDoctorReport(detected, config) {
+  const present = presentProviders(detected);
+  const providers = detected.map((d) => {
+    const spec = specForProvider(d.id);
+    return {
+      id: d.id,
+      label: d.label,
+      status: d.status,
+      command: d.command,
+      version: d.version,
+      modelCount: spec?.models.length ?? 0,
+      modelSelection: spec?.modelSelection ?? "none",
+      authHint: spec?.auth.hint ?? "",
+      installHint: d.status === "missing" ? spec?.install.hint : void 0
+    };
+  });
+  const installedCount = present.length;
+  let configReport;
+  if (config) {
+    const defaultsProvider = config.defaults?.provider;
+    const defaultsProviderOk = !defaultsProvider || present.includes(defaultsProvider);
+    const agents2 = [...config.agents];
+    if (config.leader) agents2.push(config.leader);
+    const agentsWithMissingProvider = agents2.map((a) => ({ id: a.id, intended: resolveProvider(a, config) })).filter((a) => !present.includes(a.intended)).map((a) => a.id);
+    configReport = {
+      name: config.name,
+      defaultsProvider,
+      defaultsProviderOk,
+      agentsWithMissingProvider
+    };
+  }
+  return {
+    providers,
+    installedCount,
+    config: configReport,
+    runnable: installedCount > 0
+  };
+}
+var GREEN = "\x1B[32m";
+var RED = "\x1B[31m";
+var YELLOW = "\x1B[33m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
+var ANSI_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+function color(enabled, code, text) {
+  return enabled ? `${code}${text}${RESET}` : text;
+}
+function formatDoctorReport(report, useColor = true) {
+  const lines = [];
+  const c = (code, text) => color(useColor, code, text);
+  const cell = (text, width, code) => {
+    const rendered = code ? color(useColor, code, text) : text;
+    const visible = text.replace(ANSI_RE, "").length;
+    return rendered + " ".repeat(Math.max(0, width - visible));
+  };
+  lines.push("");
+  lines.push(c(DIM, "multiclaw doctor \u2014 environment check"));
+  lines.push("");
+  lines.push(`${cell("provider", 12)}${cell("status", 10)}${cell("version", 14)}models  auth`);
+  for (const p of report.providers) {
+    const mark = p.status === "present" ? "\u2713 present" : "\u2717 missing";
+    const markCode = p.status === "present" ? GREEN : RED;
+    const version = p.version ?? (p.status === "present" ? "" : "\u2014");
+    const models = p.modelSelection === "none" ? "n/a" : String(p.modelCount);
+    const auth = p.authHint ? c(DIM, p.authHint) : "";
+    lines.push(
+      `${cell(p.label, 12)}${cell(mark, 10, markCode)}${cell(version, 14)}${cell(models, 7)}${auth}`
+    );
+    if (p.status === "missing" && p.installHint) {
+      lines.push(c(YELLOW, `  install: ${p.installHint}`));
+    }
+  }
+  if (report.config) {
+    lines.push("");
+    lines.push(c(DIM, `config: ${report.config.name ?? "(unnamed)"}`));
+    if (report.config.defaultsProvider) {
+      const ok = report.config.defaultsProviderOk;
+      lines.push(
+        `  default provider: ${report.config.defaultsProvider} ${ok ? c(GREEN, "\u2713 installed") : c(RED, "\u2717 not installed")}`
+      );
+    }
+    if (report.config.agentsWithMissingProvider.length > 0) {
+      lines.push(
+        c(
+          RED,
+          `  ${report.config.agentsWithMissingProvider.length} agent(s) need a provider that is not installed: ${report.config.agentsWithMissingProvider.join(", ")}`
+        )
+      );
+    } else {
+      lines.push(c(GREEN, "  all agents resolve to an installed provider \u2713"));
+    }
+  }
+  lines.push("");
+  if (report.runnable) {
+    lines.push(
+      c(
+        GREEN,
+        `\u2713 ${report.installedCount} of ${report.providers.length} providers available \u2014 multiclaw can run.`
+      )
+    );
+  } else {
+    lines.push(c(RED, `\u2717 no providers installed \u2014 install one of the above to run multiclaw.`));
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+async function doctorCommand(configPath) {
+  const detected = await detectProviders({ withVersion: true });
+  const config = await loadConfigSafe(configPath);
+  const report = buildDoctorReport(detected, config);
+  const useColor = !process.env.NO_COLOR && process.stdout.isTTY;
+  console.log(formatDoctorReport(report, useColor));
+  process.exitCode = report.runnable ? 0 : 1;
+}
+async function loadConfigSafe(configPath) {
+  try {
+    return await loadConfig(configPath);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/commands/init.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { checkbox, input, Separator, select } from "@inquirer/prompts";
+import { detectProviders as detectProviders2, specForProvider as specForProvider2, tierModel } from "@multiclawcli/core";
+var AGENT_BLOCKS = {
+  backend: `    agents.productManager(),
+    agents.architect({ dependsOn: ["product-manager"] }),
+    agents.archDesignReviewer({ dependsOn: ["architect"] }),
+    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
+    agents.tester({ dependsOn: ["backend-developer"] }),
+    agents.codeReviewer({ dependsOn: ["tester"] }),
+    agents.devops({ dependsOn: ["tester"] }),`,
+  frontend: `    agents.architect(),
+    agents.uiDesigner({ dependsOn: ["architect"] }),
+    agents.uiDesignReviewer({ dependsOn: ["ui-designer"] }),
+    agents.frontendDeveloper({ dependsOn: ["ui-design-reviewer"] }),
+    agents.tester({ dependsOn: ["frontend-developer"] }),
+    agents.codeReviewer({ dependsOn: ["tester"] }),`,
+  fullstack: `    agents.productManager(),
+    agents.architect({ dependsOn: ["product-manager"] }),
+    agents.archDesignReviewer({ dependsOn: ["architect"] }),
+    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
+    agents.uiDesigner({ dependsOn: ["arch-design-reviewer"] }),
+    agents.uiDesignReviewer({ dependsOn: ["ui-designer"] }),
+    agents.frontendDeveloper({ dependsOn: ["backend-developer", "ui-design-reviewer"] }),
+    agents.tester({ dependsOn: ["frontend-developer"] }),
+    agents.codeReviewer({ dependsOn: ["tester"] }),
+    agents.devops({ dependsOn: ["tester"] }),`
+};
+var PRESET_DESCRIPTIONS = {
+  backend: "Product Manager \u2192 Architect \u2192 Arch Design Reviewer \u2192 Backend Developer \u2192 Tester \u2192 Code Reviewer + DevOps  (7 agents)",
+  frontend: "Architect \u2192 UI Designer \u2192 UI Design Reviewer \u2192 Frontend Developer \u2192 Tester \u2192 Code Reviewer  (6 agents)",
+  fullstack: "Product Manager \u2192 Architect \u2192 Arch Design Reviewer \u2192 Backend Developer + UI Designer \u2192 UI Design Reviewer \u2192 Frontend Developer \u2192 Tester \u2192 Code Reviewer + DevOps  (10 agents)"
+};
+function generateConfig(opts) {
+  const name = JSON.stringify(opts.projectName);
+  const workDir = JSON.stringify(opts.workDir);
+  const defaultsParts = [`provider: ${JSON.stringify(opts.provider)}`];
+  if (opts.model) defaultsParts.push(`model: ${JSON.stringify(opts.model)}`);
+  let agentBlock = AGENT_BLOCKS[opts.preset];
+  if (opts.overrides && opts.overrides.length > 0) {
+    for (const ov of opts.overrides) {
+      const id = ov.id;
+      const model = JSON.stringify(ov.model);
+      const re = new RegExp(`(agents\\.${id}\\([^)]*\\))`, "g");
+      agentBlock = agentBlock.replace(re, (match) => {
+        const inner = match.slice(id.length + 8, -1);
+        const sep = inner.trim() ? ", " : "";
+        return `agents.${id}({ ${inner}${sep}model: ${model} })`;
+      });
+    }
+  }
+  return `import { defineConfig, agents } from "multiclaw"
+
+export default defineConfig({
+  name: ${name},
+  workDir: ${workDir},
+  context: {
+    projectName: ${name},
+  },
+  defaults: {
+    ${defaultsParts.join(",\n    ")},
+  },
+  agents: [
+${agentBlock}
+  ],
+})
+`;
+}
+async function initCommand() {
+  const configPath = path2.resolve(process.cwd(), "multiclaw.config.ts");
+  if (fs2.existsSync(configPath)) {
+    console.error("\x1B[31mError: multiclaw.config.ts already exists\x1B[0m");
+    process.exit(1);
+  }
+  const defaultProjectName = path2.basename(process.cwd());
+  const projectName = await input({
+    message: "Project name:",
+    default: defaultProjectName
+  });
+  const preset = await select({
+    message: "Select a preset:",
+    choices: [
+      { value: "backend", name: `backend    \u2014 ${PRESET_DESCRIPTIONS.backend}` },
+      { value: "frontend", name: `frontend   \u2014 ${PRESET_DESCRIPTIONS.frontend}` },
+      { value: "fullstack", name: `fullstack  \u2014 ${PRESET_DESCRIPTIONS.fullstack}` }
+    ]
+  });
+  const detected = await detectProviders2({ withVersion: true });
+  const provider = await select({
+    message: "Which agent?",
+    choices: detected.map((d) => ({
+      value: d.id,
+      name: d.status === "present" ? `${d.label}  (${d.command}${d.version ? ` ${d.version}` : ""})` : `${d.label}  (not installed)`,
+      disabled: false
+    }))
+  });
+  const spec = specForProvider2(provider);
+  if (!spec) {
+    throw new Error(`Unknown provider: ${provider}`);
+  }
+  const modelAnswer = await select({
+    message: "Team model preference:",
+    choices: [
+      { value: "", name: "Role-based tier defaults (recommended)" },
+      new Separator("---"),
+      ...[
+        { label: "Strong (architect, devops)", tier: "strong" },
+        { label: "Balanced (backend, frontend)", tier: "balanced" },
+        { label: "Fast (reviewer, tester)", tier: "fast" }
+      ].map((t) => {
+        const m = tierModel(spec, t.tier);
+        return m ? { value: m, name: `${t.label}  \u2192  ${m}` } : void 0;
+      }).filter((x) => x !== void 0),
+      new Separator("---"),
+      ...spec.models.map((m) => ({ value: m.id, name: m.label }))
+    ]
+  });
+  const modelDefault = modelAnswer || void 0;
+  const overrideIds = await checkbox({
+    message: "Override model for specific agents? (space to select, enter to confirm)",
+    choices: [
+      { value: "leader", name: "\u2605 Leader" },
+      { value: "productManager", name: "Product Manager" },
+      { value: "architect", name: "Architect" },
+      { value: "archDesignReviewer", name: "Arch Design Reviewer" },
+      { value: "backendDeveloper", name: "Backend Developer" },
+      { value: "frontendDeveloper", name: "Frontend Developer" },
+      { value: "uiDesigner", name: "UI Designer" },
+      { value: "uiDesignReviewer", name: "UI Design Reviewer" },
+      { value: "tester", name: "Tester" },
+      { value: "codeReviewer", name: "Code Reviewer" },
+      { value: "devops", name: "DevOps" }
+    ]
+  });
+  const overrides = [];
+  for (const id of overrideIds) {
+    const ov = await select({
+      message: `Model for ${id}:`.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()),
+      choices: spec.models.map((m) => ({ value: m.id, name: m.label }))
+    });
+    overrides.push({ id, model: ov });
+  }
+  const workDir = await input({
+    message: "Work directory (where agents read and write files):",
+    default: "."
+  });
+  try {
+    fs2.writeFileSync(
+      configPath,
+      generateConfig({ preset, workDir, projectName, provider, model: modelDefault, overrides })
+    );
+    if (workDir !== ".") {
+      fs2.mkdirSync(path2.resolve(process.cwd(), workDir), { recursive: true });
+    }
+  } catch (err) {
+    console.error(`\x1B[31mError: Failed to create files: ${err.message}\x1B[0m`);
+    process.exit(1);
+  }
+  const detectedProvider = detected.find((d) => d.id === provider);
+  console.log("");
+  console.log(`\x1B[32m\u2713\x1B[0m Created multiclaw.config.ts`);
+  console.log(`  preset:   ${preset}  (${PRESET_DESCRIPTIONS[preset]})`);
+  console.log(`  agent:    ${spec.label}`);
+  if (detectedProvider?.status === "present") {
+    console.log(
+      `            ${detectedProvider.command}${detectedProvider.version ? ` ${detectedProvider.version}` : ""}`
+    );
+  }
+  console.log(`  model:    ${modelDefault || "role-based tier defaults"}`);
+  console.log(`  workDir:  ${workDir}`);
+  if (overrides.length > 0) {
+    console.log(`  overrides: ${overrides.map((o) => `${o.id}=${o.model}`).join(", ")}`);
+  }
+  console.log("");
+  if (detectedProvider?.status === "missing") {
+    console.log(`\x1B[33m\u26A0 ${spec.label} is not installed.\x1B[0m`);
+    console.log(`  ${spec.install.hint}`);
+    console.log("");
+  }
+  if (detectedProvider?.note) {
+    console.log(`\x1B[2m  Before your first run: ${detectedProvider.note}\x1B[0m`);
+    console.log("");
+  }
+  console.log(`> Run: multiclaw            (interactive console)`);
+  console.log(`       multiclaw run "..."  (headless)`);
+  console.log("");
+  console.log(
+    `\x1B[2mTip: the CLI resolves the "multiclaw" import itself, so the config runs either way.\x1B[0m`
+  );
+  console.log(
+    `\x1B[2m     \`npm i -D multiclaw\` adds editor autocomplete for defineConfig/agents.\x1B[0m`
+  );
+}
+
+// src/commands/run.ts
+import * as path4 from "path";
+import { Orchestrator as OrchestratorImpl } from "@multiclawcli/core";
+
+// src/lib.ts
+import {
+  detectProviders as detectProviders3,
+  presentProviders as presentProviders2,
+  resolveCommand,
+  runtimeRegistry
+} from "@multiclawcli/core";
+import { agents, defineConfig } from "@multiclawcli/core";
+async function assertRuntimesAvailable(config) {
+  const checked = /* @__PURE__ */ new Set();
+  for (const agent of config.agents) {
+    const name = agent.runtime ?? "acp";
+    if (!runtimeRegistry.has(name)) {
+      const supported = runtimeRegistry.list().join(", ");
+      console.error(`\x1B[31mError: Unknown runtime "${name}". Supported: ${supported}\x1B[0m`);
+      process.exit(1);
+    }
+    const command = resolveCommand(agent, config);
+    const key = `${name}\0${command}`;
+    if (checked.has(key)) continue;
+    checked.add(key);
+    const info = await runtimeRegistry.get(name).describe({ command });
+    if (!info.available) {
+      const subject = `Command "${command}"`;
+      console.error(
+        `\x1B[31mError: ${subject} is not available. Make sure the CLI is installed.\x1B[0m`
+      );
+      process.exit(1);
+    }
+  }
+}
+
 // src/reporters/ConsoleReporter.ts
 var isFancy = !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY === true;
 var S = isFancy ? { ok: "\u2713", fail: "\u2717", run: "\u203A", retry: "\u21BB", skip: "\u2298", warn: "\u26A0", bullet: "\xB7" } : { ok: "+", fail: "x", run: ">", retry: "~", skip: "-", warn: "!", bullet: "*" };
@@ -83,8 +476,16 @@ var ConsoleReporter = class {
 ${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`);
         console.log(`${edge[1]}  ${S.run} ${e.payload.name.padEnd(46)}${edge[1]}`);
         console.log(`${edge[2]}${line}${edge[4]}${C.reset}`);
-        console.log(`${C.cyan}${S.bullet} Agents: ${e.payload.totalAgents}  Stages: ${e.payload.stages.length}${C.reset}
-`);
+        console.log(
+          `${C.cyan}${S.bullet} Agents: ${e.payload.totalAgents}  Stages: ${e.payload.stages.length}${C.reset}
+`
+        );
+        break;
+      }
+      case "orchestration:stages": {
+        console.log(
+          `${C.dim}${S.bullet} Plan applied \u2014 ${e.payload.stages.length} stages${C.reset}`
+        );
         break;
       }
       case "stage:start": {
@@ -114,14 +515,25 @@ ${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`);
         break;
       }
       case "agent:retrying": {
-        console.log(`${C.yellow}${S.retry} ${e.payload.agentName} retry ${e.payload.attempt}/${e.payload.maxAttempts}: ${e.payload.error}${C.reset}`);
+        console.log(
+          `${C.yellow}${S.retry} ${e.payload.agentName} retry ${e.payload.attempt}/${e.payload.maxAttempts}: ${e.payload.error}${C.reset}`
+        );
+        break;
+      }
+      case "orchestration:warning": {
+        console.log(`${C.yellow}${S.warn} ${e.payload.message}${C.reset}`);
         break;
       }
       case "orchestration:complete": {
-        const { success, totalDuration, agentResults } = e.payload;
+        const { success, totalDuration, agentResults, reply } = e.payload;
+        if (reply) {
+          const mark = reply.mode === "ask" ? "?" : S.ok;
+          console.log(`
+${C.cyan}${mark} ${reply.message}${C.reset}`);
+        }
         const line = (isFancy ? "\u2550" : "=").repeat(50);
         const edge = isFancy ? ["\u2554", "\u2551", "\u255A", "\u2557", "\u255D"] : ["+", "|", "+", "+", "+"];
-        const title = success ? `${S.ok} All done` : `${S.warn} Done (with failures)`;
+        const title = reply ? reply.mode === "ask" ? `${S.warn} Needs your input` : `${S.ok} Answered` : success ? `${S.ok} All done` : `${S.warn} Done (with failures)`;
         console.log(`
 ${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`);
         console.log(`${edge[1]}  ${title.padEnd(48)}${edge[1]}`);
@@ -131,9 +543,11 @@ ${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`);
         console.log(`  ~ ${"Total".padEnd(nameWidth)}   ${totalStr.padStart(7)}`);
         for (const r of agentResults) {
           const icon = r.status === "success" ? S.ok : S.fail;
-          const color = r.status === "success" ? C.green : C.red;
+          const color2 = r.status === "success" ? C.green : C.red;
           const dur = `${(r.duration / 1e3).toFixed(1)}s`;
-          console.log(`  ${color}${icon}${C.reset} ${r.agentName.padEnd(nameWidth)}   ${dur.padStart(7)}`);
+          console.log(
+            `  ${color2}${icon}${C.reset} ${r.agentName.padEnd(nameWidth)}   ${dur.padStart(7)}`
+          );
         }
         console.log();
         break;
@@ -143,250 +557,136 @@ ${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`);
 };
 
 // src/reporters/FileLogWriter.ts
-import * as fs2 from "fs";
-import * as path2 from "path";
+import * as fs3 from "fs";
+import * as path3 from "path";
 var FileLogWriter = class {
-  constructor(logDir) {
+  constructor(logDir, onError = (message) => process.stderr.write(`
+[multiclaw] ${message}
+`)) {
     this.logDir = logDir;
+    this.onError = onError;
     this.streams = /* @__PURE__ */ new Map();
-    fs2.mkdirSync(logDir, { recursive: true });
+    /** Agent ids whose log could not be opened — never retried, so a broken
+     *  directory does not produce one failing stream per output chunk. */
+    this.failed = /* @__PURE__ */ new Set();
+    fs3.mkdirSync(logDir, { recursive: true });
   }
   attach(eventBus) {
     return eventBus.subscribe((e) => this.handle(e));
   }
+  /**
+   * Flush every open stream.
+   *
+   * `stream.end()` only *starts* the flush, so a caller that exits the moment
+   * `orchestration:complete` arrives can lose the tail of the last agent's log.
+   * Awaiting this is what makes that tail durable.
+   */
+  async drain() {
+    if (!this.closing) this.closing = this.flush();
+    await this.closing;
+  }
   handle(e) {
     if (e.type === "agent:output") {
-      this.getStream(e.payload.agentId).write(e.payload.chunk);
+      this.getStream(e.payload.agentId)?.write(e.payload.chunk);
     }
     if (e.type === "orchestration:complete") {
-      fs2.writeFileSync(
-        path2.join(this.logDir, "report.json"),
-        JSON.stringify(e.payload, null, 2)
-      );
-      this.closeAll();
+      try {
+        fs3.writeFileSync(path3.join(this.logDir, "report.json"), JSON.stringify(e.payload, null, 2));
+      } catch (err) {
+        this.onError(`Could not write report.json: ${errorMessage(err)}`);
+      }
+      this.closing ??= this.flush();
     }
   }
   getStream(agentId) {
-    if (!this.streams.has(agentId)) {
-      this.streams.set(
-        agentId,
-        fs2.createWriteStream(path2.join(this.logDir, `${agentId}.log`))
-      );
+    if (this.failed.has(agentId)) return void 0;
+    let stream = this.streams.get(agentId);
+    if (!stream) {
+      stream = fs3.createWriteStream(path3.join(this.logDir, `${agentId}.log`));
+      stream.on("error", (err) => {
+        this.failed.add(agentId);
+        this.streams.delete(agentId);
+        this.onError(`Could not write ${agentId}.log: ${errorMessage(err)}`);
+      });
+      this.streams.set(agentId, stream);
     }
-    return this.streams.get(agentId);
+    return stream;
   }
-  closeAll() {
-    for (const s of this.streams.values()) s.end();
+  flush() {
+    const streams = [...this.streams.values()];
     this.streams.clear();
+    return Promise.all(
+      streams.map(
+        (s) => new Promise((resolve3) => {
+          if (s.destroyed || s.writableEnded) {
+            resolve3();
+            return;
+          }
+          s.end(() => resolve3());
+        })
+      )
+    ).then(() => void 0);
   }
 };
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 
 // src/commands/run.ts
+var EXIT_CANCELLED = 130;
 async function runCommand(requirement, options) {
   const config = await loadConfig(options.config, requirement);
   if (options.noLeader) {
     config.useLeader = false;
   }
   const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
-  config.workDir = path3.join(config.workDir, ".multiclaw", "runs", `run-${ts}`);
-  const runtimeNames = new Set(config.agents.map((a) => a.runtime ?? "claude"));
-  for (const name of runtimeNames) {
-    let rt;
-    try {
-      rt = runtimeRegistry.get(name);
-    } catch {
-      console.error(`\x1B[31mError: Unknown runtime "${name}". Supported: claude\x1B[0m`);
-      process.exit(1);
-    }
-    if (!await rt.checkAvailable()) {
-      console.error(`\x1B[31mError: Runtime "${name}" is not available. Make sure the CLI is installed.\x1B[0m`);
-      process.exit(1);
-    }
-  }
+  config.workDir = path4.join(config.workDir, ".multiclaw", "runs", `run-${ts}`);
+  await assertRuntimesAvailable(config);
   const orchestrator = new OrchestratorImpl(config);
   new ConsoleReporter().attach(orchestrator.eventBus);
-  const logDir = config.logDir ?? path3.join(config.workDir, "logs");
-  new FileLogWriter(logDir).attach(orchestrator.eventBus);
+  const logDir = config.logDir ?? path4.join(config.workDir, "logs");
+  const logs = new FileLogWriter(logDir);
+  logs.attach(orchestrator.eventBus);
   console.log(`\x1B[2mLogs: ${logDir}\x1B[0m`);
-  if (options.ui && options.serverUrl) {
-    console.warn("\x1B[33mWarning: --ui and --server-url cannot be used together. Using --ui.\x1B[0m");
-  }
-  if (options.ui) {
-    await attachDashboard(orchestrator, config, options);
-  } else if (options.serverUrl) {
-    await attachRemoteServer(orchestrator, options.serverUrl);
-  }
-  const result = await orchestrator.run();
-  process.exit(result.success ? 0 : 1);
-}
-async function attachDashboard(orchestrator, config, options) {
-  const { DashboardServer } = await import("@multiclawcli/dashboard/server");
-  const port = options.port ?? config.dashboard?.port ?? 3210;
-  const server = new DashboardServer({ port });
-  await server.start();
-  server.bindEventBus(orchestrator.eventBus);
-  const url = `http://localhost:${port}`;
-  console.log(`\x1B[36mDashboard: ${url}\x1B[0m`);
-  if (config.dashboard?.autoOpen ?? true) {
-    const { default: open } = await import("open");
-    await open(url);
-  }
-}
-async function attachRemoteServer(orchestrator, serverUrl) {
-  const { WebSocket } = await import("ws");
-  const wsUrl = serverUrl.replace(/^https?/, (p) => p === "https" ? "wss" : "ws");
-  const ws = new WebSocket(wsUrl);
-  await new Promise((resolve3, reject) => {
-    const timer = setTimeout(() => reject(new Error(`Connection to serve timed out: ${serverUrl}`)), 5e3);
-    ws.on("open", () => {
-      clearTimeout(timer);
-      resolve3();
-    });
-    ws.on("error", (err) => {
-      clearTimeout(timer);
-      reject(err);
-    });
-  });
-  console.log(`\x1B[36mConnected to Dashboard server: ${serverUrl}\x1B[0m`);
-  orchestrator.eventBus.subscribe((e) => {
-    if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(e));
-  });
-}
-
-// src/commands/init.ts
-import * as fs3 from "fs";
-import * as path4 from "path";
-import { execSync } from "child_process";
-import { select, input } from "@inquirer/prompts";
-var AGENT_BLOCKS = {
-  simple: `    agents.architect(),
-    agents.archDesignReviewer({ dependsOn: ["architect"] }),
-    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
-    agents.codeReviewer({ dependsOn: ["backend-developer"] }),`,
-  backend: `    agents.productManager(),
-    agents.architect({ dependsOn: ["product-manager"] }),
-    agents.archDesignReviewer({ dependsOn: ["architect"] }),
-    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
-    agents.tester({ dependsOn: ["backend-developer"] }),
-    agents.codeReviewer({ dependsOn: ["tester"] }),
-    agents.devops({ dependsOn: ["tester"] }),`,
-  fullstack: `    agents.productManager(),
-    agents.architect({ dependsOn: ["product-manager"] }),
-    agents.archDesignReviewer({ dependsOn: ["architect"] }),
-    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
-    agents.uiDesigner({ dependsOn: ["arch-design-reviewer"] }),
-    agents.uiDesignReviewer({ dependsOn: ["ui-designer"] }),
-    agents.frontendDeveloper({ dependsOn: ["ui-design-reviewer"] }),
-    agents.codeReviewer({ dependsOn: ["backend-developer", "frontend-developer"] }),
-    agents.devops({ dependsOn: ["backend-developer", "frontend-developer"] }),`
-};
-var PRESET_DESCRIPTIONS = {
-  simple: "Architect \u2192 Arch Design Reviewer \u2192 Backend Developer \u2192 Code Reviewer  (4 agents)",
-  backend: "Product Manager \u2192 Architect \u2192 Arch Design Reviewer \u2192 Backend Developer \u2192 Tester \u2192 Code Reviewer + DevOps  (7 agents)",
-  fullstack: "Product Manager \u2192 Architect \u2192 Arch Design Reviewer \u2192 Backend Developer + UI Designer \u2192 UI Design Reviewer \u2192 Frontend Developer \u2192 Code Reviewer + DevOps  (9 agents)"
-};
-var RUNTIME_INSTALL = {
-  claude: "npm install -g @anthropic-ai/claude-code",
-  codex: "npm install -g @openai/codex",
-  opencode: "npm install -g opencode",
-  cursor: "curl https://cursor.com/install | bash"
-};
-function generateConfig(opts) {
-  return `import { defineConfig, agents } from "multiclaw"
-
-export default defineConfig({
-  name: "${opts.projectName}",
-  workDir: "${opts.workDir}",
-  context: {
-    projectName: "${opts.projectName}",
-  },
-  dashboard: { port: 3210, autoOpen: true },
-  agents: [
-${AGENT_BLOCKS[opts.preset]}
-  ],
-})
-`;
-}
-async function initCommand() {
-  const configPath = path4.resolve(process.cwd(), "multiclaw.config.ts");
-  if (fs3.existsSync(configPath)) {
-    console.error("\x1B[31mError: multiclaw.config.ts already exists\x1B[0m");
-    process.exit(1);
-  }
-  const defaultProjectName = path4.basename(process.cwd());
-  const projectName = await input({
-    message: "Project name:",
-    default: defaultProjectName
-  });
-  const preset = await select({
-    message: "Select a preset:",
-    choices: [
-      { value: "simple", name: `simple     \u2014 ${PRESET_DESCRIPTIONS.simple}` },
-      { value: "backend", name: `backend    \u2014 ${PRESET_DESCRIPTIONS.backend}` },
-      { value: "fullstack", name: `fullstack  \u2014 ${PRESET_DESCRIPTIONS.fullstack}` }
-    ]
-  });
-  const workDir = await input({
-    message: "Work directory (where agents read and write files):",
-    default: "."
-  });
+  const controller = new AbortController();
+  const onSigint = () => {
+    if (controller.signal.aborted) process.exit(EXIT_CANCELLED);
+    controller.abort();
+  };
+  process.on("SIGINT", onSigint);
   try {
-    fs3.writeFileSync(configPath, generateConfig({ preset, workDir, projectName }));
-    if (workDir !== ".") {
-      fs3.mkdirSync(path4.resolve(process.cwd(), workDir), { recursive: true });
-    }
-  } catch (err) {
-    console.error(`\x1B[31mError: Failed to create files: ${err.message}\x1B[0m`);
-    process.exit(1);
+    const result = await orchestrator.run({ signal: controller.signal });
+    await logs.drain();
+    process.exitCode = result.cancelled ? EXIT_CANCELLED : result.success ? 0 : 1;
+  } finally {
+    process.off("SIGINT", onSigint);
   }
-  console.log("");
-  console.log(`\x1B[32m\u2713\x1B[0m Created multiclaw.config.ts`);
-  console.log(`  preset:   ${preset}  (${PRESET_DESCRIPTIONS[preset]})`);
-  console.log(`  workDir:  ${workDir}`);
-  console.log("");
-  console.log(`> Run: multiclaw run "describe your requirement" --ui`);
-  checkRuntime();
 }
-function checkRuntime() {
-  const runtimes = ["claude", "codex", "opencode"];
-  const available = runtimes.filter((r) => {
-    try {
-      execSync(`${r} --version`, { stdio: "ignore" });
-      return true;
-    } catch {
-      return false;
+
+// src/commands/tui.ts
+async function tuiCommand(options) {
+  const config = await loadConfig(options.config);
+  await assertRuntimesAvailable(config);
+  const { startTui } = await import("@multiclawcli/dashboard/tui");
+  await startTui({
+    config,
+    onTurnStart: (eventBus, logDir) => {
+      new FileLogWriter(logDir).attach(eventBus);
     }
   });
-  if (available.length === 0) {
-    console.log("");
-    console.log("\x1B[33mWarning: No AI runtime detected. Install at least one:\x1B[0m");
-    for (const [name, cmd] of Object.entries(RUNTIME_INSTALL)) {
-      console.log(`  \x1B[2m${name.padEnd(12)} ${cmd}\x1B[0m`);
-    }
-  }
-}
-
-// src/commands/serve.ts
-async function serveCommand(options) {
-  const { DashboardServer } = await import("@multiclawcli/dashboard/server");
-  const port = options.port ?? 3210;
-  const server = new DashboardServer({ port, acceptClientEvents: true });
-  await server.start();
-  console.log(`\x1B[36mDashboard running at: http://localhost:${port}\x1B[0m`);
-  console.log(`  In another terminal run: multiclaw run "<requirement>" --server-url http://localhost:${port}`);
 }
 
 // src/commands/upgrade.ts
-import { execSync as execSync2 } from "child_process";
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
+import { execSync } from "child_process";
+import { createRequire as createRequire2 } from "module";
+var require2 = createRequire2(import.meta.url);
 async function upgradeCommand() {
   const { version: currentVersion } = require2("../package.json");
   console.log(`Current version: v${currentVersion}`);
   console.log("Checking for updates...");
   let latestVersion;
   try {
-    latestVersion = execSync2("npm show multiclaw version", { encoding: "utf8" }).trim();
+    latestVersion = execSync("npm show multiclaw version", { encoding: "utf8" }).trim();
   } catch {
     console.error("\x1B[31mError: Failed to fetch latest version from npm registry\x1B[0m");
     process.exit(1);
@@ -398,10 +698,12 @@ async function upgradeCommand() {
   }
   console.log(`Upgrading multiclaw v${currentVersion} \u2192 v${latestVersion}...`);
   try {
-    execSync2("npm install -g multiclaw@latest", { stdio: "inherit" });
+    execSync("npm install -g multiclaw@latest", { stdio: "inherit" });
     console.log(`\x1B[32m\u2713\x1B[0m Successfully upgraded to v${latestVersion}`);
   } catch {
-    console.error("\x1B[31mError: Upgrade failed. Try running manually: npm install -g multiclaw@latest\x1B[0m");
+    console.error(
+      "\x1B[31mError: Upgrade failed. Try running manually: npm install -g multiclaw@latest\x1B[0m"
+    );
     process.exit(1);
   }
 }
@@ -411,12 +713,13 @@ var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname2(__filename2);
 var pkg = JSON.parse(readFileSync(join3(__dirname2, "../package.json"), "utf-8"));
 var program = new Command();
-program.name("multiclaw").description("Multi-agent orchestration CLI").version(pkg.version, "-v, --version", "Display version number");
+program.name("multiclaw").description("Multi-agent orchestration CLI").version(pkg.version, "-v, --version", "Display version number").action((options) => tuiCommand(options));
 program.command("init").description("Scaffold a config file (interactive)").action(() => initCommand());
-program.command("run <requirement>").description("Run an orchestration").option("--config <path>", "Config file path (default: auto-discover ./multiclaw.config.ts)").option("--ui", "Start Dashboard and open in browser").option("--port <port>", "Dashboard port (requires --ui)", (v) => parseInt(v, 10)).option("--server-url <url>", "Connect to a running serve process").option("--no-leader", "Skip the leader agent and use the default pipeline").action((requirement, opts) => runCommand(requirement, opts));
-program.command("serve").description("Start a persistent Dashboard server").option("--port <port>", "Port", (v) => parseInt(v, 10)).action((opts) => serveCommand(opts));
+program.command("run <requirement>").description("Run an orchestration headlessly").option("--config <path>", "Config file path (default: auto-discover ./multiclaw.config.ts)").option("--no-leader", "Batch mode only: skip routing and run the full team").action((requirement, opts) => runCommand(requirement, opts));
 program.command("upgrade").description("Upgrade multiclaw to the latest version").action(() => upgradeCommand());
+program.command("doctor").description("Check which agent providers are installed and ready").option("--config <path>", "Config file path (default: auto-discover ./multiclaw.config.ts)").action((opts) => doctorCommand(opts.config));
 program.parseAsync(process.argv).catch((err) => {
-  console.error(`\x1B[31mError: ${err.message ?? err}\x1B[0m`);
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`\x1B[31mError: ${message}\x1B[0m`);
   process.exit(1);
 });

package/dist/lib.d.ts

@@ -1 +1,21 @@
-export { AgentDefinition, MultiClawConfig, agents, defineConfig } from '@multiclawcli/core';
+import { MultiClawConfig } from '@multiclawcli/core';
+export { AgentDefinition, MultiClawConfig, agents, defineConfig, detectProviders, presentProviders } from '@multiclawcli/core';
+
+/**
+ * Hard gate for `run`/`tui`: every runtime the config names must exist and
+ * report itself as installed, or the process exits before any work starts.
+ *
+ * Availability comes from `describe()` rather than an ad-hoc `execSync`, so
+ * "is this runtime installed?" has exactly one implementation. `describe()`
+ * receives the agent's configured command because an external-process runtime
+ * (e.g. ACP) is only as available as the binary it was told to launch.
+ */
+declare function assertRuntimesAvailable(config: MultiClawConfig): Promise<void>;
+
+/**
+ * Legacy alias: returns runtime names that have at least one provider present.
+ * Prefer `detectProviders()` for new code.
+ */
+declare function availableRuntimes(): Promise<string[]>;
+
+export { assertRuntimesAvailable, availableRuntimes };

package/dist/lib.js

@@ -1,6 +1,44 @@
 // src/lib.ts
-import { defineConfig, agents } from "@multiclawcli/core";
+import {
+  detectProviders,
+  presentProviders,
+  resolveCommand,
+  runtimeRegistry
+} from "@multiclawcli/core";
+import { agents, defineConfig } from "@multiclawcli/core";
+async function assertRuntimesAvailable(config) {
+  const checked = /* @__PURE__ */ new Set();
+  for (const agent of config.agents) {
+    const name = agent.runtime ?? "acp";
+    if (!runtimeRegistry.has(name)) {
+      const supported = runtimeRegistry.list().join(", ");
+      console.error(`\x1B[31mError: Unknown runtime "${name}". Supported: ${supported}\x1B[0m`);
+      process.exit(1);
+    }
+    const command = resolveCommand(agent, config);
+    const key = `${name}\0${command}`;
+    if (checked.has(key)) continue;
+    checked.add(key);
+    const info = await runtimeRegistry.get(name).describe({ command });
+    if (!info.available) {
+      const subject = `Command "${command}"`;
+      console.error(
+        `\x1B[31mError: ${subject} is not available. Make sure the CLI is installed.\x1B[0m`
+      );
+      process.exit(1);
+    }
+  }
+}
+async function availableRuntimes() {
+  const detected = await detectProviders();
+  const present = presentProviders(detected);
+  return present.length > 0 ? ["acp"] : [];
+}
 export {
   agents,
-  defineConfig
+  assertRuntimesAvailable,
+  availableRuntimes,
+  defineConfig,
+  detectProviders,
+  presentProviders
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multiclaw",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "multiclaw": "dist/index.js"
@@ -27,21 +27,25 @@
     "url": "https://github.com/shipengqi/multiclaw/issues"
   },
   "dependencies": {
+    "@agentclientprotocol/claude-agent-acp": "^0.89.1",
+    "@agentclientprotocol/codex-acp": "^2.2.2",
     "@inquirer/prompts": "^8.7.3",
-    "@multiclawcli/core": "0.3.2",
-    "@multiclawcli/dashboard": "0.3.2",
-    "commander": "^12.0.0",
-    "open": "^10.0.0",
-    "tsx": "^4.7.0",
-    "ws": "^8.16.0"
+    "@multiclawcli/core": "0.4.0",
+    "@multiclawcli/dashboard": "0.4.0",
+    "commander": "^15.0.0",
+    "jiti": "^2.7.0"
   },
   "devDependencies": {
-    "@types/node": "^20.11.0",
-    "@types/ws": "^8.5.0",
-    "typescript": "^5.4.0"
+    "@types/node": "^26.6.4",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "dev": "tsx src/index.ts"
   }
 }