multiclaw 0.4.0 → 0.5.1

package/dist/commands/doctor.d.ts

@@ -0,0 +1,32 @@
+import { type DetectedProvider, type ModelSelectionMode, type MultiClawConfig, type ProviderSource, type ProviderStatus } from "@multiclawcli/core";
+export interface DoctorProviderRow {
+    id: string;
+    label: string;
+    status: ProviderStatus;
+    command: string;
+    source?: ProviderSource;
+    resolvedPath?: string;
+    version?: string;
+    modelCount: number;
+    modelSelection: ModelSelectionMode;
+    authHint: string;
+    installHint?: string;
+}
+export interface DoctorReport {
+    providers: DoctorProviderRow[];
+    installedCount: number;
+    config?: {
+        name?: string;
+        defaultsProvider?: string;
+        defaultsProviderOk: boolean;
+        agentsWithMissingProvider: string[];
+        agentsWithUnsupportedTools: string[];
+    };
+    runnable: boolean;
+}
+/** Build the diagnostic model from detection results and an optional config. */
+export declare function buildDoctorReport(detected: DetectedProvider[], config?: MultiClawConfig): DoctorReport;
+/** Render the report as human-readable text for stdout. */
+export declare function formatDoctorReport(report: DoctorReport, useColor?: boolean): string;
+/** Run the `doctor` command: detect providers, print the report, set exit code. */
+export declare function doctorCommand(configPath?: string): Promise<void>;

package/dist/commands/doctor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/init.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The agents each preset actually contains, by their `agents.<id>()` name.
+ *
+ * Kept adjacent to {@link AGENT_BLOCKS} because the two must stay in step: the
+ * override checkbox offers exactly these ids, and the regex that injects an
+ * override only matches an id that really appears in the block. A mismatch is a
+ * silently dropped override, which is what this list exists to prevent. The
+ * `init.test.ts` consistency check asserts every id here has a matching
+ * `agents.<id>(` in the block string.
+ */
+export declare const PRESET_AGENT_IDS: Record<string, string[]>;
+/**
+ * The override choices for a preset: the leader (which belongs to no preset)
+ * plus the preset's own agents. Filtering by preset is what stops an override
+ * for an agent the preset does not contain from being offered and then dropped.
+ */
+export declare function overrideChoices(preset: string): Array<{
+    value: string;
+    name: string;
+}>;
+export declare function generateConfig(opts: {
+    preset: string;
+    workDir: string;
+    projectName: string;
+    provider: string;
+    model?: string;
+    overrides?: Array<{
+        id: string;
+        model: string;
+    }>;
+}): string;
+export declare function initCommand(): Promise<void>;

package/dist/commands/init.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/resume.d.ts

@@ -0,0 +1,32 @@
+import type { MultiClawConfig, OrchestratorResult } from "@multiclawcli/core";
+/** A previous run's report, as much of it as resume needs. */
+export interface ResumeTarget {
+    runDir: string;
+    report: OrchestratorResult;
+}
+/**
+ * Resolve `--resume` into the run directory it names.
+ *
+ * `true` (a bare `--resume`) and `"latest"` both mean "the newest run". Run
+ * directories are named `run-<ISO stamp>` with a fixed-width stamp, so a plain
+ * lexicographic maximum is the most recent one — deterministic, and testable
+ * without a clock.
+ *
+ * Any other value is treated as a path: either the run directory itself or its
+ * `logs/` subdirectory, since that is where the report lives and a caller may
+ * well point at it.
+ */
+export declare function resolveRunDir(runsRoot: string, target: string | boolean): string;
+/** Read a run's `report.json`. */
+export declare function readReport(runDir: string): OrchestratorResult;
+/**
+ * Turn a report (plus an optional requirement override) into run config.
+ *
+ * The requirement is the one thing a report cannot always supply — an older
+ * report predates the field — so an explicit override wins, and its absence on
+ * both sides is an error rather than a silently empty run.
+ */
+export declare function resumeOptionsFromReport(report: OrchestratorResult, requirementOverride?: string): {
+    requirement: string;
+    resume: NonNullable<MultiClawConfig["resume"]>;
+};

package/dist/commands/resume.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/run.d.ts

