premanmcp 1.1.16 → 1.1.18

package/README.md

@@ -53,7 +53,7 @@ preman chat -p "list my endpoints"      # one turn, printed, then exit
 ```
 
 Inside a session: `/help`, `/new`, `/conversations`, `/resume <id>`, `/app`,
-`/eval`, `/clear`, `/exit`. `/eval list` shows what your agent can be measured
+`/swarm`, `/eval`, `/clear`, `/exit`. `/eval list` shows what your agent can be measured
 on, numbered; `/eval on 3 12` or `/eval on sycophancy` switches those on (a
 number, a `3-7` range, `all`, an id, or enough of one to be unambiguous), `/eval
 off` the same in reverse, and `/eval` runs what is on. `/eval defaults` reads
@@ -65,6 +65,30 @@ link underneath opens the PreMan desktop app when it is installed (a build older
 than 0.4.0 comes forward on whatever it was showing rather than on the run), and
 the run's dashboard URL is always printed with it.
 
+Ask the agent to launch a hosted-MCP swarm in plain language, just as in the
+app: “Launch a 12-attempt Codex swarm against my tracker server; ask it to find
+open issues and expect search_issues.” The terminal uses the same conversation
+service and approval rules. A proposed launch shows its summary in the terminal;
+choose “Approve exact action” to launch it, “Decline” to reject it, or Enter to
+leave it unanswered. A swarm result prints its label, status, run ID, and link.
+Piped sessions leave approvals unanswered for review in the app.
+
+For explicit commands inside the session, `/swarm` uses the current session's
+account, backend, and workspace:
+
+```text
+/swarm list
+/swarm launch --server tracker --ask "Find open issues" --expect search_issues --agents codex --size 12 --rivals 0
+/swarm watch <run-id>
+/swarm stop <run-id>
+```
+
+`/swarm help` lists every option. Add `--dry-run` to preview a launch without
+starting attempts. Ctrl+C while watching returns to the conversation and leaves
+the swarm running; `/swarm stop <run-id>` cancels it explicitly. The same commands
+work outside a session as `preman swarm list|launch|watch|stop|bank`. These run
+real agents against hosted MCPs; the app's sample swarms remain a separate demo.
+
 A session takes a screen of its own, the way `vim` does: nothing above it is
 scrollable, and leaving hands your shell back exactly as it was with one line
 saying how to resume. Ctrl+C stops the current turn (PreMan keeps working on it)

package/bin/agent.js

@@ -25,6 +25,7 @@ import { basename, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 import { createSseParser } from "./runner.js";
+import { SWARM_HELP, swarmCommand } from "./swarm.js";
 import {
   authenticateTerminal,
   backendUrl,
@@ -59,6 +60,10 @@ const SLASH_HELP = `Commands:
   /eval on|off <what>   Switch behaviours on or off, by number or by id
   /eval defaults        Pick a few that suit this project, and switch them on
   /eval doctor          Check this machine can run evals before starting one
+  /swarm list           List your hosted-MCP swarms
+  /swarm launch ...     Launch with the same flags as preman swarm launch
+  /swarm watch <id>     Follow a swarm; Ctrl+C returns to the conversation
+  /swarm help           Show launch, watch, stop and behavior-bank options
   /app                  Open this conversation in the PreMan app
   /clear                Clear the screen
   /exit                 Leave (Ctrl+D does the same)
@@ -212,6 +217,13 @@ export function artifactLine(artifact) {
   if (!artifact || typeof artifact !== "object") return "";
   const type = String(artifact.type || "");
   if (!type || SILENT_ARTIFACTS.has(type)) return "";
+  if (type === "swarm_run" && artifact.run?.id) {
+    const run = artifact.run;
+    const name = truncate(run.release_label || artifact.title || "Swarm", 60);
+    const line = [name, run.status, run.id].filter(Boolean).join(" · ");
+    const url = artifactUrl(artifact);
+    return url ? `${line} — ${url}` : line;
+  }
   const label =
     String(artifact.title || "").trim() || ARTIFACT_LABELS[type] || type.replace(/_/g, " ");
   const url = artifactUrl(artifact);
@@ -757,10 +769,82 @@ async function runTurn({
       ask,
       say,
     });
+    await askActionProposals({
+      args, token, workspaceId, artifacts: done.turn.artifacts, paint, ask, say, register,
+    });
   }
   return done;
 }
 
