@ra3orblade/swarm 0.4.1 → 0.6.0

package/README.md

@@ -22,7 +22,7 @@ A local-first control plane for AI-agent development on any repository.</p>
   <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-lightgrey?labelColor=0e1013"></a>
 </p>
 
-<p align="center"><a href="https://getswarm.vercel.app"><img src="docs/art/screens/fleet.jpg" alt="Swarm Fleet view — every agent session on the machine, live" width="100%"></a></p>
+<p align="center"><a href="https://getswarm.vercel.app"><img src="docs/art/screens/fleet.png" alt="Swarm Fleet view — every agent session on the machine, live" width="100%"></a></p>
 
 Run more than one [Claude Code](https://claude.com/claude-code) session at a time — or a [Codex CLI](https://github.com/openai/codex) or Grok run on the side — and you lose the thread fast: which session is on which branch, what it's costing, which worktree has uncommitted work nobody owns, why that edit got blocked. Swarm is one daemon that watches every session on your machine — live tool calls, reasoning, token spend, cost — keeps a ledger of who holds which task, worktree and runtime resource, turns the "never do X" prose in `CLAUDE.md` into real permission decisions, and streams all of it to one dashboard.
 
@@ -42,11 +42,11 @@ bunx @ra3orblade/swarm setup
 
 **Session** — an agent's reasoning and tool calls as a live stream, with cost per turn, cache hit rate, thinking share, tool histogram and the transcript path.
 
-<p align="center"><img src="docs/art/screens/session.jpg" alt="Session view — live reasoning stream with a stats panel" width="100%"></p>
+<p align="center"><img src="docs/art/screens/session.png" alt="Session view — live reasoning stream with a stats panel" width="100%"></p>
 
 **Board** — the coordination ledger for a project: task **claims** (each in an isolated git worktree), **worktrees** with branch, dirty/unpushed state and which session is inside, **runtime resources** (ports, dev servers, databases held as named singletons), and **incidents** — every command the rules asked about or denied, with the rule and the command.
 
-<p align="center"><img src="docs/art/screens/board.jpg" alt="Board view — worktrees and incidents" width="100%"></p>
+<p align="center"><img src="docs/art/screens/board.png" alt="Board view — worktrees and incidents" width="100%"></p>
 
 **Rules** — guardrails on the Bash commands a Claude Code session runs: `shared_tree`, `destructive_git`, `pattern_kill`, `protected_ports`, plus `no_foreign_worktree` and the opt-in `claim_required_to_write` on file writes; each `ask | deny | off` per repo in `.swarm.toml`. A `deny` is returned to Claude Code as a real permission denial. Ports held as resources are protected automatically. Guardrails against accidents, not a sandbox — see [what rules are and aren't](https://getswarm.vercel.app/docs/03-rules-and-config#what-rules-are--and-arent).
 
@@ -54,11 +54,11 @@ bunx @ra3orblade/swarm setup
 
 **Timeline** — session lanes per project, coloured by agent, 3–72 h.
 
-<p align="center"><img src="docs/art/screens/timeline.jpg" alt="Timeline view — session lanes per project" width="100%"></p>
+<p align="center"><img src="docs/art/screens/timeline.png" alt="Timeline view — session lanes per project" width="100%"></p>
 
 **Spend & Stats** — cost by project, model and agent, today and all-time; plus the fun numbers: tokens, turns, streaks, activity calendar, words written, what it adds up to in novels and coffee.
 
-<p align="center"><img src="docs/art/screens/stats.jpg" alt="Stats view" width="100%"></p>
+<p align="center"><img src="docs/art/screens/stats.png" alt="Stats view" width="100%"></p>
 
 **Multi-agent** — Claude Code via its hooks and transcripts; Codex CLI and Grok by tailing the session logs they already write (`~/.codex`, ACP `updates.jsonl`). Every session is tagged with its agent; Spend breaks down per agent.
 

package/dist/swarm-mcp.js

@@ -19723,6 +19723,7 @@ async function ensureDaemon(opts = {}) {
 }
 // packages/mcp/src/server.ts
 var OWNER = process.env.SWARM_OWNER ?? "agent";
+var SESSION = process.env.CLAUDE_SESSION_ID ?? null;
 async function api2(path, init) {
   const base = await ensureDaemon({ quiet: true }).catch(() => resolveBaseUrl());
   const r = await fetch(`${base}${path}`, init);
@@ -19764,6 +19765,29 @@ function buildServer() {
       resources
     });
   });