@@ -0,0 +1,12 @@
+export interface RunOptions {
+    config?: string;
+    noLeader?: boolean;
+    /**
+     * `true` for a bare `--resume` (latest run), or a path to a specific run.
+     * Commander only ever produces `undefined`, `true` or a string, so `false` is
+     * not part of the domain.
+     */
+    resume?: string | true;
+    dryRun?: boolean;
+}
+export declare function runCommand(requirementArg: string | undefined, options: RunOptions): Promise<void>;

package/dist/commands/run.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/tui.d.ts

@@ -0,0 +1,4 @@
+export interface TuiCommandOptions {
+    config?: string;
+}
+export declare function tuiCommand(options: TuiCommandOptions): Promise<void>;

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,30 @@
+/** Which package manager owns the copy of multiclaw that is currently running. */
+export type Installer = "npm" | "pnpm" | "bun" | "yarn" | "unknown";
+/** Walk up from `start` to the package.json that declares this package. */
+export declare function findPackageRoot(start: string): string | undefined;
+/** Read the installed version straight from disk (no module cache to go stale). */
+export declare function readInstalledVersion(pkgRoot: string): string | undefined;
+/**
+ * Identify the installer from the on-disk location of the running package.
+ *
+ * This is the whole point of the command: `npm install -g` writes to npm's
+ * prefix, which is not necessarily where the binary on PATH came from. A user
+ * with a pnpm global install used to get a silent no-op upgrade — npm installed
+ * a fresh copy somewhere else while `multiclaw --version` kept reporting the
+ * pnpm one. Upgrading must therefore target the manager that owns this copy.
+ */
+export declare function detectInstaller(pkgRoot: string): Installer;
+type Exec = (command: string, mode: "capture" | "inherit") => string;
+export interface UpgradeContext {
+    pkgRoot: string;
+    currentVersion: string;
+    installer: Installer;
+    /** Re-read after installing: the on-disk copy is what `--version` reports. */
+    readVersion: (pkgRoot: string) => string | undefined;
+    exec: Exec;
+}
+/** Resolve the running install. `undefined` means it is not an installed copy. */
+export declare function createUpgradeContext(): UpgradeContext | undefined;
+export declare function runUpgrade(ctx: UpgradeContext): Promise<void>;
+export declare function upgradeCommand(): Promise<void>;
+export {};

package/dist/commands/upgrade.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
-import { fileURLToPath } from "url";
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname4, join as join5 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
 
 // src/commands/doctor.ts
 import {
   detectProviders,
   presentProviders,
+  resolveCommand,
   resolveProvider,
+  specForCommand,
   specForProvider
 } from "@multiclawcli/core";
 