+/** Approve only a stored action on this session's backend; no tool-supplied URL is executed. */
+async function askActionProposals({ args, token, workspaceId, artifacts, paint, ask, say, register }) {
+  if (!process.stdin.isTTY) return;
+  const seen = new Set();
+  const proposals = (Array.isArray(artifacts) ? artifacts : []).filter((item) => {
+    const proposal = item?.type === "action_proposal" ? item.proposal : null;
+    const id = proposal?.id;
+    if (typeof id !== "string" || !/^[\w-]{1,128}$/.test(id) || seen.has(id)) return false;
+    if ((proposal.status || "pending") !== "pending") return false;
+    if (proposal.expires_at && Date.parse(proposal.expires_at) <= Date.now()) return false;
+    seen.add(id);
+    return true;
+  });
+  if (!proposals.length) return;
+  const write = say || ((text) => process.stdout.write(text));
+  const borrowed = typeof ask === "function";
+  const rl = borrowed ? null : createInterface({ input: process.stdin, output: process.stdout });
+  const readAnswer = borrowed ? ask : (text) => rl.question(text);
+  try {
+    for (const artifact of proposals.slice(0, 10)) {
+      const proposal = artifact.proposal;
+      const title = truncate(String(proposal.title || artifact.title || "Confirm action"), 240);
+      write(`\n${paint.yellow("PreMan needs a decision")}\n  ${title}\n`);
+      const summary = String(proposal.summary || artifact.summary || "").trim();
+      if (summary) write(`  ${truncate(summary, 1000)}\n`);
+      write(`  1. Approve exact action\n  2. Decline\n${paint.dim("  Enter to skip\n")}`);
+      const answer = String((await readAnswer("  > ")) || "").trim().toLowerCase();
+      const action = ["1", "y", "yes", "approve"].includes(answer) ? "approve"
+        : ["2", "n", "no", "decline"].includes(answer) ? "decline" : null;
+      if (!action) {
+        write(paint.dim("  Left unanswered.\n"));
+        continue;
+      }
+      if (proposal.expires_at && Date.parse(proposal.expires_at) <= Date.now()) {
+        write(paint.dim("  This action expired. Ask PreMan to regenerate it.\n"));
+        continue;
+      }
+      const controller = new AbortController();
+      register?.({ abort: () => controller.abort() });
+      try {
+        const response = await backendCall(args, "POST",
+          `/workbench/action-proposals/${encodeURIComponent(proposal.id)}/${action}`, {
+            token, signal: controller.signal,
+            headers: workspaceId ? { "x-workspace-id": workspaceId } : undefined,
+          });
+        const result = response.result;
+        const status = response.proposal?.status || "unknown";
+        if (result?.ok === false || result?.error) {
+          write(`  ${paint.red(describeFailure(result, "The action did not complete."))}\n`);
+        } else if (status === "completed" || status === "declined") {
+          write(`  ${paint.green("✓")} ${status === "completed" ? "Completed" : "Declined"}: ${title}\n`);
+          if (result?.run?.id) write(`  ${artifactLine({ type: "swarm_run", title, run: result.run, url: result.url })}\n`);
+        } else {
+          write(`  Action ${String(status).replaceAll("_", " ")}. Use /app to check its result.\n`);
+        }
+      } catch (error) {
+        write(controller.signal.aborted
+          ? "  Stopped waiting for the action result. Check /app before trying again.\n"
+          : `  ${paint.red(error?.message || String(error))}\n`);
+      } finally {
+        register?.(null);
+      }
+    }
+    if (proposals.length > 10) write("  More actions are awaiting a decision in /app.\n");
+  } finally {
+    if (rl) rl.close();
+  }
+}
+
 /**
  * Put a permission confirmation to the person at the keyboard.
  *
@@ -1956,6 +2040,64 @@ export async function runEval(rest, { args, token, dock, rl, paint, say, running
   }
 }
 
+/** Quoted flag values for a session command, without shell evaluation. */
+export function swarmArguments(rest) {
+  const words = [];
+  let word = "";
+  let quote = "";
+  let escaped = false;
+  let active = false;
+  for (const character of String(rest || "")) {
+    if (escaped) {
+      word += character;
+      escaped = false;
+    } else if (character === "\\" && quote !== "'") {
+      escaped = true;
+      active = true;
+    } else if (quote) {
+      if (character === quote) quote = "";
+      else word += character;
+    } else if (character === "'" || character === '"') {
+      quote = character;
+      active = true;
+    } else if (/\s/.test(character)) {
+      if (active) words.push(word);
+      word = "";
+      active = false;
+    } else {
+      word += character;
+      active = true;
+    }
+  }
+  if (quote || escaped) throw new Error("Finish the quoted value or escaped character in /swarm.");
+  if (active) words.push(word);
+  return words;
+}
+
+/** Reuse the CLI command inside the current authenticated conversation. */
+export async function runSwarm(rest, { args, token, workspaceId, say, paint, register }) {
+  const controller = new AbortController();
+  register?.({ abort: () => controller.abort() });
+  try {
+    const argv = swarmArguments(rest);
+    if (["help", "--help", "-h"].includes(argv[0])) {
+      say(`${SWARM_HELP}\n`);
+      return;
+    }
+    await swarmCommand(argv, {
+      sessionArgs: args, token, workspaceId, signal: controller.signal,
+      write: say, clearWatch: false,
+    });
+    say("\n");
+  } catch (error) {
+    say(controller.signal.aborted
+      ? "Stopped waiting. The swarm may still be running; /swarm list to check.\n\n"
+      : `${paint.red(error?.message || String(error))}\n\n`);
+  } finally {
+    register?.(null);
+  }
+}
+
 export async function agentCommand(commandArgs = [], { authenticate = authenticateTerminal } = {}) {
   const args = makeArgs(commandArgs);
   if (args.has("--help") || args.has("-h")) {
@@ -2067,6 +2209,7 @@ export async function agentCommand(commandArgs = [], { authenticate = authentica
     // Only reaches anything when a run is open, and the import is already
     // resolved by then -- the module was loaded to start the run.
     if (evaluating) void import("./eval.js").then(({ cancelEvalRuns }) => cancelEvalRuns());
+    turn?.abort();
   });
   hold.onTeardown(() => process.stdout.off("resize", onResize));
   hold.onTeardown(() => dock.disable());
@@ -2286,6 +2429,13 @@ export async function agentCommand(commandArgs = [], { authenticate = authentica
           });
           continue;
         }
+        if (slash.name === "swarm") {
+          await runSwarm(slash.rest, {
+            args, token, workspaceId: workspace.id, say, paint,
+            register: (handle) => { turn = handle; },
+          });
+          continue;
+        }
         if (slash.name === "app") {
           const url = `${frontendUrl(args)}/workbench/${conversation.id}`;
           openUrl(url);

package/bin/cli.js

@@ -36,6 +36,7 @@ import {
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
 import { PREDICT_HELP, predictCommand } from "./predict.js";
 import { STATUS_HELP, statusCommand } from "./status.js";
+import { SWARM_HELP, swarmCommand } from "./swarm.js";
 import { HOOK_HELP, hookCommand, installHook, scheduleHookRepair } from "./hook.js";
 import { EVAL_HELP } from "./eval.js";
 import { TARGET_HELP, targetCommand } from "./target.js";
@@ -142,6 +143,7 @@ function printHelp() {
     ["", "Chat with the PreMan agent in this terminal"],
     ["chat [message] [--continue]", "The same session, named explicitly"],
     ["status", "Healthy / failing / recently fixed endpoints"],
+    ["swarm list|launch|watch|stop|bank", "Send real coding agents to see if they pick your MCP tools"],
     ["verify [options]", "Test endpoints against your local app"],
     ["probe [options]", "Fire a population of simulated users at your local app"],
     ["hook install|uninstall|status", "Manage the git pre-push hook"],
@@ -178,7 +180,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${AGENT_HELP}${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${PROBE_HELP}${HOOK_HELP}${RUNNER_HELP}${EVAL_HELP}${TARGET_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${PREDICT_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
+${AGENT_HELP}${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${SWARM_HELP}${VERIFY_HELP}${PROBE_HELP}${HOOK_HELP}${RUNNER_HELP}${EVAL_HELP}${TARGET_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${PREDICT_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -375,6 +377,8 @@ async function main() {
     await loginCommand();
   } else if (command === "status") {
     await statusCommand(commandArgs);
+  } else if (command === "swarm") {
+    await swarmCommand(commandArgs);
   } else if (command === "verify") {
     await verifyCommand(commandArgs);
   } else if (command === "probe") {

package/bin/swarm.js

@@ -0,0 +1,373 @@
+/**
+ * `preman swarm` — send real coding agents at a hosted MCP and see whether
+ * they pick its tools, from the terminal.
+ *
+ * A swarm is a harness matrix run, so every call here goes to `/matrix`; the
+ * dashboard's Swarms page reads the same runs. What this adds is the swarm's
+ * vocabulary: agents grouped by where developers run them (terminal, IDE,
+ * desktop app), each with how often it picked the tool, and the rival that
+ * won when it did not.
+ */
+
+import { setTimeout as wait } from "node:timers/promises";
+
+import {
+  backendUrl,
+  callBackendJson,
+  cliInvocation,
+  describeFailure,
+  frontendUrl,
+  makeArgs,
+  resolveApiKey,
+  truncate,
+} from "./shared.js";
+
+export const SWARM_HELP = `
+Swarm options:
+  preman swarm list                       Recent swarms and what each found
+  preman swarm launch --server <slug|id> --ask "<what a developer asks>" [--ask ...]
+        [--expect tool,tool] [--agents claude_code,codex,...] [--rivals 0,5]
+        [--size 60] [--name <label>] [--dry-run]
+                                          Start a swarm (--dry-run only counts it)
+  preman swarm watch <id> [--once]        Follow a swarm until it finishes
+  preman swarm stop <id>                  Stop a swarm; unfinished agents do not run
+  preman swarm bank [--server <slug|id>]  Behaviors PreMan learned and you kept
+  --json                                  Print the raw JSON instead
+`;
+
+const ENVIRONMENTS = [
+  { id: "terminal", label: "Terminal", harnesses: ["claude_code", "codex", "cursor_cli"] },
+  { id: "ide", label: "IDE", harnesses: ["cursor_ide"] },
+  { id: "desktop", label: "Desktop app", harnesses: ["claude_desktop", "codex_desktop"] },
+];
+
+const AGENT_NAMES = {
+  claude_code: "Claude Code",
+  codex: "Codex CLI",
+  cursor_cli: "Cursor CLI",
+  cursor_ide: "Cursor",
+  claude_desktop: "Claude Desktop",
+  codex_desktop: "Codex Desktop",
+};
+
+const TERMINAL = new Set(["done", "failed", "cancelled"]);
+const POLL_MS = 5000;
+
+function environmentOf(harness) {
+  return ENVIRONMENTS.find((env) => env.harnesses.includes(harness))?.id || "other";
+}
+
+function paintFor(enabled) {
+  const wrap = (code) => (text) => (enabled ? `\u001b[${code}m${text}\u001b[0m` : String(text));
+  return { green: wrap("32"), red: wrap("31"), yellow: wrap("33"), dim: wrap("2"), bold: wrap("1") };
+}
+
+function colourEnabled(args) {
+  if (args.has("--no-color") || process.env.NO_COLOR) return false;
+  return Boolean(process.stdout.isTTY);
+}
+
+/** Every value of a repeatable flag, in order. */
+export function allValues(raw, name) {
+  const out = [];
+  for (let i = 0; i < raw.length; i += 1) {
+    if (raw[i] === name && raw[i + 1] !== undefined) out.push(raw[i + 1]);
+  }
+  return out;
+}
+
+/** Values not taken by a flag: `stop --backend <url> <id>` names the swarm, not the url. */
+export function positionals(raw) {
+  const out = [];
+  for (let i = 0; i < raw.length; i += 1) {
+    if (raw[i].startsWith("--")) {
+      if (raw[i + 1] !== undefined && !raw[i + 1].startsWith("--") && !BARE_FLAGS.has(raw[i])) i += 1;
+      continue;
+    }
+    out.push(raw[i]);
+  }
+  return out;
+}
+
+const BARE_FLAGS = new Set(["--json", "--once", "--dry-run", "--no-color"]);
+
+function listOf(value) {
+  return String(value || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+/** A Wilson 95% interval, so a small swarm never reads as certain. */
+export function likelyRange(hits, n) {
+  if (!n) return null;
+  const z = 1.96;
+  const p = hits / n;
+  const d = 1 + (z * z) / n;
+  const c = p + (z * z) / (2 * n);
+  const m = z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n));
+  return [Math.max(0, (c - m) / d), Math.min(1, (c + m) / d)];
+}
+
+const pct = (rate) => (rate === null || rate === undefined ? "—" : `${Math.round(rate * 100)}%`);
+
+/**
+ * The swarm by environment and agent, from its cells.
+ *
+ * The same rules as the dashboard: a cell with no verdict is not a miss, and
+ * two arms of one harness are two agents whose rates are never pooled.
+ */
+export function summarize(cells) {
+  const agents = new Map();
+  for (const cell of cells || []) {
+    const arm = cell.tool_visibility || "deferred";
+    const key = `${cell.harness}/${arm}`;
+    const agent = agents.get(key) || {
+      key,
+      harness: cell.harness,
+      arm,
+      environment: environmentOf(cell.harness),
+      picked: 0,
+      scored: 0,
+      running: 0,
+      queued: 0,
+      lostTo: new Map(),
+    };
+    if (cell.status === "running") agent.running += 1;
+    else if (cell.status === "queued") agent.queued += 1;
+    const expected = new Set([
+      ...(cell.evidence?.expected?.tools || []),
+      cell.evidence?.expected?.tool,
+      ...(cell.evidence?.expected?.alternates || []),
+    ].filter(Boolean));
+    const called = cell.evidence?.tools_called || [];
+    // Missing search telemetry cannot erase a recorded selection or call to
+    // the expected tool. Codex can call it without emitting a tool search.
+    const sawExpected = cell.selected === true || called.some((tool) => expected.has(tool));
+    const unseen = !sawExpected && cell.evidence?.tool_surfaced_by_search === false && arm === "deferred";
+    if ((cell.selected === true || cell.selected === false) && !unseen) {
+      agent.scored += 1;
+      if (cell.selected) agent.picked += 1;
+      else {
+        for (const tool of called) {
+          if (!expected.has(tool)) agent.lostTo.set(tool, (agent.lostTo.get(tool) || 0) + 1);
+        }
+      }
+    }
+    agents.set(key, agent);
+  }
+  const arms = new Map();
+  for (const agent of agents.values()) arms.set(agent.harness, (arms.get(agent.harness) || 0) + 1);
+  for (const agent of agents.values()) {
+    agent.name = AGENT_NAMES[agent.harness] || agent.harness;
+    if (arms.get(agent.harness) > 1) {
+      agent.name += agent.arm === "deferred" ? " (on demand)" : " (always loaded)";
+    }
+    agent.rate = agent.scored ? agent.picked / agent.scored : null;
+  }
+  const groups = [...ENVIRONMENTS, { id: "other", label: "Elsewhere" }]
+    .map((env) => ({ ...env, agents: [...agents.values()].filter((a) => a.environment === env.id) }))
+    .filter((env) => env.agents.length);
+  const picked = [...agents.values()].reduce((sum, a) => sum + a.picked, 0);
+  const scored = [...agents.values()].reduce((sum, a) => sum + a.scored, 0);
+  return { groups, picked, scored, total: (cells || []).length };
+}
+
+export function renderSwarm(run, cells, { colour = false } = {}) {
+  const paint = paintFor(colour);
+  const summary = summarize(cells);
+  const done = (cells || []).filter((cell) => cell.status === "done" || cell.status === "failed").length;
+  const lines = [];
+  lines.push(
+    `${paint.bold(run.release_label || run.id)}  ${paint.dim(run.hosted_mcp_name || run.hosted_mcp_slug || "")}  ${run.status}`
+  );
+  if (summary.scored) {
+    const range = likelyRange(summary.picked, summary.scored);
+    lines.push(
+      `${TERMINAL.has(run.status) ? "Agents" : "So far, agents"} picked your tool ${summary.picked} of ${summary.scored} times ` +
+        paint.dim(`(likely ${Math.round(range[0] * 100)}–${Math.round(range[1] * 100)}%)`)
+    );
+  } else {
+    lines.push(paint.dim(TERMINAL.has(run.status) ? "Nothing was scored." : "Agents are on their way."));
+  }
+  lines.push(paint.dim(`${done} of ${summary.total} attempts done`));
+  for (const group of summary.groups) {
+    lines.push("");
+    lines.push(paint.bold(group.label));
+    for (const agent of group.agents) {
+      const rate = agent.rate === null ? paint.dim("—") : agent.rate >= 0.75 ? paint.green(pct(agent.rate)) : agent.rate >= 0.4 ? paint.yellow(pct(agent.rate)) : paint.red(pct(agent.rate));
+      const working = agent.running ? paint.dim(` · ${agent.running} working`) : "";
+      const rival = [...agent.lostTo.entries()].sort((a, b) => b[1] - a[1])[0];
+      const lost = rival ? paint.dim(` · lost to ${rival[0]} ×${rival[1]}`) : "";
+      lines.push(`  ${truncate(agent.name, 30).padEnd(30)} ${String(rate).padStart(colour ? 13 : 4)}  ${paint.dim(`${agent.picked}/${agent.scored}`)}${working}${lost}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function headlineFromRollup(run) {
+  const bucket = run?.rollup?.by_harness_visibility || {};
+  let hits = 0;
+  let n = 0;
+  for (const value of Object.values(bucket)) {
+    hits += value?.selected?.hits || 0;
+    n += value?.selected?.n || 0;
+  }
+  return n ? `picked ${hits} of ${n}` : "";
+}
+
+function requireToken(args) {
+  const token = resolveApiKey(args);
+  if (!token) {
+    throw new Error(`no PreMan API key found. Run \`${cliInvocation()} login\` first, or pass --api-key.`);
+  }
+  return token;
+}
+
+async function call(args, token, method, path, options = {}) {
+  const result = await callBackendJson(args, method, path, { token, ...options });
+  if (!result.ok) {
+    throw new Error(`${method} ${path} on ${backendUrl(args)}: ${result.status_code} ${describeFailure(result, "request failed")}`);
+  }
+  return result;
+}
+
+async function findServer(request, ref) {
+  if (/^[0-9a-f-]{36}$/i.test(ref)) return { id: ref, name: ref };
+  const result = await request("GET", "/hosted-mcps");
+  const servers = result.hosted_mcps || result.list || [];
+  const match = servers.find((server) => [server.slug, server.name, server.id].includes(ref));
+  if (!match) {
+    const names = servers.map((server) => server.slug || server.name).filter(Boolean).join(", ");
+    throw new Error(`no hosted MCP called "${ref}"${names ? `. Yours: ${names}` : ""}`);
+  }
+  return match;
+}
+
+async function readSwarm(request, id) {
+  const run = await request("GET", `/matrix/runs/${encodeURIComponent(id)}`);
+  const cells = await request("GET", `/matrix/runs/${encodeURIComponent(id)}/cells`);
+  const { status_code, ok, ...runBody } = run;
+  return { run: runBody, cells: cells.cells || cells.list || [] };
+}
+
+function swarmLink(args, id) {
+  return `${frontendUrl(args)}/workbench/swarms/swarms/${encodeURIComponent(id)}`;
+}
+
+export async function swarmCommand(commandArgs = [], {
+  sessionArgs, token: sessionToken, workspaceId, signal,
+  write = (text) => process.stdout.write(text), clearWatch = true,
+} = {}) {
+  const [sub = "list", ...rest] = commandArgs;
+  // A session's credential stays with its backend even when slash-command
+  // arguments contain transport overrides. First occurrence wins in makeArgs.
+  const args = makeArgs(sessionArgs ? [
+    "--backend", backendUrl(sessionArgs), "--frontend", frontendUrl(sessionArgs),
+    ...(sessionArgs.has("--no-color") || sessionArgs.has("--no-colour") ? ["--no-color"] : []), ...rest,
+  ] : rest);
+  const json = args.has("--json");
+  const colour = colourEnabled(args);
+  const token = sessionToken || requireToken(args);
+  const request = (method, path, options = {}) => call(args, token, method, path, {
+    ...options, signal, ...(workspaceId ? { headers: { "x-workspace-id": workspaceId } } : {}),
+  });
+
+  if (sub === "list") {
+    const result = await request("GET", "/matrix/runs");
+    const runs = result.runs || result.list || [];
+    if (json) return void write(`${JSON.stringify(runs, null, 2)}\n`);
+    if (!runs.length) {
+      write(`No swarms yet. Start one with \`${cliInvocation()} swarm launch\`.\n`);
+      return;
+    }
+    for (const run of runs.slice(0, 20)) {
+      write(
+        `${String(run.id).slice(0, 8)}  ${truncate(run.release_label || "", 32).padEnd(32)}  ` +
+          `${truncate(run.hosted_mcp_name || run.hosted_mcp_slug || "", 20).padEnd(20)}  ${String(run.status).padEnd(9)}  ${headlineFromRollup(run)}\n`
+      );
+    }
+    return;
+  }
+
+  if (sub === "launch") {
+    const asks = allValues(rest, "--ask");
+    const serverRef = args.value("--server");
+    if (!serverRef || !asks.length) {
+      throw new Error(`a swarm needs --server and at least one --ask.${SWARM_HELP}`);
+    }
+    const server = await findServer(request, serverRef);
+    const expect = listOf(args.value("--expect"));
+    const payload = {
+      hosted_mcp_id: server.id,
+      asks: asks.map((prompt) => ({ prompt, expected_tools: expect })),
+      distractor_levels: listOf(args.value("--rivals", "0,5")).map(Number).filter((n) => Number.isFinite(n)),
+      target_size: Number(args.value("--size", "60")),
+      release_label: args.value("--name") || `cli ${new Date().toISOString().slice(0, 16).replace("T", " ")}`,
+    };
+    if (!Number.isInteger(payload.target_size) || payload.target_size < 1) {
+      throw new Error("--size must be a whole number of attempts, 1 or more.");
+    }
+    const agents = listOf(args.value("--agents"));
+    if (agents.length) payload.harnesses = agents;
+    if (args.has("--dry-run")) payload.dry_run = true;
+    const result = await request("POST", "/matrix/runs", { json: payload });
+    const { status_code, ok, ...body } = result;
+    if (json) return void write(`${JSON.stringify(body, null, 2)}\n`);
+    if (payload.dry_run) {
+      write(`Would send ${body.cell_count ?? "?"} attempts (${body.asks_used ?? asks.length} asks, ${body.replicates ?? 1}× each).\n`);
+      return;
+    }
+    write(`Swarm ${body.id} launched against ${server.name || server.slug}.\n`);
+    write(`  Watch:  ${cliInvocation()} swarm watch ${body.id}\n  Open:   ${swarmLink(args, body.id)}\n`);
+    return;
+  }
+
+  if (sub === "watch" || sub === "show") {
+    const [id] = positionals(rest);
+    if (!id) throw new Error(`which swarm? ${cliInvocation()} swarm watch <id>`);
+    for (;;) {
+      const { run, cells } = await readSwarm(request, id);
+      if (json) {
+        write(`${JSON.stringify({ run, summary: summarize(cells) }, (k, v) => (v instanceof Map ? Object.fromEntries(v) : v), 2)}\n`);
+      } else {
+        if (clearWatch && process.stdout.isTTY && sub === "watch") write("\u001b[2J\u001b[H");
+        write(renderSwarm(run, cells, { colour }));
+      }
+      if (sub === "show" || args.has("--once") || TERMINAL.has(run.status)) {
+        if (!json) write(`\n${swarmLink(args, id)}\n`);
+        return;
+      }
+      await wait(POLL_MS, undefined, { signal });
+    }
+  }
+
+  if (sub === "stop") {
+    const [id] = positionals(rest);
+    if (!id) throw new Error(`which swarm? ${cliInvocation()} swarm stop <id>`);
+    await request("POST", `/matrix/runs/${encodeURIComponent(id)}/cancel`);
+    write(`Stopped ${id}. Agents that had not finished will not run.\n`);
+    return;
+  }
+
+  if (sub === "bank") {
+    const serverRef = args.value("--server");
+    const server = serverRef ? await findServer(request, serverRef) : null;
+    const result = await request("GET", "/swarms/behaviors", {
+      query: server ? { hosted_mcp_id: server.id } : undefined,
+    });
+    const kept = (result.behaviors || []).filter((row) => row.status === "kept");
+    if (json) return void write(`${JSON.stringify(kept, null, 2)}\n`);
+    if (!kept.length) {
+      write("Nothing kept yet. After a swarm, keep the patterns PreMan finds in its misses.\n");
+      return;
+    }
+    for (const row of kept) {
+      write(`${row.hosted_mcp_name || ""}  ${row.title}  (${row.evidence?.count || 0} attempts)\n`);
+      for (const ask of (row.seed?.asks || []).slice(0, 3)) write(`    “${truncate(ask.prompt, 70)}”\n`);
+    }
+    return;
+  }
+
+  throw new Error(`unknown swarm command "${sub}".${SWARM_HELP}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "description": "PreMan CLI and stdio proxy for PreMan's hosted MCP server",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "test:proxy": "node --test scripts/smoke-proxy.mjs",
     "test:connect": "node scripts/smoke-connect.mjs",
     "test:connect-heartbeat": "node scripts/smoke-connect-heartbeat.mjs",
-    "test:node": "node --test --test-timeout=90000 scripts/smoke-account.mjs scripts/smoke-agent-session.mjs scripts/smoke-agent-dock.mjs scripts/smoke-terminal-lifecycle.mjs scripts/smoke-cli-entrypoint.mjs scripts/smoke-cli-update.mjs scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-eval.mjs scripts/smoke-eval-start.mjs scripts/smoke-eval-run-watch.mjs scripts/smoke-eval-behaviors.mjs scripts/smoke-eval-runtime.mjs scripts/smoke-eval-entry.mjs scripts/smoke-eval-entry-placeholder.mjs scripts/smoke-eval-discover.mjs scripts/smoke-eval-templates.mjs scripts/smoke-eval-decorated-capture.mjs scripts/smoke-eval-decorate-approval.mjs scripts/smoke-eval-approval-record.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-onboard-opening.mjs scripts/smoke-local-detect.mjs scripts/smoke-agent-target.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs scripts/smoke-desktop-session.mjs scripts/smoke-api-tools.mjs scripts/smoke-tests-workbench.mjs scripts/smoke-bin-scope.mjs scripts/smoke-shared-errors.mjs scripts/smoke-prompts.mjs scripts/smoke-process-title.mjs scripts/smoke-predict.mjs",
+    "test:node": "node --test --test-timeout=90000 scripts/smoke-account.mjs scripts/smoke-agent-session.mjs scripts/smoke-agent-dock.mjs scripts/smoke-terminal-lifecycle.mjs scripts/smoke-cli-entrypoint.mjs scripts/smoke-cli-update.mjs scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-eval.mjs scripts/smoke-eval-start.mjs scripts/smoke-eval-run-watch.mjs scripts/smoke-eval-behaviors.mjs scripts/smoke-eval-runtime.mjs scripts/smoke-eval-entry.mjs scripts/smoke-eval-entry-placeholder.mjs scripts/smoke-eval-discover.mjs scripts/smoke-eval-templates.mjs scripts/smoke-eval-decorated-capture.mjs scripts/smoke-eval-decorate-approval.mjs scripts/smoke-eval-approval-record.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-onboard-opening.mjs scripts/smoke-local-detect.mjs scripts/smoke-agent-target.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs scripts/smoke-desktop-session.mjs scripts/smoke-api-tools.mjs scripts/smoke-tests-workbench.mjs scripts/smoke-bin-scope.mjs scripts/smoke-shared-errors.mjs scripts/smoke-prompts.mjs scripts/smoke-process-title.mjs scripts/smoke-predict.mjs scripts/smoke-swarm.mjs",
     "test:dmg": "node --test --test-timeout=300000 scripts/smoke-install-desktop-volume.mjs"
   },
   "devDependencies": {