@ra3orblade/swarm 0.9.0 → 0.11.0

package/README.md

@@ -24,7 +24,7 @@ A local-first control plane for AI-agent development on any repository.</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.
+Run more than one [Claude Code](https://claude.com/claude-code) session at a time — or a [Codex CLI](https://github.com/openai/codex), Gemini, Grok, Aider or opencode 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.
 
 It runs entirely on your machine. No account, no telemetry, works offline. Nothing is added to your repositories.
 
@@ -32,13 +32,13 @@ It runs entirely on your machine. No account, no telemetry, works offline. Nothi
 bunx @ra3orblade/swarm setup
 ```
 
-> Status: early, but real — observability, task claims in isolated worktrees, runtime resources, configurable rules, incidents, a cross-forge merge queue, spawned agents (`swarm run` / `swarm dispatch`), executed verification gates, handoffs, session replay, search and spend budgets are built and dogfooded daily — Swarm dispatches its own tasks. Agent-to-agent messaging, declarative workflows and a built-in review gate are next on the [roadmap](ROADMAP.md).
+> Status: early, but real, and shipping fast — eleven releases so far. Observability across six agent CLIs, task claims in isolated worktrees, runtime resources, rules and incidents, a cross-forge merge queue, spawned agents (`swarm run` / `swarm dispatch`), declarative workflows, executed verification gates (including a built-in reviewer), handoffs, agent-to-agent messaging, session replay, outcome tracking, the collision graph, search, budgets, signed org policy and a self-hosted team daemon are all built and dogfooded daily — Swarm dispatches its own tasks. What's next is on the [roadmap](ROADMAP.md).
 
 ---
 
 ## What you get
 
-**Fleet** — every session across every project, live: agent, title, branch, what it's doing right now, model, a trend sparkline, output tokens, context size, cost, age. Filter by agent (Claude Code, Codex, Grok).
+**Fleet** — every session across every project, live: agent, title, branch, what it's doing right now, model, a trend sparkline, output tokens, context size, cost, age. Filter by agent (all six). A session that starts repeating a failing command gets a **Stuck** badge and a desktop notification — a heuristic, and nothing is ever interrupted.
 
 **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. **Replay** steps through its tool calls one at a time with full input and output; an ended session gets **Resume where it died**, which spawns a run from what it left behind; a session inside a worktree shows its **Diff**.
 
@@ -56,6 +56,10 @@ bunx @ra3orblade/swarm setup
 
 **Ask the human** — an agent that hits a decision only you can make calls `swarm_ask`; the question shows on the session page with the options as buttons, Fleet shows an **Asking** badge, a desktop notification fires, and the answer reaches the agent on its own.
 
+**Workflows** — `[[workflows]] name = "ship" steps = ["implement", "gate:tests", "gate:review", "pr"]` in `.swarm.toml`, and the daemon advances it: run steps spawn an agent in the task's worktree, gate steps must pass to continue, `pr` pushes the branch and opens the pull request. A failed step stops with an incident that says which one.
+
+**Messaging** — `swarm_send(to, text)` reaches another session by id, whoever holds a task, or `"lead"` (your interactive session in the project). It arrives as injected context on the recipient's next tool call, over stdin to a spawned run, or via `swarm_inbox` — exactly once.
+
 **PRs** — one merge queue across GitHub and GitLab, read through your already-authenticated `gh` / `glab`. Merge from the dashboard when checks and review are clear. No tokens stored.
 
 **Timeline** — session lanes per project, coloured by agent, 3–72 h.
@@ -66,15 +70,21 @@ bunx @ra3orblade/swarm setup
 
 **Search** — full-text memory over everything Swarm remembers: handoffs, incidents, gate runs and what sessions said. **Dry-run rules** replays a project's history under rule modes you pick before switching anything on.
 
+**Outcomes** — did the work survive? Sessions join to a branch, the branch to its PR, the PR to merged or reverted, scored per model and per agent: merge rate, median time from session start to merge, dollars per merge.
+
+**Graphs** — a live bipartite graph of running sessions against the files they touch. A file two sessions hold with at least one writer turns red: a merge conflict you can still prevent.
+
+<p align="center"><img src="docs/art/screens/outcomes.png" alt="Outcomes view — merge rate, median time to merge and dollars per merge, per model and per agent" 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.
+**Multi-agent** — six brands, one ledger: Claude Code via its hooks and transcripts (the full picture — rules, MCP, spawned runs), and Codex CLI (`~/.codex`), Gemini CLI (`~/.gemini`), Grok (ACP `updates.jsonl`), Aider (`.aider.chat.history.md`) and opencode (its SQLite database, read-only) by reading the session logs they already write. Every session is tagged with its agent; Spend, Timeline and Outcomes break down per agent.
 
 **Zero instrumentation** — it reads the hooks and transcripts the agents already write. Every table is a real data grid: sort, resize, reorder, filter, persisted layouts. Light and dark themes.
 
 ## Install
 
-Requires [Bun](https://bun.sh) ≥ 1.3, git, and at least one agent: [Claude Code](https://claude.com/claude-code) (`claude` on your PATH — hooks, rules and MCP need it), [Codex CLI](https://github.com/openai/codex) and/or Grok (observed by tailing their logs; no hooks, so no rules). Optional: `gh` and/or `glab` (authenticated) for the PRs view.
+Requires [Bun](https://bun.sh) ≥ 1.3, git, and at least one agent: [Claude Code](https://claude.com/claude-code) (`claude` on your PATH — hooks, rules and MCP need it), plus [Codex CLI](https://github.com/openai/codex), Gemini CLI, Grok, Aider and opencode (observed by reading their logs; no hooks, so no rules). Optional: `gh` and/or `glab` (authenticated) for the PRs view.
 
 ```sh
 bunx @ra3orblade/swarm setup        # daemon + hooks + MCP, opens the dashboard
@@ -176,16 +186,15 @@ swarm install | uninstall      # add/remove Swarm hooks in ~/.claude/settings.js
 ## How it works
 
 ```
- Claude Code sessions ──hooks──▶ swarm-hook ──┐
- (any folder, any repo)                          │
-                        transcripts (JSONL) ──────┼──▶ swarmd ──▶ SQLite (~/.swarm)
- Codex CLI  ─── ~/.codex rollout logs ────────────┤      │
- Grok       ─── ACP updates.jsonl ────────────────┘      └──▶ SSE ──▶ dashboard · CLI · MCP
-                                                  ▼               ▲
-                                       rules engine (ask / deny → incidents)
-                                       ledger: claims · worktrees · gates · handoffs · resources · budgets
-                                                  │
-                                       swarm run / dispatch ──▶ claude -p in a claimed worktree ──┘
+Claude Code · Codex · Gemini · Grok · Aider · opencode
+              │   hooks · transcripts · session logs
+              ▼
+           swarmd ──▶ SQLite (~/.swarm) — the only place state lives
+              │
+              ├──▶ rules engine ──▶ ask · deny · incident
+              ├──▶ ledger ──▶ claims · worktrees · gates · handoffs · ports · budgets
+              ├──▶ SSE ──▶ dashboard · CLI · MCP · desktop app
+              └──▶ swarm run / dispatch ──▶ an agent in a claimed worktree
 ```
 
 - **Identity** is the git common dir, so every worktree of a repo maps to one project.
@@ -195,9 +204,15 @@ swarm install | uninstall      # add/remove Swarm hooks in ~/.claude/settings.js
 
 Design docs (architecture, data model, protocol, interface, roadmap) are rendered at [getswarm.vercel.app/docs/design](https://getswarm.vercel.app/docs/design/) and live in [`docs/`](docs/00-index.md).
 
+## Teams
+
+One machine is free and always will be. When it outgrows one laptop, `swarm-teamd` is a second, self-hosted service your machines *forward* to — audit events, spend rollups and claims, never transcript text unless a machine opts in, and always after your redaction rules. You get one view of the fleet (machines, cluster-wide claims, spend by person, project, machine and day), a claim taken on one laptop is refused on another with the holder's name, org `policy.toml` is ed25519-signed and verified against a key pinned at `swarm login`, team budgets enforce warn / ask / stop, and monthly chargeback exports come out by user, machine, model or **ticket id**. Every laptop stays local-first and keeps working offline. [Teams guide](https://getswarm.vercel.app/docs/11-teams).
+
+*Licensing: `packages/team` is the single source-available package ([FSL-1.1-ALv2](packages/team/LICENSE.md), Apache-2.0 after two years). Everything else is and stays Apache-2.0.*
+
 ## Privacy
 
-Everything is local. Swarm reads the hook payloads and transcript files (Claude Code, Codex, Grok) that already exist on your disk, stores derived state in `~/.swarm/swarm.db`, and serves a dashboard on `127.0.0.1`. Optional outbound paths, all under your control: fetching model prices from the public LiteLLM list (`SWARM_OFFLINE=1` skips it); the PRs view shelling out to your already-authenticated `gh` / `glab` (Swarm stores no forge tokens); and the desktop app asking GitHub Releases for updates when you click *Check for Updates…*. No data about your sessions leaves your machine.
+Everything is local. Swarm reads the hook payloads and session logs (all six agents) that already exist on your disk, stores derived state in `~/.swarm/swarm.db`, and serves a dashboard on `127.0.0.1`. Optional outbound paths, all under your control: fetching model prices from the public LiteLLM list (`SWARM_OFFLINE=1` skips it); the PRs view shelling out to your already-authenticated `gh` / `glab` (Swarm stores no forge tokens); and the desktop app asking GitHub Releases for updates when you click *Check for Updates…*. No data about your sessions leaves your machine.
 
 ## Configuration
 
@@ -221,4 +236,11 @@ bun run dev      # daemon with hot reload
 bun run test     # the suite CI runs
 ```
 
-Apache-2.0.
+Apache-2.0 — everything that runs on one machine: daemon, dashboard, CLI, MCP server, hooks, all
+agent adapters. No telemetry, no account, and that never changes.
+
+The one exception is [`packages/team`](packages/team) — the self-hosted **team daemon** (multi-machine,
+paid tier), which is source-available under
+[FSL-1.1-ALv2](packages/team/LICENSE.md): free for internal use, education, research and
+professional services, converting to Apache-2.0 two years after each release. The boundary is
+simple ([OQ-15](docs/07-open-questions.md)): one machine free, a second person is the product.

package/dist/swarm-hook.js

@@ -47,6 +47,38 @@ function resolveBaseUrl(explicit) {
 // packages/core/src/actor.ts
 var HUMAN_ALIASES = new Set(["cli", "dashboard", "me", "desktop", "human"]);
 var DAEMON_ALIASES = new Set(["daemon", "system", "swarm"]);
+// packages/core/src/art.ts
+var ROBOT = [
+  "       g       g       ",
+  "       X       X       ",
+  "       X       X       ",
+  "     ddddddddddddd     ",
+  "     dXXXXXXXXXXXd     ",
+  "     dggXXXXXXXXXd     ",
+  "   dddXXddXXXddXXddd   ",
+  "   dddXXddXXXddXXddd   ",
+  "   dddXXXXXXXXXXXddd   ",
+  "   dddXXdddddddXXddd   ",
+  "     dXXXXXXXXXXXd     ",
+  "     dXXXXXXXXXXXd     ",
+  "     ddddddddddddd     ",
+  "          XXX          ",
+  "         ddddd         ",
+  "      ddddddddddd      ",
+  "   dXXdggXXXXXXXdXXd   ",
+  "   dXXdXggggXddddXXd   ",
+  "   dXXdXggggXXXXdXXd   ",
+  "   dXXdXXXXXXddddXXd   ",
+  "   dXXdXXXXXXXXXdXXd   ",
+  "   dXXdXdddXXXXXdXXd   ",
+  "   ddddXXXXXXXXXdddd   ",
+  "      ddddddddddd      ",
+  "        XX   XX        ",
+  "        XX   XX        ",
+  "       XXXX XXXX       ",
+  "       dddd dddd       "
+];
+var ROBOT_HEAD = ROBOT.slice(0, 13);
 // packages/core/src/audit.ts
 var AUDIT_TYPES = new Set([
   "session.started",
@@ -230,8 +262,17 @@ function guardWrite(target, current, claims, modes = DEFAULT_MODES, kind = "file
   }
   return { action: "allow" };
 }
+// packages/core/src/hygiene.ts
+var HYGIENE_DEFAULTS = {
+  staleDays: 7,
+  abandonedDays: 30,
+  hungryRssKb: 1024 * 1024,
+  heavyKb: 2 * 1024 * 1024
+};
 // packages/core/src/ledger.ts
 var EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+// packages/core/src/outcomes.ts
+var DEFAULT_BRANCHES = new Set(["main", "master", "develop", "trunk"]);
 // packages/core/src/policy.ts
 import { createHash } from "crypto";
 var POLICY_CACHE_VERSION = 1;

package/dist/swarm.js

@@ -2,6 +2,14 @@
 // @bun
 
 // packages/cli/src/bin.ts
+import {
+  copyFileSync,
+  existsSync as existsSync5,
+  mkdirSync as mkdirSync3,
+  readdirSync,
+  unlinkSync,
+  writeFileSync as writeFileSync3
+} from "fs";
 import { join as join5, resolve as resolve3 } from "path";
 
 // packages/client/src/daemon.ts
@@ -142,7 +150,6 @@ class SwarmClient {
       throw new Error(`swarmd: ${r.status}`);
   }
 }
-
 // packages/core/src/actor.ts
 var HUMAN_ALIASES = new Set(["cli", "dashboard", "me", "desktop", "human"]);
 var DAEMON_ALIASES = new Set(["daemon", "system", "swarm"]);
@@ -159,6 +166,38 @@ var HOOK_EVENTS = [
   "Notification",
   "PreCompact"
 ];
+// packages/core/src/art.ts
+var ROBOT = [
+  "       g       g       ",
+  "       X       X       ",
+  "       X       X       ",
+  "     ddddddddddddd     ",
+  "     dXXXXXXXXXXXd     ",
+  "     dggXXXXXXXXXd     ",
+  "   dddXXddXXXddXXddd   ",
+  "   dddXXddXXXddXXddd   ",
+  "   dddXXXXXXXXXXXddd   ",
+  "   dddXXdddddddXXddd   ",
+  "     dXXXXXXXXXXXd     ",
+  "     dXXXXXXXXXXXd     ",
+  "     ddddddddddddd     ",
+  "          XXX          ",
+  "         ddddd         ",
+  "      ddddddddddd      ",
+  "   dXXdggXXXXXXXdXXd   ",
+  "   dXXdXggggXddddXXd   ",
+  "   dXXdXggggXXXXdXXd   ",
+  "   dXXdXXXXXXddddXXd   ",
+  "   dXXdXXXXXXXXXdXXd   ",
+  "   dXXdXdddXXXXXdXXd   ",
+  "   ddddXXXXXXXXXdddd   ",
+  "      ddddddddddd      ",
+  "        XX   XX        ",
+  "        XX   XX        ",
+  "       XXXX XXXX       ",
+  "       dddd dddd       "
+];
+var ROBOT_HEAD = ROBOT.slice(0, 13);
 // packages/core/src/audit.ts
 var AUDIT_TYPES = new Set([
   "session.started",
@@ -287,6 +326,9 @@ var DEFAULT_CONFIG = {
   gates: { required: [], auto: "session-end", defs: {} },
   workflows: {},
   budget: { daily: null, weekly: null, warn_at: 0.8, on_exceed: "warn" },
+  models: { allow: [] },
+  notify: { webhook: null },
+  team: { url: null, forward: ["ledger", "cost"], interval: 5 },
   events: { retain_days: 30 },
   audit: { retain_days: 0 },
   privacy: DEFAULT_PRIVACY,
@@ -382,6 +424,26 @@ function validate(c) {
       on_exceed: b.on_exceed === "ask" || b.on_exceed === "stop" ? b.on_exceed : "warn"
     },
     workflows: parseWorkflows(c.workflows),
+    notify: {
+      webhook: (() => {
+        const w = c.notify?.webhook;
+        return typeof w === "string" && /^https?:\/\//.test(w.trim()) ? w.trim() : null;
+      })()
+    },
+    models: {
+      allow: Array.isArray(c.models?.allow) ? c.models.allow.filter((m) => typeof m === "string" && m.trim() !== "") : []
+    },
+    team: (() => {
+      const t = c.team ?? {};
+      const url = typeof t.url === "string" && /^https?:\/\//.test(t.url.trim()) ? t.url.trim().replace(/\/+$/, "") : null;
+      const iv = Number(t.interval);
+      const KINDS = ["ledger", "cost", "transcripts"];
+      return {
+        url,
+        forward: Array.isArray(t.forward) ? t.forward.filter((k) => typeof k === "string" && KINDS.includes(k)) : ["ledger", "cost"],
+        interval: Number.isFinite(iv) && iv >= 1 && iv <= 300 ? Math.round(iv) : 5
+      };
+    })(),
     events: {
       retain_days: days(c.events?.retain_days, 30)
     },
@@ -499,8 +561,17 @@ function loadConfigDetailed(opts = {}) {
 // packages/core/src/rules.ts
 var LIVE_WINDOW_MS = 10 * 60000;
 var WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+// packages/core/src/hygiene.ts
+var HYGIENE_DEFAULTS = {
+  staleDays: 7,
+  abandonedDays: 30,
+  hungryRssKb: 1024 * 1024,
+  heavyKb: 2 * 1024 * 1024
+};
 // packages/core/src/ledger.ts
 var EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+// packages/core/src/outcomes.ts
+var DEFAULT_BRANCHES = new Set(["main", "master", "develop", "trunk"]);
 // packages/core/src/policy.ts
 var HOOK_MARK = "swarm-hook";
 var hookIsOurs = (h) => typeof h.command === "string" && (h.command.includes(HOOK_MARK) || h.command.includes("/packages/hook/src/bin.ts"));
@@ -757,6 +828,26 @@ function status() {
     otherAgents
   };
 }
+function setTeamUrl(home, url) {
+  const path = join3(home, "config.toml");
+  const text = existsSync4(path) ? readFileSync3(path, "utf8") : "";
+  let out;
+  const section = text.match(/(^|\n)\[team\]([\s\S]*?)(?=\n\[|$)/);
+  if (section) {
+    const body = section[2] ?? "";
+    const newBody = /^\s*url\s*=/m.test(body) ? body.replace(/^\s*url\s*=.*$/m, `url = "${url}"`) : `
+url = "${url}"${body}`;
+    out = text.replace(section[0], `${section[1]}[team]${newBody}`);
+  } else {
+    out = `${text}${text && !text.endsWith(`
+`) ? `
+` : ""}
+[team]
+url = "${url}"
+`;
+  }
+  writeFileSync2(path, out);
+}
 
 // packages/cli/src/procs.ts
 import { mkdirSync as mkdirSync2, openSync } from "fs";
@@ -873,7 +964,7 @@ var help = `swarm \u2014 control plane for AI-agent development
   setup              start the daemon, install hooks, open the dashboard (do this first)
   start | stop | restart   manage the background daemon
   status [-p]        live sessions (whole machine, or one project)
-  doctor             check everything and print the fix for each gap
+  doctor [--migrate] check everything and print the fix for each gap (--migrate: apply pending db migrations)
 
   add <path> [--name n]   register (pin) a project
   ls                 list projects
@@ -911,8 +1002,10 @@ var help = `swarm \u2014 control plane for AI-agent development
   msg ls [-p] [--json]          recent messages
   demo                    open a seeded demo dashboard (own home + port; your real data is untouched)
   audit export [--since 30d|ISO] [-p] [--type claim.acquired] [--format jsonl|csv|json] [--limit n]   the audit log (ledger changes + decisions, with actor) to stdout
+  login [url] [--token t]   log in to the team daemon ([team].url) and register this machine (M8.3c)
+  backup [dest] | restore <src>   snapshot ~/.swarm (VACUUM INTO, zero downtime) / restore it (daemon stopped)
 
-  install | uninstall     add/remove Swarm hooks in ~/.claude/settings.json
+  install [--config-url <team url>] | uninstall     add/remove Swarm hooks in ~/.claude/settings.json (--config-url also points this machine at a team daemon)
 
 Env: SWARM_URL, SWARM_PORT (default 7777), SWARM_HOME (~/.swarm)`;
 async function api(path, init) {
@@ -974,6 +1067,15 @@ Open the dashboard: ${base}`);
     case "install": {
       const evs = install();
       console.log(`installed hooks for ${evs.length} events in ${status().path}`);
+      const cuIdx = rest.indexOf("--config-url");
+      const configUrl = cuIdx >= 0 ? rest[cuIdx + 1] : null;
+      if (configUrl) {
+        if (!/^https?:\/\//.test(configUrl))
+          throw new Error("--config-url must be an http(s) URL to the team daemon");
+        setTeamUrl(swarmHome(), configUrl.replace(/\/+$/, ""));
+        console.log(`[team] url = "${configUrl}" written to ${join5(swarmHome(), "config.toml")}`);
+        console.log("next: swarm login \u2014 to register this machine and pin the org policy key");
+      }
       console.log("restart any running claude session for it to report in.");
       break;
     }
@@ -981,6 +1083,8 @@ Open the dashboard: ${base}`);
       console.log(`removed ${uninstall()} hook entries`);
       break;
     case "doctor": {
+      if (rest.includes("--migrate"))
+        await ensureDaemon({ quiet: true });
       const st = status();
       const bun = Bun.which("bun");
       const claude = Bun.which("claude");
@@ -1020,6 +1124,13 @@ Open the dashboard: ${base}`);
       };
       forge2("gh", ["auth", "status", "--active", "-h", "github.com"]);
       forge2("glab", ["auth", "status"]);
+      if (running) {
+        const t = await api("/v1/team").catch(() => null);
+        if (t?.configured) {
+          const lag = t.pending ? `${t.pending} pending${t.oldest ? ` since ${t.oldest}` : ""}` : "in sync";
+          line(!t.lastError, `team forwarding \u2192 ${t.url} (${lag})`, `last error: ${t.lastError} \u2014 check the team daemon and [team].url`);
+        }
+      }
       if (process.env.GITLAB_TOKEN)
         console.log("\xB7 glab uses GITLAB_TOKEN from this shell \u2014 a daemon started by the desktop app won't see it; run `glab auth login` to store it instead");
       if (!running)
@@ -1808,6 +1919,102 @@ ${flag("--body") ?? d.body}`);
       }
       throw new Error("usage: swarm msg send <to> <text\u2026> | swarm msg ls");
     }