@@ -96,6 +98,8 @@ function buildDoctorReport(detected, config) {
       label: d.label,
       status: d.status,
       command: d.command,
+      source: d.source,
+      resolvedPath: d.resolvedPath,
       version: d.version,
       modelCount: spec?.models.length ?? 0,
       modelSelection: spec?.modelSelection ?? "none",
@@ -111,11 +115,17 @@ function buildDoctorReport(detected, config) {
     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);
+    const agentsWithUnsupportedTools = agents2.map((a) => {
+      const command = resolveCommand(a, config);
+      const spec = specForCommand(command) ?? specForProvider(resolveProvider(a, config));
+      return { id: a.id, spec, tools: a.tools };
+    }).filter((a) => a.spec && !a.spec.tools && a.tools !== void 0).map((a) => a.id);
     configReport = {
       name: config.name,
       defaultsProvider,
       defaultsProviderOk,
-      agentsWithMissingProvider
+      agentsWithMissingProvider,
+      agentsWithUnsupportedTools
     };
   }
   return {
@@ -145,16 +155,23 @@ function formatDoctorReport(report, useColor = true) {
   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`);
+  lines.push(
+    `${cell("provider", 12)}${cell("status", 10)}${cell("version", 14)}${cell("source", 9)}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 source = p.source ?? "\u2014";
+    const sourceCode = p.source === "bundled" ? YELLOW : void 0;
     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}`
+      `${cell(p.label, 12)}${cell(mark, 10, markCode)}${cell(version, 14)}${cell(source, 9, sourceCode)}${cell(models, 7)}${auth}`
     );
+    if (p.status === "present" && p.source === "bundled" && p.resolvedPath) {
+      lines.push(c(DIM, `    bundled bridge: ${p.resolvedPath}`));
+    }
     if (p.status === "missing" && p.installHint) {
       lines.push(c(YELLOW, `  install: ${p.installHint}`));
     }
@@ -178,6 +195,14 @@ function formatDoctorReport(report, useColor = true) {
     } else {
       lines.push(c(GREEN, "  all agents resolve to an installed provider \u2713"));
     }
+    if (report.config.agentsWithUnsupportedTools.length > 0) {
+      lines.push(
+        c(
+          YELLOW,
+          `  ${report.config.agentsWithUnsupportedTools.length} agent(s) use a provider that cannot enforce tool allowlists: ${report.config.agentsWithUnsupportedTools.join(", ")}`
+        )
+      );
+    }
   }
   lines.push("");
   if (report.runnable) {
@@ -244,21 +269,75 @@ var PRESET_DESCRIPTIONS = {
   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)"
 };
+var PRESET_AGENT_IDS = {
+  backend: [
+    "productManager",
+    "architect",
+    "archDesignReviewer",
+    "backendDeveloper",
+    "tester",
+    "codeReviewer",
+    "devops"
+  ],
+  frontend: [
+    "architect",
+    "uiDesigner",
+    "uiDesignReviewer",
+    "frontendDeveloper",
+    "tester",
+    "codeReviewer"
+  ],
+  fullstack: [
+    "productManager",
+    "architect",
+    "archDesignReviewer",
+    "backendDeveloper",
+    "uiDesigner",
+    "uiDesignReviewer",
+    "frontendDeveloper",
+    "tester",
+    "codeReviewer",
+    "devops"
+  ]
+};
+var OVERRIDE_LABELS = {
+  leader: "\u2605 Leader",
+  productManager: "Product Manager",
+  architect: "Architect",
+  archDesignReviewer: "Arch Design Reviewer",
+  backendDeveloper: "Backend Developer",
+  frontendDeveloper: "Frontend Developer",
+  uiDesigner: "UI Designer",
+  uiDesignReviewer: "UI Design Reviewer",
+  tester: "Tester",
+  codeReviewer: "Code Reviewer",
+  devops: "DevOps"
+};
+function overrideChoices(preset) {
+  const ids = PRESET_AGENT_IDS[preset] ?? [];
+  return [
+    { value: "leader", name: OVERRIDE_LABELS.leader },
+    ...ids.map((id) => ({ value: id, name: OVERRIDE_LABELS[id] ?? id }))
+  ];
+}
 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)}`);
+  const leaderOverride = opts.overrides?.find((o) => o.id === "leader");
+  const leaderLine = leaderOverride ? `  leader: agents.leader({ model: ${JSON.stringify(leaderOverride.model)} }),` : `  leader: agents.leader(),`;
   let agentBlock = AGENT_BLOCKS[opts.preset];
   if (opts.overrides && opts.overrides.length > 0) {
     for (const ov of opts.overrides) {
       const id = ov.id;
+      if (id === "leader") continue;
       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} })`;
+        const body = match.slice(id.length + 8, -1).trim().replace(/^\{/, "").replace(/\}$/, "").trim();
+        const sep = body ? ", " : "";
+        return `agents.${id}({ ${body}${sep}model: ${model} })`;
       });
     }
   }
@@ -267,6 +346,7 @@ function generateConfig(opts) {
 export default defineConfig({
   name: ${name},
   workDir: ${workDir},
+${leaderLine}
   context: {
     projectName: ${name},
   },
@@ -331,19 +411,7 @@ async function initCommand() {
   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" }
-    ]
+    choices: overrideChoices(preset)
   });
   const overrides = [];
   for (const id of overrideIds) {
@@ -406,14 +474,18 @@ async function initCommand() {
 }
 
 // src/commands/run.ts
-import * as path4 from "path";
-import { Orchestrator as OrchestratorImpl } from "@multiclawcli/core";
+import * as fs5 from "fs";
+import * as path5 from "path";
+import {
+  describeResumePlan,
+  Orchestrator as OrchestratorImpl
+} from "@multiclawcli/core";
 
 // src/lib.ts
 import {
   detectProviders as detectProviders3,
   presentProviders as presentProviders2,
-  resolveCommand,
+  resolveCommand as resolveCommand2,
   runtimeRegistry
 } from "@multiclawcli/core";
 import { agents, defineConfig } from "@multiclawcli/core";
@@ -426,7 +498,7 @@ async function assertRuntimesAvailable(config) {
       console.error(`\x1B[31mError: Unknown runtime "${name}". Supported: ${supported}\x1B[0m`);
       process.exit(1);
     }
-    const command = resolveCommand(agent, config);
+    const command = resolveCommand2(agent, config);
     const key = `${name}\0${command}`;
     if (checked.has(key)) continue;
     checked.add(key);
@@ -463,6 +535,11 @@ var C = isFancy ? {
   red: "",
   purple: ""
 };
+function markFor(status) {
+  if (status === "success") return { icon: S.ok, color: C.green };
+  if (status === "cancelled") return { icon: S.skip, color: C.yellow };
+  return { icon: S.fail, color: C.red };
+}
 var ConsoleReporter = class {
   attach(eventBus) {
     return eventBus.subscribe((e) => this.handle(e));
@@ -480,6 +557,10 @@ ${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`);
           `${C.cyan}${S.bullet} Agents: ${e.payload.totalAgents}  Stages: ${e.payload.stages.length}${C.reset}
 `
         );