+  server.registerTool("swarm_search", {
+    title: "Search Swarm's memory",
+    description: "Full-text search over what Swarm remembers about this repo: handoffs (what was done / what's left), incidents (commands the rules stopped, and why), gate runs (rubric + evidence) and what previous sessions last said. Not the codebase \u2014 grep that. Words are AND-ed, the last one is a prefix; quote a phrase; `kind:incident` / `task:M1.2` filter. Use it before redoing work someone may have done, or when a rule blocks you and you want to know how it was handled before.",
+    inputSchema: {
+      query: exports_external.string(),
+      kind: exports_external.enum(["handoff", "incident", "gate", "session"]).optional(),
+      all_projects: exports_external.boolean().optional().describe("search every project, not just this repo"),
+      limit: exports_external.number().int().min(1).max(100).optional()
+    }
+  }, async ({ query, kind, all_projects, limit }) => {
+    const q = new URLSearchParams({ q: query, limit: String(limit ?? 20) });
+    if (!all_projects)
+      q.set("project", await projectId());
+    if (kind)
+      q.set("kind", kind);
+    const r = await api2(`/v1/memory?${q}`);
+    if (!r.hits.length)
+      return ok(`nothing in memory matches "${query}"`, { hits: [] });
+    return ok(r.hits.map((h) => `[${h.kind}] ${h.title}${h.task ? ` (${h.task})` : ""} \u2014 ${h.ts.slice(0, 16)}
+${h.text}`).join(`
+
+`), r.hits);
+  });
   server.registerTool("swarm_next_task", {
     title: "Next claimable task",
     description: "The first unclaimed task in this repo's task source whose dependencies are done \u2014 what to pick up next. Needs `[tasks] source` in .swarm.toml. Pass all=true to list every ready task.",
@@ -19782,6 +19806,92 @@ function buildServer() {
     const n = ready[0];
     return ok(`next: ${n.id} \u2014 ${n.title} (claim it with swarm_claim)`, n);
   });
+  server.registerTool("swarm_handoff", {
+    title: "Leave a handoff",
+    description: "Before stopping or releasing a task, record what was done, what remains (in order), files worth reading first, and how to verify. The next session that starts in this task's worktree receives it automatically as context; `swarm_resume` reads it on demand.",
+    inputSchema: {
+      task: exports_external.string(),
+      done: exports_external.string().describe("what was finished"),
+      remaining: exports_external.string().describe("what is left, in the order to do it"),
+      files: exports_external.array(exports_external.string()).optional().describe("files touched or to read first"),
+      verify: exports_external.string().optional().describe("how to verify the work so far")
+    }
+  }, async ({ task, done, remaining, files, verify }) => {
+    const pid = await projectId();
+    const r = await api2("/v1/handoffs", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        projectId: pid,
+        task,
+        done,
+        remaining,
+        files: files ?? [],
+        verify: verify ?? null,
+        by: OWNER,
+        sessionId: SESSION
+      })
+    });
+    if (!r.ok)
+      return fail(`REFUSED: ${r.error}`);
+    return ok(`handoff recorded on ${task}`, r.handoff);
+  });
+  server.registerTool("swarm_resume", {
+    title: "Read the latest handoff",
+    description: "The latest handoff on a task: done, remaining, files, verify. Read it before continuing someone else's work. Handoffs marked `auto:` were derived by Swarm from what the previous session did (files edited, last verify command) when it stopped without leaving one.",
+    inputSchema: { task: exports_external.string() }
+  }, async ({ task }) => {
+    const pid = await projectId();
+    const j = await api2(`/v1/handoffs?project=${pid}&task=${encodeURIComponent(task)}`);
+    if (!j.text)
+      return ok(`no handoff on ${task}`, null);
+    return ok(j.text, j.handoff);
+  });
+  server.registerTool("swarm_gate_record", {
+    title: "Record a verification gate",
+    description: "Record the result of a verification gate (review, tests, security, \u2026) on a task. The rubric \u2014 what you actually checked \u2014 is required; a verdict without one is rejected. The latest run of a gate decides; failed runs stay on record and open an incident. Check `swarm_gates` for the gates this repo requires.",
+    inputSchema: {
+      task: exports_external.string().describe("task id, e.g. M1.2"),
+      gate: exports_external.string().describe("gate name, e.g. review, tests, security"),
+      verdict: exports_external.enum(["pass", "fail"]),
+      rubric: exports_external.string().describe("what was checked, concretely"),
+      evidence: exports_external.string().optional().describe("how: command output, PR link, notes")
+    }
+  }, async ({ task, gate, verdict, rubric, evidence }) => {
+    const pid = await projectId();
+    const r = await api2("/v1/gates", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        projectId: pid,
+        task,
+        gate,
+        verdict,
+        rubric,
+        evidence,
+        sessionId: SESSION
+      })
+    });
+    if (!r.ok)
+      return fail(`REFUSED: ${r.error}`);
+    return ok(`recorded ${gate} ${verdict} on ${task}`, r.run);
+  });
+  server.registerTool("swarm_gates", {
+    title: "Gate status",
+    description: "The gates this repo requires (.swarm.toml [gates] required) and, for a task, the latest verdict per gate with run history. A task is done only when every required gate's latest run is a pass.",
+    inputSchema: { task: exports_external.string().optional() }
+  }, async ({ task }) => {
+    const pid = await projectId();
+    const q = new URLSearchParams({ project: pid });
+    if (task)
+      q.set("task", task);
+    const g = await api2(`/v1/gates?${q}`);
+    const head = g.required.length ? `required: ${g.required.join(", ")}` : "no required gates declared";
+    const body = task ? (g.status ?? []).map((s) => `${s.gate}: ${s.verdict ?? "not run"}`).join(`
+`) || `no runs on ${task}` : `${g.runs.length} runs`;
+    return ok(`${head}
+${body}`, g);
+  });
   server.registerTool("swarm_claim", {
     title: "Claim a task",
     description: "Claim a task and get an isolated git worktree to work in. Fails closed if another session holds it \u2014 pick another task or coordinate. cd into the returned worktree before editing.",

package/dist/swarm.js

@@ -147,10 +147,51 @@ var HOOK_EVENTS = [
 // packages/core/src/rules.ts
 var LIVE_WINDOW_MS = 10 * 60000;
 var WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+// packages/core/src/ledger.ts
+var EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
 // packages/cli/src/install.ts
 var MARK = "swarm-hook";
 var isOurs = (h) => h.command.includes(MARK) || h.command.includes("/packages/hook/src/bin.ts");
 var settingsPath = () => process.env.CLAUDE_SETTINGS ?? join2(homedir2(), ".claude", "settings.json");
+var claudeJsonPath = () => process.env.CLAUDE_JSON ?? join2(homedir2(), ".claude.json");
+function loadClaudeJson() {
+  const p = claudeJsonPath();
+  if (!existsSync3(p))
+    return {};
+  try {
+    return JSON.parse(readFileSync2(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveClaudeJson(c) {
+  writeFileSync2(claudeJsonPath(), `${JSON.stringify(c, null, 2)}
+`);
+}
+function registerMcp() {
+  const c = loadClaudeJson();
+  const mcp = c.mcpServers ?? {};
+  mcp.swarm = { type: "stdio", ...mcpServerConfig() };
+  c.mcpServers = mcp;
+  saveClaudeJson(c);
+}
+function unregisterMcp() {
+  const c = loadClaudeJson();
+  const mcp = c.mcpServers ?? {};
+  if (!mcp.swarm)
+    return false;
+  delete mcp.swarm;
+  if (Object.keys(mcp).length)
+    c.mcpServers = mcp;
+  else
+    delete c.mcpServers;
+  saveClaudeJson(c);
+  return true;
+}
+function mcpRegistered() {
+  const c = loadClaudeJson();
+  return Boolean(c.mcpServers?.swarm);
+}
 var hookCommand = (event) => `${binCommand("swarm-hook")} ${event}`;
 var shimPath = () => resolveBin("swarm-hook").at(-1);
 function mcpServerConfig() {
@@ -179,10 +220,16 @@ function install() {
     added.push(ev);
   }
   s.hooks = hooks2;
-  const mcp = s.mcpServers ?? {};
-  mcp.swarm = { type: "stdio", ...mcpServerConfig() };
-  s.mcpServers = mcp;
+  const stale = s.mcpServers ?? {};
+  if (stale.swarm) {
+    delete stale.swarm;
+    if (Object.keys(stale).length)
+      s.mcpServers = stale;
+    else
+      delete s.mcpServers;
+  }
   save(s);
+  registerMcp();
   return added;
 }
 function uninstall() {
@@ -211,23 +258,22 @@ function uninstall() {
   else
     delete s.hooks;
   const mcp = s.mcpServers ?? {};
-  if (mcp.swarm) {
+  if (mcp.swarm)
     delete mcp.swarm;
-    removed++;
-  }
   if (Object.keys(mcp).length)
     s.mcpServers = mcp;
   else
     delete s.mcpServers;
   save(s);
+  if (unregisterMcp())
+    removed++;
   return removed;
 }
 function status() {
   const s = load();
   const hooks2 = s.hooks ?? {};
   const installed = Object.values(hooks2).some((l) => l.some((g) => g.hooks.some(isOurs)));
-  const mcp = Boolean(s.mcpServers?.swarm);
-  return { installed, mcp, path: settingsPath(), shim: shimPath() };
+  return { installed, mcp: mcpRegistered(), path: settingsPath(), shim: shimPath() };
 }
 
 // packages/cli/src/procs.ts
@@ -348,6 +394,14 @@ var help = `swarm \u2014 control plane for AI-agent development
   renew <task>            extend the lease;  release <task> [--force]   release + remove worktree
   claims                  list claims;  reap   release abandoned claims (keeps ones holding work)
   tasks [--ready] [--json] the repo's task source (.swarm.toml [tasks] source); --ready = claimable now
+  gate record <task> <gate> pass|fail --rubric "\u2026" [--evidence "\u2026"]   record a verification run (rubric required)
+  gate ls [task]          latest verdict per gate (and the run history for one task)
+  run --task <id> (--prompt "\u2026" | --prompt-file f) [--model m] [--permission-mode m] [--allowed-tools a,b] [--max-turns n]
+                          claim the task and spawn claude -p in its worktree; the session shows in Fleet
+  run ls | send <task|id> "text" | stop <task|id>   steer (stdin) or stop a spawned run, by pid never pattern
+  run resume <session-id> [--model m] [--permission-mode m]   spawn a run that picks up where a dead session stopped (its handoff + tail)
+  handoff <task> --done "\u2026" --remaining "\u2026" [--files a,b] [--verify "\u2026"]   leave notes for the next holder
+  resume <task>           print the latest handoff (the next session gets it automatically on start)
   res ls | acquire <name> [--owner n] [--pid n] [--port n] | release <name> [--force]
                           named singletons (ports, processes); fail-closed
   serve start [--name web] [--from-port 3400 | --port n] -- <cmd>
@@ -355,6 +409,8 @@ var help = `swarm \u2014 control plane for AI-agent development
   serve ls | stop [name]  list / stop servers this project started (by pid, never by pattern)
   proc start [--name n] -- <cmd> | ls | stop <name|pid>   same, for workers without a port
   stats [-p] [--json]     all-time totals, streak, records (the dashboard's Stats view)
+  search <query\u2026> [-p] [--kind handoff|incident|gate|session] [--json]   memory over Swarm's own data (handoffs, incidents, gates, what sessions said)
+  rules dryrun [--set rule=mode,\u2026] [--limit n] [--json]   replay this repo's history under rule modes; shows what would fire + flaky signals
 
   install | uninstall     add/remove Swarm hooks in ~/.claude/settings.json
 
@@ -546,6 +602,305 @@ url: ${resolveBaseUrl()}`);
           console.log(`${c.state.padEnd(9)} ${c.task.padEnd(16)} ${(c.owner || "").padEnd(12)} ${c.worktree}`);
       break;
     }
+    case "run": {
+      await ensureDaemon({ quiet: true });
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      const base = new SwarmClient().baseUrl;
+      const valueFlags = new Set([
+        "--task",
+        "--prompt",
+        "--prompt-file",
+        "--model",
+        "--permission-mode",
+        "--allowed-tools",
+        "--max-turns",
+        "--owner"
+      ]);
+      const positionals = [];
+      for (let i = 0;i < rest.length; i++) {
+        const a = rest[i];
+        if (valueFlags.has(a))
+          i++;
+        else if (!a.startsWith("--"))
+          positionals.push(a);
+      }
+      const flag = (n) => {
+        const i = rest.indexOf(n);
+        return i >= 0 ? rest[i + 1] : undefined;
+      };
+      const sub = positionals[0];
+      if (sub === "ls") {
+        const runs = await api(`/v1/runs?project=${proj.id}`);
+        if (json)
+          console.log(JSON.stringify(runs));
+        else if (!runs.length)
+          console.log("no live runs here");
+        else
+          for (const r2 of runs)
+            console.log(`${r2.id}  ${r2.task.padEnd(12)} pid ${String(r2.pid).padEnd(7)} ${r2.owner.padEnd(10)} ${r2.result ? `$${r2.result.costUsd.toFixed(2)} \xB7 ${r2.result.turns} turns${r2.result.isError ? " \xB7 error" : ""}` : "starting\u2026"}`);
+        break;
+      }
+      if (sub === "send" || sub === "stop") {
+        const target = positionals[1];
+        if (!target)
+          throw new Error(`usage: swarm run ${sub} <task|id>${sub === "send" ? ' "text"' : ""}`);
+        const r2 = sub === "send" ? await fetch(`${base}/v1/runs/${encodeURIComponent(target)}/send`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ text: positionals.slice(2).join(" ") })
+        }) : await fetch(`${base}/v1/runs/${encodeURIComponent(target)}`, { method: "DELETE" });
+        const j = await r2.json();
+        if (json)
+          console.log(JSON.stringify(j));
+        else if (j.ok)
+          console.log(sub === "send" ? `sent to ${target}` : `stopped ${target}`);
+        else {
+          console.error(`REFUSED: ${j.error}`);
+          process.exit(1);
+        }
+        break;
+      }
+      const resumeFrom = sub === "resume" ? positionals[1] : undefined;
+      if (sub === "resume" && !resumeFrom)
+        throw new Error("usage: swarm run resume <session-id>");
+      const task = resumeFrom ? "(resumed)" : flag("--task") ?? sub;
+      let prompt = resumeFrom ? "(from handoff)" : flag("--prompt");
+      const pf = flag("--prompt-file");
+      if (!prompt && pf)
+        prompt = await Bun.file(resolve3(pf)).text();
+      if (!task || !prompt)
+        throw new Error('usage: swarm run --task <id> --prompt "\u2026" | --prompt-file f  [--model] [--permission-mode] [--allowed-tools a,b] [--max-turns n]');
+      const r = await fetch(resumeFrom ? `${base}/v1/sessions/${encodeURIComponent(resumeFrom)}/resume` : `${base}/v1/runs`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          projectId: proj.id,
+          task,
+          prompt,
+          owner: flag("--owner") ?? (resumeFrom ? undefined : process.env.USER ?? "me"),
+          model: flag("--model"),
+          permissionMode: flag("--permission-mode"),
+          allowedTools: flag("--allowed-tools")?.split(",").map((t) => t.trim()).filter(Boolean),
+          maxTurns: flag("--max-turns") ? Number(flag("--max-turns")) : undefined
+        })
+      }).then((x) => x.json());
+      if (json)
+        console.log(JSON.stringify(r));
+      else if (r.ok && r.run)
+        console.log(`run ${r.run.id} on ${r.run.task} (pid ${r.run.pid})
+  worktree: ${r.run.worktree}
+  session:  ${r.run.sessionId}
+  log:      ${r.run.log}
+  steer:    swarm run send ${r.run.task} "\u2026"   stop: swarm run stop ${r.run.task}   watch: swarm tail --session ${r.run.sessionId}`);
+      else {
+        console.error(`REFUSED: ${r.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+    case "handoff":
+    case "resume": {
+      await ensureDaemon({ quiet: true });
+      const task = arg();
+      if (!task)
+        throw new Error(`usage: swarm ${cmd} <task> \u2026`);
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      if (cmd === "resume") {
+        const r2 = await fetch(`${new SwarmClient().baseUrl}/v1/handoffs?project=${proj.id}&task=${encodeURIComponent(task)}`);
+        const j = await r2.json();
+        if (json)
+          console.log(JSON.stringify(j.handoff));
+        else
+          console.log(j.text ?? `no handoff on ${task}`);
+        break;
+      }
+      const flag = (n) => {
+        const i = rest.indexOf(n);
+        return i >= 0 ? rest[i + 1] : undefined;
+      };
+      const r = await fetch(`${new SwarmClient().baseUrl}/v1/handoffs`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          projectId: proj.id,
+          task,
+          done: flag("--done"),
+          remaining: flag("--remaining"),
+          files: (flag("--files") ?? "").split(",").map((f) => f.trim()).filter(Boolean),
+          verify: flag("--verify") ?? null,
+          by: flag("--by") ?? process.env.USER ?? null,
+          sessionId: process.env.CLAUDE_SESSION_ID ?? null
+        })
+      }).then((x) => x.json());
+      if (json)
+        console.log(JSON.stringify(r));
+      else if (r.ok)
+        console.log(`handoff recorded on ${task} \u2014 the next session in its worktree sees it on start`);
+      else {
+        console.error(`REFUSED: ${r.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+    case "gate": {
+      await ensureDaemon({ quiet: true });
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      const valueFlags = new Set(["--rubric", "--evidence"]);
+      const positionals = [];
+      for (let i = 0;i < rest.length; i++) {
+        const a = rest[i];
+        if (valueFlags.has(a))
+          i++;
+        else if (!a.startsWith("--"))
+          positionals.push(a);
+      }
+      const flag = (n) => {
+        const i = rest.indexOf(n);
+        return i >= 0 ? rest[i + 1] : undefined;
+      };
+      const sub = positionals[0] ?? "ls";
+      if (sub === "record") {
+        const [, task, gate, verdict] = positionals;
+        if (!task || !gate || !verdict)
+          throw new Error('usage: swarm gate record <task> <gate> pass|fail --rubric "what was checked" [--evidence "\u2026"]');
+        const r = await fetch(`${new SwarmClient().baseUrl}/v1/gates`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            projectId: proj.id,
+            task,
+            gate,
+            verdict,
+            rubric: flag("--rubric"),
+            evidence: flag("--evidence"),
+            sessionId: process.env.CLAUDE_SESSION_ID ?? null
+          })
+        }).then((x) => x.json());
+        if (json)
+          console.log(JSON.stringify(r));
+        else if (r.ok)
+          console.log(`recorded ${gate} ${verdict} on ${task}`);
+        else {
+          console.error(`REFUSED: ${r.error}`);
+          process.exit(1);
+        }
+        break;
+      }
+      if (sub === "ls") {
+        const task = positionals[1];
+        const q = new URLSearchParams({ project: proj.id });
+        if (task)
+          q.set("task", task);
+        const g = await api(`/v1/gates?${q}`);
+        if (json)
+          console.log(JSON.stringify(g));
+        else if (task) {
+          if (!g.status?.length)
+            console.log(`no gates on ${task}${g.required.length ? ` (required: ${g.required.join(", ")})` : ""}`);
+          for (const st of g.status ?? [])
+            console.log(`${(st.verdict ?? "\u2014").padEnd(5)} ${st.gate.padEnd(12)} ${st.runs} run${st.runs === 1 ? "" : "s"}, ${st.fails} fail${st.fails === 1 ? "" : "s"}`);
+          for (const r of g.runs)
+            console.log(`  ${r.createdAt.slice(0, 16)} ${r.gate.padEnd(12)} ${r.verdict.padEnd(5)} ${r.rubric.slice(0, 70)}`);
+        } else {
+          if (g.required.length)
+            console.log(`required: ${g.required.join(", ")}`);
+          if (!g.runs.length)
+            console.log("no gate runs yet");
+          for (const r of g.runs.slice(0, 50))
+            console.log(`${r.createdAt.slice(0, 16)} ${r.task.padEnd(10)} ${r.gate.padEnd(12)} ${r.verdict.padEnd(5)} ${r.rubric.slice(0, 60)}`);
+        }
+        break;
+      }
+      throw new Error("usage: swarm gate record|ls");
+    }
+    case "search": {
+      await ensureDaemon({ quiet: true });
+      const q = new URLSearchParams({ limit: "30" });
+      const words = [];
+      for (let i = 0;i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--kind")
+          q.set("kind", rest[++i] ?? "");
+        else if (a === "-p") {
+          const proj = await api("/v1/projects", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ path: resolve3(".") })
+          });
+          q.set("project", proj.id);
+        } else if (!a.startsWith("--"))
+          words.push(a);
+      }
+      if (!words.length)
+        throw new Error("usage: swarm search <query\u2026> [-p] [--kind k]");
+      q.set("q", words.join(" "));
+      const r = await api(`/v1/memory?${q}`);
+      if (json)
+        console.log(JSON.stringify(r.hits));
+      else if (!r.hits.length)
+        console.log("nothing in memory matches");
+      else
+        for (const h of r.hits)
+          console.log(`${h.kind.padEnd(8)} ${h.ts.slice(0, 16).replace("T", " ")}  ${h.title}${h.task ? `  [${h.task}]` : ""}
+         ${h.snippet.split("\x01").join("").split("\x02").join("").replace(/\s+/g, " ")}${h.sessionId ? `
+         session ${h.sessionId}` : ""}`);
+      break;
+    }
+    case "rules": {
+      if (rest[0] !== "dryrun")
+        throw new Error("usage: swarm rules dryrun [--set rule=mode,\u2026] [--limit n]");
+      await ensureDaemon({ quiet: true });
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      const q = new URLSearchParams({ project: proj.id });
+      const si = rest.indexOf("--set");
+      if (si >= 0)
+        for (const kv of (rest[si + 1] ?? "").split(",")) {
+          const [k, v] = kv.split("=");
+          if (k && v)
+            q.set(k.trim(), v.trim());
+        }
+      const li = rest.indexOf("--limit");
+      if (li >= 0)
+        q.set("limit", rest[li + 1] ?? "");
+      const r = await api(`/v1/rules/dryrun?${q}`);
+      if (json) {
+        console.log(JSON.stringify(r));
+        break;
+      }
+      console.log(`dry-run over ${r.evaluated} of ${r.calls} recorded calls (nothing recorded)`);
+      for (const [rule, n] of Object.entries(r.byRule))
+        console.log(`  ${rule.padEnd(26)} ${String(r.modes[rule]).padEnd(5)} ask ${String(n.ask).padStart(4)}  deny ${String(n.deny).padStart(4)}`);
+      if (r.flaky.length) {
+        console.log(`
+flaky signals:`);
+        for (const f of r.flaky)
+          console.log(`  ${f.display}
+    ${f.suggestion}`);
+      }
+      if (r.hits.length) {
+        console.log(`
+would have fired (newest last):`);
+        for (const h of r.hits.slice(-20))
+          console.log(`  ${h.ts.slice(11, 19)} ${h.action.padEnd(4)} ${h.rule.padEnd(20)} ${h.display}${h.completed ? "  (ran)" : ""}`);
+      }
+      break;
+    }
     case "tasks": {
       await ensureDaemon({ quiet: true });
       const proj = await api("/v1/projects", {
@@ -559,7 +914,9 @@ url: ${resolveBaseUrl()}`);
       if (json)
         console.log(JSON.stringify(rows));
       else if (!t.source)
-        console.log('no task source \u2014 add `[tasks] source = "path/to/plan.md"` to .swarm.toml');
+        console.log('no task source \u2014 add `[tasks] source = "path/to/plan.md"` (or "github" / "linear") to .swarm.toml');
+      else if (t.error && !t.tasks.length)
+        console.log(`${t.source}: ${t.error}`);
       else if (!rows.length)
         console.log(ready ? "nothing ready to claim" : `no tasks in ${t.source}`);
       else