+    case "backup": {
+      await ensureDaemon({ quiet: true });
+      const dest = resolve3(arg() ?? join5(swarmHome(), "backups", new Date().toISOString().slice(0, 10)));
+      const r = await api("/v1/backup", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ dest })
+      });
+      console.log(`backed up ${r.files.join(", ")} \u2192 ${r.dest}`);
+      console.log(`restore on any machine with: swarm restore ${r.dest} (daemon stopped)`);
+      break;
+    }
+    case "restore": {
+      const src = arg();
+      if (!src)
+        throw new Error("usage: swarm restore <backup dir>  (with the daemon stopped)");
+      if (await daemonRunning())
+        throw new Error("the daemon is running \u2014 stop it first: swarm stop");
+      const home = swarmHome();
+      mkdirSync3(home, { recursive: true });
+      let n = 0;
+      for (const f of readdirSync(resolve3(src))) {
+        if (f === "daemon.json")
+          continue;
+        copyFileSync(join5(resolve3(src), f), join5(home, f));
+        n++;
+      }
+      for (const suffix of ["-wal", "-shm"]) {
+        const p = join5(home, `swarm.db${suffix}`);
+        if (existsSync5(p))
+          unlinkSync(p);
+      }
+      console.log(`restored ${n} files into ${home} \u2014 run: swarm start`);
+      break;
+    }
+    case "login": {
+      await ensureDaemon({ quiet: true });
+      const t = await api("/v1/team");
+      const teamUrl = (arg() ?? t.url)?.replace(/\/+$/, "");
+      if (!teamUrl)
+        throw new Error("no team daemon configured \u2014 set [team] url or run: swarm login <url>");
+      const cfg = await (await authedFetch(`${teamUrl}/t1/auth/config`)).json();
+      const tokIdx = rest.indexOf("--token");
+      let human = null;
+      if (cfg.mode === "oidc") {
+        const flow = await (await authedFetch(`${teamUrl}/t1/auth/device`, { method: "POST" })).json();
+        if (!flow.handle)
+          throw new Error(`login failed: ${flow.error ?? "no device flow"}`);
+        console.log(`visit ${flow.verificationUriComplete ?? flow.verificationUri} and enter code: ${flow.userCode}`);
+        for (;; ) {
+          await new Promise((r) => setTimeout(r, (flow.interval ?? 5) * 1000));
+          const poll = await (await authedFetch(`${teamUrl}/t1/auth/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ handle: flow.handle })
+          })).json();
+          if (poll.status === "pending")
+            continue;
+          if (poll.status !== "ok" || !poll.token)
+            throw new Error(`login failed: ${poll.error ?? "denied"}`);
+          human = poll.token;
+          writeFileSync3(join5(swarmHome(), "team-token"), JSON.stringify({
+            url: teamUrl,
+            token: poll.token,
+            subject: poll.subject,
+            role: poll.role
+          }), { mode: 384 });
+          console.log(`logged in as ${poll.subject} (${poll.role})`);
+          break;
+        }
+      } else if (cfg.mode === "token") {
+        human = tokIdx >= 0 ? rest[tokIdx + 1] ?? null : null;
+        if (!human)
+          throw new Error("this team daemon uses a shared token \u2014 run: swarm login --token <secret>");
+      } else {
+        console.log("team daemon runs open (no auth configured) \u2014 registering machine directly");
+      }
+      const reg = await (await authedFetch(`${teamUrl}/t1/machines/register`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...human ? { authorization: `Bearer ${human}` } : {}
+        },
+        body: JSON.stringify({ id: t.machine.id, name: t.machine.name })
+      })).json();
+      const machineToken = reg.token ?? (cfg.mode === "token" ? human : null);
+      if (!machineToken)
+        throw new Error(`machine registration failed: ${reg.error ?? "unknown"}`);
+      await api("/v1/team/credentials", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ token: machineToken, policyPublicKey: cfg.policyPublicKey })
+      });
+      console.log(`machine ${t.machine.name} (${t.machine.id.slice(0, 8)}) registered \u2014 forwarding is authed`);
+      break;
+    }
     case "audit": {
       if (rest[0] !== "export")
         throw new Error("usage: swarm audit export [--since 30d] [-p] [--type t] [--format jsonl|csv|json] [--limit n]");