+        if (e.payload.selectionReason) {
+          console.log(`${C.dim}${S.bullet} Why: ${e.payload.selectionReason}${C.reset}
+`);
+        }
         break;
       }
       case "orchestration:stages": {
@@ -498,6 +579,7 @@ ${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`);
         break;
       }
       case "agent:output": {
+        if (e.payload.kind && e.payload.kind !== "text") break;
         process.stdout.write(`  ${e.payload.chunk}`);
         break;
       }
@@ -507,6 +589,10 @@ ${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`);
         break;
       }
       case "agent:failed": {
+        if (e.payload.status === "cancelled") {
+          console.log(`${C.yellow}${S.skip} ${e.payload.agentName} cancelled${C.reset}`);
+          break;
+        }
         console.log(`${C.red}${S.fail} ${e.payload.agentName} failed: ${e.payload.error}${C.reset}`);
         break;
       }
@@ -533,22 +619,33 @@ ${C.cyan}${mark} ${reply.message}${C.reset}`);
         }
         const line = (isFancy ? "\u2550" : "=").repeat(50);
         const edge = isFancy ? ["\u2554", "\u2551", "\u255A", "\u2557", "\u255D"] : ["+", "|", "+", "+", "+"];
-        const title = reply ? reply.mode === "ask" ? `${S.warn} Needs your input` : `${S.ok} Answered` : success ? `${S.ok} All done` : `${S.warn} Done (with failures)`;
+        const title = reply ? reply.mode === "ask" ? `${S.warn} Needs your input` : `${S.ok} Answered` : e.payload.cancelled ? `${S.skip} Cancelled` : 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]}`);
         console.log(`${edge[2]}${line}${edge[4]}${C.reset}`);
         const nameWidth = Math.max(8, ...agentResults.map((r) => r.agentName.length));
         const totalStr = `${(totalDuration / 1e3).toFixed(1)}s`;
-        console.log(`  ~ ${"Total".padEnd(nameWidth)}   ${totalStr.padStart(7)}`);
+        const cost = e.payload.totalCostUsd;
+        const costStr = cost === void 0 ? "" : `  $${cost.toFixed(2)}`;
+        console.log(`  ~ ${"Total".padEnd(nameWidth)}   ${totalStr.padStart(7)}${costStr}`);
         for (const r of agentResults) {
-          const icon = r.status === "success" ? S.ok : S.fail;
-          const color2 = r.status === "success" ? C.green : C.red;
+          const { icon, color: color2 } = markFor(r.status);
           const dur = `${(r.duration / 1e3).toFixed(1)}s`;
           console.log(
             `  ${color2}${icon}${C.reset} ${r.agentName.padEnd(nameWidth)}   ${dur.padStart(7)}`
           );
         }
+        if (e.payload.deliverables && e.payload.deliverables.length > 0) {
+          console.log(`
+  Deliverables:`);
+          for (const file of e.payload.deliverables.slice(0, 5)) {
+            console.log(`  ${S.bullet} ${file.path} (${file.status}, ${file.size} bytes)`);
+          }
+          if (e.payload.deliverables.length > 5) {
+            console.log(`  ${S.bullet} \u2026 ${e.payload.deliverables.length - 5} more`);
+          }
+        }
         console.log();
         break;
       }
@@ -587,7 +684,9 @@ var FileLogWriter = class {
   }
   handle(e) {
     if (e.type === "agent:output") {
-      this.getStream(e.payload.agentId)?.write(e.payload.chunk);
+      const { agentId, chunk, kind } = e.payload;
+      if (kind && kind !== "text") return;
+      this.getStream(agentId)?.write(chunk);
     }
     if (e.type === "orchestration:complete") {
       try {
@@ -617,12 +716,12 @@ var FileLogWriter = class {
     this.streams.clear();
     return Promise.all(
       streams.map(
-        (s) => new Promise((resolve3) => {
+        (s) => new Promise((resolve5) => {
           if (s.destroyed || s.writableEnded) {
-            resolve3();
+            resolve5();
             return;
           }
-          s.end(() => resolve3());
+          s.end(() => resolve5());
         })
       )
     ).then(() => void 0);
@@ -632,19 +731,108 @@ function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
+// src/commands/resume.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+function resolveRunDir(runsRoot, target) {
+  if (typeof target !== "string" || target === "latest") {
+    return latestRunDir(runsRoot);
+  }
+  const resolved = path4.resolve(target);
+  const runDir = path4.basename(resolved) === "logs" ? path4.dirname(resolved) : resolved;
+  if (!fs4.existsSync(runDir)) {
+    throw new Error(`Run directory not found: ${runDir}`);
+  }
+  return runDir;
+}
+function latestRunDir(runsRoot) {
+  const names = fs4.existsSync(runsRoot) ? fs4.readdirSync(runsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.startsWith("run-")).map((entry) => entry.name).sort() : [];
+  const latest = names[names.length - 1];
+  if (!latest) {
+    throw new Error(`No runs found to resume \u2014 looked in ${runsRoot}`);
+  }
+  return path4.join(runsRoot, latest);
+}
+function readReport(runDir) {
+  const reportPath = path4.join(runDir, "logs", "report.json");
+  let raw;
+  try {
+    raw = fs4.readFileSync(reportPath, "utf-8");
+  } catch {
+    throw new Error(`No report.json in ${runDir} \u2014 it may not be a complete run`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`Could not parse ${reportPath}: ${detail}`);
+  }
+}
+function resumeOptionsFromReport(report, requirementOverride) {
+  const agents2 = [...new Set(report.agentResults.map((result) => result.agentId))];
+  if (agents2.length === 0) {
+    throw new Error("The previous run has no agent results \u2014 nothing to resume");
+  }
+  const sessions = {};
+  for (const result of report.agentResults) {
+    if (result.sessionId) sessions[result.agentId] = result.sessionId;
+  }
+  const requirement = requirementOverride ?? report.requirement;
+  if (requirement === void 0) {
+    throw new Error("The previous run recorded no requirement \u2014 pass one explicitly to resume");
+  }
+  return {
+    requirement,
+    resume: {
+      agents: agents2,
+      // Absent, not `{}`: core reads a missing `sessions` as "start every agent
+      // fresh", which is exactly the single-agent retry of a failed agent.
+      ...Object.keys(sessions).length > 0 ? { sessions } : {}
+    }
+  };
+}
+
 // src/commands/run.ts
 var EXIT_CANCELLED = 130;
-async function runCommand(requirement, options) {
-  const config = await loadConfig(options.config, requirement);
+async function runCommand(requirementArg, options) {
+  const config = await loadConfig(options.config, requirementArg);
   if (options.noLeader) {
     config.useLeader = false;
   }
-  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
-  config.workDir = path4.join(config.workDir, ".multiclaw", "runs", `run-${ts}`);
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  if (options.resume !== void 0) {
+    const runsRoot = path5.join(config.workDir, ".multiclaw", "runs");
+    const runDir = resolveRunDir(runsRoot, options.resume);
+    const report = readReport(runDir);
+    const { requirement, resume } = resumeOptionsFromReport(report, requirementArg);
+    config.workDir = runDir;
+    config.resume = resume;
+    config.context = { ...config.context, requirement };
+    config.logDir = path5.join(runDir, `logs-resume-${stamp}`);
+    const plan = describeResumePlan({
+      agents: resume.agents,
+      sessions: resume.sessions,
+      team: config.agents
+    });
+    console.log(`\x1B[2mResuming ${runDir} (${resume.agents.length} agents) \u2014 ${plan}\x1B[0m`);
+  } else {
+    config.workDir = path5.join(config.workDir, ".multiclaw", "runs", `run-${stamp}`);
+  }
+  if (options.dryRun) {
+    const preview = await new OrchestratorImpl(config).preview();
+    printDryRun(preview, config.workDir);
+    process.exitCode = 0;
+    return;
+  }
   await assertRuntimesAvailable(config);
+  const before = snapshotFiles(config.workDir);
   const orchestrator = new OrchestratorImpl(config);
+  orchestrator.eventBus.subscribe((event) => {
+    if (event.type !== "orchestration:complete") return;
+    event.payload.deliverables = collectDeliverables(config.workDir, before);
+  });
   new ConsoleReporter().attach(orchestrator.eventBus);
-  const logDir = config.logDir ?? path4.join(config.workDir, "logs");
+  const logDir = config.logDir ?? path5.join(config.workDir, "logs");
   const logs = new FileLogWriter(logDir);
   logs.attach(orchestrator.eventBus);
   console.log(`\x1B[2mLogs: ${logDir}\x1B[0m`);
@@ -662,6 +850,59 @@ async function runCommand(requirement, options) {
     process.off("SIGINT", onSigint);
   }
 }
+function printDryRun(preview, workDir) {
+  console.log("Dry run \u2014 no pipeline agents will execute.");
+  console.log(`Project: ${preview.name}`);
+  console.log(`Work dir: ${workDir}`);
+  if (preview.requirement) console.log(`Requirement: ${preview.requirement}`);
+  if (preview.reply) {
+    console.log(`${preview.reply.mode === "ask" ? "Question" : "Reply"}: ${preview.reply.message}`);
+    return;
+  }
+  console.log(`Agents: ${preview.totalAgents}`);
+  if (preview.selectionReason) console.log(`Why: ${preview.selectionReason}`);
+  for (const stage of preview.stages) {
+    const agents2 = stage.agents.map(
+      (agent) => `${agent.id}${agent.model ? ` (${agent.model})` : ""}`
+    );
+    console.log(`Stage ${stage.stageIndex + 1}: ${agents2.join(", ") || "\u2014"}`);
+  }
+}
+function snapshotFiles(root) {
+  const snapshot = /* @__PURE__ */ new Map();
+  walkFiles(root, (_absolute, relative2, stat) => {
+    snapshot.set(relative2, { mtimeMs: stat.mtimeMs, size: stat.size });
+  });
+  return snapshot;
+}
+function collectDeliverables(root, before) {
+  const deliverables = [];
+  walkFiles(root, (_absolute, relative2, stat) => {
+    const previous = before.get(relative2);
+    if (previous && previous.mtimeMs === stat.mtimeMs && previous.size === stat.size) return;
+    deliverables.push({
+      path: relative2,
+      status: previous ? "modified" : "created",
+      size: stat.size,
+      modifiedAt: stat.mtime.toISOString()
+    });
+  });
+  return deliverables.sort((a, b) => a.path.localeCompare(b.path)).slice(0, 20);
+}
+function walkFiles(root, visit) {
+  if (!fs5.existsSync(root)) return;
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    for (const name of fs5.readdirSync(dir)) {
+      if (name === ".multiclaw") continue;
+      const absolute = path5.join(dir, name);
+      const stat = fs5.statSync(absolute);
+      if (stat.isDirectory()) stack.push(absolute);
+      else if (stat.isFile()) visit(absolute, path5.relative(root, absolute), stat);
+    }
+  }
+}
 
 // src/commands/tui.ts
 async function tuiCommand(options) {
@@ -678,44 +919,139 @@ async function tuiCommand(options) {
 
 // src/commands/upgrade.ts
 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}`);
+import { existsSync as existsSync5, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname3, join as join4, resolve as resolve4 } from "path";
+import { fileURLToPath } from "url";
+var PACKAGE_NAME = "multiclaw";
+var RED2 = "\x1B[31m";
+var GREEN2 = "\x1B[32m";
+var RESET2 = "\x1B[0m";
+function readManifest(dir) {
+  const manifest = join4(dir, "package.json");
+  if (!existsSync5(manifest)) return void 0;
+  try {
+    return JSON.parse(readFileSync2(manifest, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function findPackageRoot(start) {
+  let dir = resolve4(start);
+  for (; ; ) {
+    if (readManifest(dir)?.name === PACKAGE_NAME) return dir;
+    const parent = dirname3(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function readInstalledVersion(pkgRoot) {
+  return readManifest(pkgRoot)?.version;
+}
+function detectInstaller(pkgRoot) {
+  const path6 = pkgRoot.replaceAll("\\", "/");
+  if (path6.includes("/pnpm/global/") || path6.includes("/.pnpm/")) return "pnpm";
+  if (path6.includes("/install/global/") || path6.includes("/.bun/")) return "bun";
+  if (path6.includes("/yarn/global/")) return "yarn";
+  if (path6.includes("/node_modules/")) return "npm";
+  return "unknown";
+}
+var COMMANDS = {
+  npm: { latest: "npm show multiclaw version", install: "npm install -g multiclaw@latest" },
+  pnpm: { latest: "pnpm view multiclaw version", install: "pnpm add -g multiclaw@latest" },
+  bun: void 0,
+  yarn: void 0,
+  unknown: void 0
+};
+var MANUAL = {
+  npm: "npm install -g multiclaw@latest",
+  pnpm: "pnpm add -g multiclaw@latest",
+  bun: "bun add -g multiclaw@latest",
+  yarn: "yarn global add multiclaw@latest",
+  unknown: "npm install -g multiclaw@latest"
+};
+function createUpgradeContext() {
+  const pkgRoot = findPackageRoot(dirname3(fileURLToPath(import.meta.url)));
+  if (!pkgRoot) return void 0;
+  const currentVersion = readInstalledVersion(pkgRoot);
+  if (!currentVersion) return void 0;
+  return {
+    pkgRoot,
+    currentVersion,
+    installer: detectInstaller(pkgRoot),
+    readVersion: readInstalledVersion,
+    exec: (command, mode) => {
+      if (mode === "inherit") {
+        execSync(command, { stdio: "inherit" });
+        return "";
+      }
+      return execSync(command, { encoding: "utf8" });
+    }
+  };
+}
+async function runUpgrade(ctx) {
+  const { pkgRoot, currentVersion, installer, exec, readVersion } = ctx;
+  console.log(`Current version: v${currentVersion} (${installer} install)`);
+  const commands = COMMANDS[installer];
+  if (!commands) {
+    const reason = installer === "unknown" ? `this copy is not a global install (${pkgRoot})` : `the ${installer} install at ${pkgRoot} cannot be upgraded automatically`;
+    console.error(`${RED2}Error: ${reason}. Run it manually: ${MANUAL[installer]}${RESET2}`);
+    process.exit(1);
+    return;
+  }
   console.log("Checking for updates...");
   let latestVersion;
   try {
-    latestVersion = execSync("npm show multiclaw version", { encoding: "utf8" }).trim();
+    latestVersion = exec(commands.latest, "capture").trim();
   } catch {
-    console.error("\x1B[31mError: Failed to fetch latest version from npm registry\x1B[0m");
+    console.error(`${RED2}Error: Failed to fetch latest version from npm registry${RESET2}`);
     process.exit(1);
     return;
   }
   if (latestVersion === currentVersion) {
-    console.log(`\x1B[32m\u2713\x1B[0m Already on the latest version (v${currentVersion})`);
+    console.log(`${GREEN2}\u2713${RESET2} Already on the latest version (v${currentVersion})`);
     return;
   }
   console.log(`Upgrading multiclaw v${currentVersion} \u2192 v${latestVersion}...`);
   try {
-    execSync("npm install -g multiclaw@latest", { stdio: "inherit" });
-    console.log(`\x1B[32m\u2713\x1B[0m Successfully upgraded to v${latestVersion}`);
+    exec(commands.install, "inherit");
   } catch {
+    console.error(`${RED2}Error: Upgrade failed. Try running manually: ${commands.install}${RESET2}`);
+    process.exit(1);
+    return;
+  }
+  const installedVersion = readVersion(pkgRoot);
+  if (installedVersion !== latestVersion) {
+    console.error(
+      `${RED2}Error: ${commands.install} finished, but ${pkgRoot} still reports v${installedVersion ?? "unknown"}. Check for a second multiclaw install, then retry.${RESET2}`
+    );
+    process.exit(1);
+    return;
+  }
+  console.log(`${GREEN2}\u2713${RESET2} Successfully upgraded to v${latestVersion} (${pkgRoot})`);
+}
+async function upgradeCommand() {
+  const ctx = createUpgradeContext();
+  if (!ctx) {
     console.error(
-      "\x1B[31mError: Upgrade failed. Try running manually: npm install -g multiclaw@latest\x1B[0m"
+      `${RED2}Error: could not locate the multiclaw package this process is running from.${RESET2}`
     );
     process.exit(1);
+    return;
   }
+  await runUpgrade(ctx);
 }
 
 // src/index.ts
-var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = dirname2(__filename2);
-var pkg = JSON.parse(readFileSync(join3(__dirname2, "../package.json"), "utf-8"));
+var __filename2 = fileURLToPath2(import.meta.url);
+var __dirname2 = dirname4(__filename2);
+var pkg = JSON.parse(readFileSync3(join5(__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").action((options) => tuiCommand(options));
 program.command("init").description("Scaffold a config file (interactive)").action(() => initCommand());
-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("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").option("--dry-run", "Preview the routed plan without running the pipeline").option(
+  "--resume [path]",
+  "Resume a previous run, continuing agent sessions (default: the latest)"
+).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) => {

package/dist/lib.d.ts

@@ -1,6 +1,6 @@
-import { MultiClawConfig } from '@multiclawcli/core';
-export { AgentDefinition, MultiClawConfig, agents, defineConfig, detectProviders, presentProviders } from '@multiclawcli/core';
-
+import { detectProviders, type MultiClawConfig, presentProviders } from "@multiclawcli/core";
+export type { AgentDefinition, MultiClawConfig } from "@multiclawcli/core";
+export { agents, defineConfig } 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.
@@ -10,12 +10,11 @@ export { AgentDefinition, MultiClawConfig, agents, defineConfig, detectProviders
  * 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>;
-
+export declare function assertRuntimesAvailable(config: MultiClawConfig): Promise<void>;
+/** Re-export for consumers that need full detection details. */
+export { detectProviders, presentProviders };
 /**
  * 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 };
+export declare function availableRuntimes(): Promise<string[]>;

package/dist/lib.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/loader/loadConfig.d.ts

@@ -0,0 +1,2 @@
+import type { MultiClawConfig } from "@multiclawcli/core";
+export declare function loadConfig(configPath?: string, requirement?: string): Promise<MultiClawConfig>;

package/dist/loader/loadConfig.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reporters/ConsoleReporter.d.ts

@@ -0,0 +1,5 @@
+import type { EventBus } from "@multiclawcli/core";
+export declare class ConsoleReporter {
+    attach(eventBus: EventBus): () => void;
+    private handle;
+}

package/dist/reporters/ConsoleReporter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reporters/FileLogWriter.d.ts

@@ -0,0 +1,29 @@
+import type { EventBus } from "@multiclawcli/core";
+/**
+ * Streams each agent's output to its own log file, plus a `report.json` per turn.
+ *
+ * Logging is diagnostics, so nothing in here is allowed to take the run down: a
+ * failed log write is reported and then ignored.
+ */
+export declare class FileLogWriter {
+    private logDir;
+    private onError;
+    private streams;
+    /** Agent ids whose log could not be opened — never retried, so a broken
+     *  directory does not produce one failing stream per output chunk. */
+    private failed;
+    private closing;
+    constructor(logDir: string, onError?: (message: string) => void);
+    attach(eventBus: EventBus): () => void;
+    /**
+     * 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.
+     */
+    drain(): Promise<void>;
+    private handle;
+    private getStream;
+    private flush;
+}

package/dist/reporters/FileLogWriter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multiclaw",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "bin": {
     "multiclaw": "dist/index.js"
@@ -27,22 +27,22 @@
     "url": "https://github.com/shipengqi/multiclaw/issues"
   },
   "dependencies": {
-    "@agentclientprotocol/claude-agent-acp": "^0.89.1",
+    "@agentclientprotocol/claude-agent-acp": "^0.93.0",
     "@agentclientprotocol/codex-acp": "^2.2.2",
     "@inquirer/prompts": "^8.7.3",
-    "@multiclawcli/core": "0.4.0",
-    "@multiclawcli/dashboard": "0.4.0",
+    "@multiclawcli/core": "0.5.1",
+    "@multiclawcli/dashboard": "0.5.1",
     "commander": "^15.0.0",
     "jiti": "^2.7.0"
   },
   "devDependencies": {
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "tsx": "^4.7.0",
-    "typescript": "^5.4.0",
-    "vitest": "^4.1.11"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.4"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.json --emitDeclarationOnly --outDir dist --composite false --incremental false",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",