@ra3orblade/swarm 0.7.0 → 0.9.0

package/dist/swarm.js

@@ -2,7 +2,7 @@
 // @bun
 
 // packages/cli/src/bin.ts
-import { resolve as resolve3 } from "path";
+import { join as join5, resolve as resolve3 } from "path";
 
 // packages/client/src/daemon.ts
 import { existsSync as existsSync2, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
@@ -50,6 +50,22 @@ function readDaemonInfo() {
     return null;
   }
 }
+var tokenFile = (home = swarmHome()) => join(home, "token");
+function readToken(home = swarmHome()) {
+  try {
+    const t = readFileSync(tokenFile(home), "utf8").trim();
+    return /^[a-f0-9]{64}$/.test(t) ? t : null;
+  } catch {
+    return null;
+  }
+}
+var authedFetch = (input, init) => {
+  const h = new Headers(init?.headers);
+  const t = readToken();
+  if (t && !h.has("authorization"))
+    h.set("authorization", `Bearer ${t}`);
+  return fetch(input, { ...init, headers: h });
+};
 function alive(pid) {
   try {
     process.kill(pid, 0);
@@ -108,7 +124,7 @@ class SwarmClient {
   f;
   constructor(opts = {}) {
     this.baseUrl = resolveBaseUrl(opts.baseUrl);
-    this.f = opts.fetch ?? fetch;
+    this.f = opts.fetch ?? authedFetch;
   }
   async health() {
     const r = await this.f(`${this.baseUrl}/v1/health`);
@@ -127,10 +143,9 @@ class SwarmClient {
   }
 }
 
-// packages/cli/src/install.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+// 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/adapters/claude-code/hooks.ts
 var HOOK_EVENTS = [
   "SessionStart",
@@ -144,24 +159,382 @@ var HOOK_EVENTS = [
   "Notification",
   "PreCompact"
 ];
+// packages/core/src/audit.ts
+var AUDIT_TYPES = new Set([
+  "session.started",
+  "session.ended",
+  "tool.denied",
+  "claim.acquired",
+  "claim.renewed",
+  "claim.released",
+  "claim.expired",
+  "claim.orphaned",
+  "worktree.created",
+  "worktree.removed",
+  "worktree.bootstrapped",
+  "pr.opened",
+  "question.asked",
+  "question.answered",
+  "dispatch.queued",
+  "dispatch.started",
+  "dispatch.finished",
+  "resource.acquired",
+  "resource.released",
+  "resource.reaped",
+  "process.started",
+  "process.exited",
+  "gate.recorded",
+  "handoff.recorded",
+  "permission.requested",
+  "permission.resolved",
+  "incident.opened",
+  "incident.acked",
+  "run.result",
+  "workflow.started",
+  "workflow.finished"
+]);
+var AUDIT_TYPES_SQL = [...AUDIT_TYPES].map((t) => `'${t}'`).join(", ");
+var DEFAULT_PRIVACY = {
+  store_prompts: true,
+  store_reasoning: true,
+  redact: []
+};
 // packages/core/src/budget.ts
 var BUDGET_ASK_TOOLS = new Set(["Bash", "Edit", "Write", "MultiEdit", "NotebookEdit"]);
+// packages/core/src/config.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+
+// packages/core/src/workflows.ts
+var NAME_RE = /^[a-z0-9][a-z0-9_.-]{0,39}$/i;
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parseWorkflows(raw) {
+  const out = {};
+  if (!Array.isArray(raw))
+    return out;
+  for (const w of raw) {
+    if (!isRecord(w) || typeof w.name !== "string" || !NAME_RE.test(w.name))
+      continue;
+    if (!Array.isArray(w.steps) || !w.steps.length)
+      continue;
+    const prompts = isRecord(w.prompts) ? w.prompts : {};
+    const steps = [];
+    for (const s of w.steps) {
+      if (typeof s !== "string" || !s.trim()) {
+        steps.length = 0;
+        break;
+      }
+      const t = s.trim();
+      if (t === "pr")
+        steps.push({ kind: "pr" });
+      else if (t.startsWith("gate:")) {
+        const gate = t.slice(5);
+        if (!NAME_RE.test(gate)) {
+          steps.length = 0;
+          break;
+        }
+        steps.push({ kind: "gate", gate });
+      } else if (NAME_RE.test(t)) {
+        const p = prompts[t];
+        steps.push({
+          kind: "run",
+          name: t,
+          prompt: typeof p === "string" && p.trim() ? p.trim() : null
+        });
+      } else {
+        steps.length = 0;
+        break;
+      }
+    }
+    if (steps.length)
+      out[w.name] = { name: w.name, steps };
+  }
+  return out;
+}
+
+// packages/core/src/config.ts
+var DEFAULT_GATE_TIMEOUT_S = 900;
+var AUTO_MODES = ["session-end", "stop", "off"];
+function parseGateDefs(gates) {
+  const out = {};
+  if (!isRecord2(gates))
+    return out;
+  for (const [name, v] of Object.entries(gates)) {
+    if (!isRecord2(v))
+      continue;
+    const builtin = v.builtin === "review" ? "review" : null;
+    const cmd = typeof v.cmd === "string" ? v.cmd.trim() : "";
+    if (!cmd && !builtin)
+      continue;
+    if (!/^[a-z0-9][a-z0-9_.-]{0,39}$/i.test(name))
+      continue;
+    const t = Number(v.timeout);
+    out[name] = {
+      cmd: builtin ? "" : cmd,
+      timeout: Number.isFinite(t) && t > 0 ? Math.min(t, 86400) : builtin ? 600 : DEFAULT_GATE_TIMEOUT_S,
+      cwd: isRepoRelative(v.cwd) ? v.cwd.trim() : null,
+      builtin,
+      model: typeof v.model === "string" && v.model.trim() ? v.model.trim() : null
+    };
+  }
+  return out;
+}
+var DEFAULT_CONFIG = {
+  daemon: { port: 7777, auth: "loopback-optional" },
+  tasks: { source: null, labels: [], team: null },
+  gates: { required: [], auto: "session-end", defs: {} },
+  workflows: {},
+  budget: { daily: null, weekly: null, warn_at: 0.8, on_exceed: "warn" },
+  events: { retain_days: 30 },
+  audit: { retain_days: 0 },
+  privacy: DEFAULT_PRIVACY,
+  dispatch: {
+    max_parallel: 2,
+    permission_mode: null,
+    model: null,
+    max_turns: null,
+    require_pr: true,
+    profile: null
+  },
+  worktree: { setup: null, copy: [], open: null },
+  rules: {
+    shared_tree: "ask",
+    destructive_git: "ask",
+    pattern_kill: "ask",
+    protected_ports: "ask",
+    no_foreign_worktree: "ask",
+    claim_required_to_write: "off",
+    protected: { ports: [] }
+  }
+};
+var MODES = ["ask", "deny", "off"];
+function isRecord2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function merge(a, b) {
+  if (!isRecord2(a) || !isRecord2(b))
+    return b === undefined ? a : b;
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b))
+    out[k] = merge(a[k], v);
+  return out;
+}
+function parseToml(text, source) {
+  try {
+    return Bun.TOML.parse(text) ?? {};
+  } catch (e) {
+    console.error(`swarm: ignoring invalid TOML in ${source}: ${e.message}`);
+    return {};
+  }
+}
+function isRepoRelative(f) {
+  if (typeof f !== "string")
+    return false;
+  const t = f.trim();
+  if (!t || t.startsWith("/") || t.startsWith("\\") || /^[a-zA-Z]:/.test(t))
+    return false;
+  return !t.split(/[/\\]/).some((seg) => seg === "..");
+}
+var days = (v, fallback) => {
+  const n = Number(v);
+  return Number.isInteger(n) && n >= 0 ? Math.min(n, 3650) : fallback;
+};
+function validate(c) {
+  const mode = (v, fallback) => MODES.includes(v) ? v : fallback;
+  const port = Number(c.daemon?.port);
+  const source = c.tasks?.source;
+  const setup = c.worktree?.setup;
+  const opener = c.worktree?.open;
+  const rawGates = c.gates;
+  const d = c.dispatch ?? {};
+  const mp = Number(d.max_parallel);
+  const mt = Number(d.max_turns);
+  const str = (v) => typeof v === "string" && v.trim() ? v.trim() : null;
+  const b = c.budget ?? {};
+  const usd = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  };
+  const warnAt = Number(b.warn_at);
+  const auto = rawGates?.auto;
+  return {
+    ...c,
+    daemon: {
+      port: Number.isInteger(port) && port > 0 && port < 65536 ? port : 7777,
+      auth: c.daemon?.auth === "required" ? "required" : "loopback-optional"
+    },
+    tasks: {
+      source: typeof source === "string" && source.trim() && !source.startsWith("/") ? source.trim() : null,
+      labels: Array.isArray(c.tasks?.labels) ? c.tasks.labels.filter((l) => typeof l === "string" && l.trim() !== "") : [],
+      team: typeof c.tasks?.team === "string" && c.tasks.team.trim() ? c.tasks.team.trim() : null
+    },
+    gates: {
+      required: Array.isArray(rawGates?.required) ? rawGates.required.filter((g) => typeof g === "string" && g.trim() !== "") : [],
+      auto: AUTO_MODES.includes(auto) ? auto : "session-end",
+      defs: parseGateDefs(rawGates)
+    },
+    budget: {
+      daily: usd(b.daily),
+      weekly: usd(b.weekly),
+      warn_at: Number.isFinite(warnAt) && warnAt > 0 && warnAt < 1 ? warnAt : 0.8,
+      on_exceed: b.on_exceed === "ask" || b.on_exceed === "stop" ? b.on_exceed : "warn"
+    },
+    workflows: parseWorkflows(c.workflows),
+    events: {
+      retain_days: days(c.events?.retain_days, 30)
+    },
+    audit: {
+      retain_days: days(c.audit?.retain_days, 0)
+    },
+    privacy: {
+      store_prompts: c.privacy?.store_prompts !== false,
+      store_reasoning: c.privacy?.store_reasoning !== false,
+      redact: Array.isArray(c.privacy?.redact) ? c.privacy.redact.filter((r) => typeof r === "string" && r.length > 0) : []
+    },
+    dispatch: {
+      max_parallel: Number.isInteger(mp) && mp > 0 ? Math.min(mp, 16) : 2,
+      permission_mode: str(d.permission_mode),
+      model: str(d.model),
+      max_turns: Number.isInteger(mt) && mt > 0 ? mt : null,
+      require_pr: d.require_pr === undefined ? true : d.require_pr === true,
+      profile: ["full", "no-edits", "read-only"].includes(String(d.profile)) ? String(d.profile) : null
+    },
+    worktree: {
+      setup: typeof setup === "string" && setup.trim() ? setup.trim() : null,
+      copy: Array.isArray(c.worktree?.copy) ? c.worktree.copy.filter((f) => isRepoRelative(f)) : [],
+      open: typeof opener === "string" && opener.trim() ? opener.trim() : null
+    },
+    rules: {
+      ...c.rules,
+      shared_tree: mode(c.rules?.shared_tree, "ask"),
+      destructive_git: mode(c.rules?.destructive_git, "ask"),
+      pattern_kill: mode(c.rules?.pattern_kill, "ask"),
+      protected_ports: mode(c.rules?.protected_ports, "ask"),
+      no_foreign_worktree: mode(c.rules?.no_foreign_worktree, "ask"),
+      claim_required_to_write: mode(c.rules?.claim_required_to_write, "off"),
+      protected: {
+        ports: Array.isArray(c.rules?.protected?.ports) ? c.rules.protected.ports.filter((p) => Number.isInteger(p) && p > 0 && p < 65536) : []
+      }
+    }
+  };
+}
+function leafPaths(v, prefix = "") {
+  if (!isRecord2(v))
+    return prefix ? [prefix] : [];
+  const keys = Object.keys(v);
+  if (keys.length === 0)
+    return prefix ? [prefix] : [];
+  return keys.flatMap((k) => leafPaths(v[k], prefix ? `${prefix}.${k}` : k));
+}
+function getPath(v, path) {
+  let cur = v;
+  for (const seg of path.split(".")) {
+    if (!isRecord2(cur))
+      return;
+    cur = cur[seg];
+  }
+  return cur;
+}
+function setPath(obj, path, value) {
+  const segs = path.split(".");
+  let cur = obj;
+  for (const seg of segs.slice(0, -1)) {
+    if (!isRecord2(cur[seg]))
+      cur[seg] = {};
+    cur = cur[seg];
+  }
+  cur[segs[segs.length - 1]] = value;
+}
+var isLockedBy = (path, lock) => path === lock || path.startsWith(`${lock}.`);
+function readLayer(path) {
+  return existsSync3(path) ? parseToml(readFileSync2(path, "utf8"), path) : null;
+}
+function loadConfigDetailed(opts = {}) {
+  const home = opts.home ?? process.env.SWARM_HOME ?? join2(process.env.HOME ?? "", ".swarm");
+  const policyPath = opts.policy ?? process.env.SWARM_POLICY ?? join2(home, "policy.toml");
+  const policyRaw = readLayer(policyPath);
+  const locked = Array.isArray(policyRaw?.locked) ? policyRaw.locked.filter((k) => typeof k === "string" && /^[a-z0-9_.-]+$/i.test(k)) : [];
+  const policy = { ...policyRaw ?? {} };
+  delete policy.locked;
+  const layers = [
+    ["policy", policyRaw ? policy : null],
+    ["global", readLayer(join2(home, "config.toml"))],
+    ["repo", opts.repoRoot ? readLayer(join2(opts.repoRoot, ".swarm.toml")) : null]
+  ];
+  const provenance = {};
+  for (const p of leafPaths(DEFAULT_CONFIG))
+    provenance[p] = "default";
+  const overridden = [];
+  let cfg = DEFAULT_CONFIG;
+  for (const [layer, raw] of layers) {
+    if (!raw)
+      continue;
+    for (const p of leafPaths(raw)) {
+      const lock = layer !== "policy" && locked.find((l) => isLockedBy(p, l));
+      if (lock)
+        overridden.push({ key: p, layer, attempted: getPath(raw, p) });
+      else
+        provenance[p] = layer;
+    }
+    cfg = merge(cfg, raw);
+  }
+  if (overridden.length) {
+    const out = structuredClone(cfg);
+    for (const { key } of overridden) {
+      const fromPolicy = getPath(policy, key);
+      setPath(out, key, fromPolicy === undefined ? getPath(DEFAULT_CONFIG, key) : fromPolicy);
+      provenance[key] = fromPolicy === undefined ? "default" : "policy";
+    }
+    cfg = out;
+  }
+  return {
+    config: validate(cfg),
+    provenance,
+    overridden,
+    policy: { path: policyRaw ? policyPath : null, locked }
+  };
+}
 // 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/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"));
+var MIN_HOOK_TIMEOUT_S = 5;
+function hookCoverage(settings) {
+  const hooks = settings && typeof settings === "object" && !Array.isArray(settings) ? settings.hooks : undefined;
+  const missing = [];
+  const short = [];
+  for (const ev of HOOK_EVENTS) {
+    const groups = Array.isArray(hooks?.[ev]) ? hooks?.[ev] : [];
+    const ours = groups.flatMap((g) => {
+      const list = g?.hooks;
+      return Array.isArray(list) ? list.filter((h) => hookIsOurs(h)) : [];
+    });
+    if (!ours.length)
+      missing.push(ev);
+    else if (ours.every((h) => typeof h.timeout === "number" && h.timeout < MIN_HOOK_TIMEOUT_S))
+      short.push(ev);
+  }
+  return { missing, short, complete: !missing.length && !short.length };
+}
 // 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");
+import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join3 } from "path";
+var isOurs = hookIsOurs;
+var settingsPath = () => process.env.CLAUDE_SETTINGS ?? join3(homedir2(), ".claude", "settings.json");
+var claudeJsonPath = () => process.env.CLAUDE_JSON ?? join3(homedir2(), ".claude.json");
 function loadClaudeJson() {
   const p = claudeJsonPath();
-  if (!existsSync3(p))
+  if (!existsSync4(p))
     return {};
   try {
-    return JSON.parse(readFileSync2(p, "utf8"));
+    return JSON.parse(readFileSync3(p, "utf8"));
   } catch {
     return {};
   }
@@ -194,8 +567,8 @@ function mcpRegistered() {
   const c = loadClaudeJson();
   return Boolean(c.mcpServers?.swarm);
 }
-var codexConfigPath = () => process.env.CODEX_CONFIG ?? join2(homedir2(), ".codex", "config.toml");
-var geminiSettingsPath = () => process.env.GEMINI_SETTINGS ?? join2(homedir2(), ".gemini", "settings.json");
+var codexConfigPath = () => process.env.CODEX_CONFIG ?? join3(homedir2(), ".codex", "config.toml");
+var geminiSettingsPath = () => process.env.GEMINI_SETTINGS ?? join3(homedir2(), ".gemini", "settings.json");
 function codexBlock() {
   const { command, args } = mcpServerConfig();
   return `[mcp_servers.swarm]
@@ -206,9 +579,9 @@ args = ${JSON.stringify(args)}
 var CODEX_BLOCK_RE = /\[mcp_servers\.swarm\]\n(?:(?!\[)[^\n]*\n?)*/;
 function registerCodex() {
   const p = codexConfigPath();
-  if (!existsSync3(join2(p, "..")))
+  if (!existsSync4(join3(p, "..")))
     return false;
-  const cur = existsSync3(p) ? readFileSync2(p, "utf8") : "";
+  const cur = existsSync4(p) ? readFileSync3(p, "utf8") : "";
   const next = CODEX_BLOCK_RE.test(cur) ? cur.replace(CODEX_BLOCK_RE, codexBlock()) : `${cur.trimEnd()}${cur.trim() ? `
 
 ` : ""}${codexBlock()}`;
@@ -218,9 +591,9 @@ function registerCodex() {
 }
 function unregisterCodex() {
   const p = codexConfigPath();
-  if (!existsSync3(p))
+  if (!existsSync4(p))
     return false;
-  const cur = readFileSync2(p, "utf8");
+  const cur = readFileSync3(p, "utf8");
   if (!CODEX_BLOCK_RE.test(cur))
     return false;
   writeFileSync2(p, cur.replace(CODEX_BLOCK_RE, "").replace(/\n{3,}/g, `
@@ -231,11 +604,11 @@ function unregisterCodex() {
 }
 function registerGemini() {
   const p = geminiSettingsPath();
-  if (!existsSync3(join2(p, "..")))
+  if (!existsSync4(join3(p, "..")))
     return false;
   let c = {};
   try {
-    c = existsSync3(p) ? JSON.parse(readFileSync2(p, "utf8")) : {};
+    c = existsSync4(p) ? JSON.parse(readFileSync3(p, "utf8")) : {};
   } catch {
     return false;
   }
@@ -248,10 +621,10 @@ function registerGemini() {
 }
 function unregisterGemini() {
   const p = geminiSettingsPath();
-  if (!existsSync3(p))
+  if (!existsSync4(p))
     return false;
   try {
-    const c = JSON.parse(readFileSync2(p, "utf8"));
+    const c = JSON.parse(readFileSync3(p, "utf8"));
     const mcp = c.mcpServers ?? {};
     if (!mcp.swarm)
       return false;
@@ -291,7 +664,7 @@ function mcpServerConfig() {
 }
 function load() {
   const p = settingsPath();
-  return existsSync3(p) ? JSON.parse(readFileSync2(p, "utf8")) : {};
+  return existsSync4(p) ? JSON.parse(readFileSync3(p, "utf8")) : {};
 }
 function save(s) {
   writeFileSync2(settingsPath(), `${JSON.stringify(s, null, 2)}
@@ -368,21 +741,28 @@ function status() {
   const installed = Object.values(hooks2).some((l) => l.some((g) => g.hooks.some(isOurs)));
   const otherAgents = [];
   const cp = codexConfigPath();
-  if (existsSync3(cp) && CODEX_BLOCK_RE.test(readFileSync2(cp, "utf8")))
+  if (existsSync4(cp) && CODEX_BLOCK_RE.test(readFileSync3(cp, "utf8")))
     otherAgents.push("codex");
   const gp = geminiSettingsPath();
   try {
-    if (existsSync3(gp) && JSON.parse(readFileSync2(gp, "utf8")).mcpServers?.swarm)
+    if (existsSync4(gp) && JSON.parse(readFileSync3(gp, "utf8")).mcpServers?.swarm)
       otherAgents.push("gemini");
   } catch {}
-  return { installed, mcp: mcpRegistered(), path: settingsPath(), shim: shimPath(), otherAgents };
+  return {
+    installed,
+    coverage: hookCoverage(s),
+    mcp: mcpRegistered(),
+    path: settingsPath(),
+    shim: shimPath(),
+    otherAgents
+  };
 }
 
 // packages/cli/src/procs.ts
 import { mkdirSync as mkdirSync2, openSync } from "fs";
-import { join as join3, resolve as resolve2 } from "path";
+import { join as join4, resolve as resolve2 } from "path";
 async function call(path, init) {
-  const r = await fetch(`${new SwarmClient().baseUrl}${path}`, init);
+  const r = await authedFetch(`${new SwarmClient().baseUrl}${path}`, init);
   return await r.json();
 }
 var post = (path, body) => call(path, {
@@ -410,9 +790,9 @@ async function start(opts) {
       port = a.port;
     }
   }
-  const logDir = join3(swarmHome(), "logs", slug(pid));
+  const logDir = join4(swarmHome(), "logs", slug(pid));
   mkdirSync2(logDir, { recursive: true });
-  const log = join3(logDir, `${slug(opts.name)}.log`);
+  const log = join4(logDir, `${slug(opts.name)}.log`);
   const fd = openSync(log, "a");
   const cmdline = opts.cmd.join(" ");
   const child = Bun.spawn(["sh", "-c", cmdline], {
@@ -477,6 +857,14 @@ function fmt(r) {
 }
 
 // packages/cli/src/bin.ts
+function gitToplevel() {
+  const r = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+    stdout: "pipe",
+    stderr: "ignore"
+  });
+  const out = r.exitCode === 0 ? r.stdout.toString().trim() : "";
+  return out || null;
+}
 var [cmd = "help", ...rest] = process.argv.slice(2);
 var json = rest.includes("--json");
 var arg = () => rest.find((a) => !a.startsWith("--"));
@@ -518,13 +906,18 @@ var help = `swarm \u2014 control plane for AI-agent development
   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
+  workflow <name> <task> | workflow ls | workflow stop <task>   run a [[workflows]] sequence on a task (M7.8)
+  msg send <to> <text\u2026> [-p]    message a session id, a task's holder, or "lead" (M7.6)
+  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
 
   install | uninstall     add/remove Swarm hooks in ~/.claude/settings.json
 
 Env: SWARM_URL, SWARM_PORT (default 7777), SWARM_HOME (~/.swarm)`;
 async function api(path, init) {
   const base = new SwarmClient().baseUrl;
-  const r = await fetch(`${base}${path}`, init);
+  const r = await authedFetch(`${base}${path}`, init);
   if (!r.ok)
     throw new Error(`${path}: ${r.status} ${await r.text()}`);
   return r.status === 204 ? null : r.json();
@@ -597,7 +990,24 @@ Open the dashboard: ${base}`);
       line(Boolean(bun), `bun ${bun ? `(${bun})` : ""}`, "install bun: https://bun.sh");
       line(Boolean(claude), "claude CLI on PATH", "install Claude Code: https://claude.com/claude-code");
       line(running, `daemon ${info ? `(pid ${info.pid}, ${info.url})` : ""}`, "run: swarm start");
+      if (running) {
+        const h = await authedFetch(`${resolveBaseUrl()}/v1/health`).then((r) => r.json()).catch(() => null);
+        if (h)
+          console.log(`\xB7 daemon v${h.version ?? "?"} \xB7 schema v${h.schema ?? 0}`);
+      }
       line(st.installed, "hooks installed", "run: swarm install");
+      if (st.installed && !st.coverage.complete) {
+        if (st.coverage.missing.length)
+          line(false, `hooks missing: ${st.coverage.missing.join(", ")}`, "run: swarm install");
+        if (st.coverage.short.length)
+          line(false, `hook timeout too short: ${st.coverage.short.join(", ")}`, "run: swarm install");
+      }
+      const pol = loadConfigDetailed({ repoRoot: gitToplevel() });
+      if (pol.policy.path) {
+        line(true, `policy ${pol.policy.path} (locked: ${pol.policy.locked.join(", ") || "nothing"})`, "");
+        for (const o of pol.overridden)
+          line(false, `${o.layer} config overrides locked ${o.key}`, `remove it \u2014 policy value stays in effect`);
+      }
       line(st.mcp, "MCP server registered", "run: swarm install");
       if (st.otherAgents.length)
         console.log(`\u2713 MCP server also registered for ${st.otherAgents.join(", ")} (swarm_* tools in those CLIs too)`);
@@ -645,7 +1055,7 @@ url: ${resolveBaseUrl()}`);
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ path: resolve3(".") })
       });
-      const r = await fetch(`${new SwarmClient().baseUrl}/v1/claims`, {
+      const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/claims`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ projectId: proj.id, task, owner })
@@ -673,7 +1083,7 @@ url: ${resolveBaseUrl()}`);
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ path: resolve3(".") })
       });
-      const r = await fetch(`${new SwarmClient().baseUrl}/v1/claims/${cmd}`, {
+      const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/claims/${cmd}`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ projectId: proj.id, task, force: rest.includes("--force") })
@@ -696,7 +1106,7 @@ url: ${resolveBaseUrl()}`);
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ path: resolve3(".") })
       });
-      const post2 = (path, body) => fetch(`${new SwarmClient().baseUrl}${path}`, {
+      const post2 = (path, body) => authedFetch(`${new SwarmClient().baseUrl}${path}`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ projectId: proj.id, ...body })
@@ -852,7 +1262,7 @@ url: ${resolveBaseUrl()}`);
       const text = words.join(" ");
       if (!id || !text)
         throw new Error("usage: swarm answer <id> <text\u2026>");
-      const r = await fetch(`${new SwarmClient().baseUrl}/v1/questions/${id}/answer`, {
+      const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/questions/${id}/answer`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ text, by: process.env.USER ?? "cli" })
@@ -904,7 +1314,7 @@ url: ${resolveBaseUrl()}`);
         break;
       }
       if (sub === "clear") {
-        const r2 = await fetch(`${new SwarmClient().baseUrl}/v1/dispatch`, {
+        const r2 = await authedFetch(`${new SwarmClient().baseUrl}/v1/dispatch`, {
           method: "DELETE",
           headers: { "content-type": "application/json" },
           body: JSON.stringify({ projectId: proj.id, task: positional[1] })
@@ -912,7 +1322,7 @@ url: ${resolveBaseUrl()}`);
         console.log(json ? JSON.stringify(r2) : `cleared ${r2.cleared}`);
         break;
       }
-      const r = await fetch(`${new SwarmClient().baseUrl}/v1/dispatch`, {
+      const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/dispatch`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({
@@ -978,7 +1388,7 @@ watch: swarm dispatch status \xB7 swarm run ls \xB7 the Board`);
 ${flag("--body") ?? d.body}`);
         break;
       }
-      const r = await fetch(`${new SwarmClient().baseUrl}/v1/prs/open`, {
+      const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/prs/open`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({
@@ -1070,11 +1480,11 @@ ${flag("--body") ?? d.body}`);
         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`, {
+        const r2 = sub === "send" ? await authedFetch(`${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" });
+        }) : await authedFetch(`${base}/v1/runs/${encodeURIComponent(target)}`, { method: "DELETE" });
         const j = await r2.json();
         if (json)
           console.log(JSON.stringify(j));
@@ -1096,7 +1506,7 @@ ${flag("--body") ?? d.body}`);
         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] [--profile p] [--allowed-tools a,b] [--max-turns n]');
-      const r = await fetch(resumeFrom ? `${base}/v1/sessions/${encodeURIComponent(resumeFrom)}/resume` : `${base}/v1/runs`, {
+      const r = await authedFetch(resumeFrom ? `${base}/v1/sessions/${encodeURIComponent(resumeFrom)}/resume` : `${base}/v1/runs`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({
@@ -1137,7 +1547,7 @@ ${flag("--body") ?? d.body}`);
         body: JSON.stringify({ path: resolve3(".") })
       });
       if (cmd === "resume") {
-        const r2 = await fetch(`${new SwarmClient().baseUrl}/v1/handoffs?project=${proj.id}&task=${encodeURIComponent(task)}`);
+        const r2 = await authedFetch(`${new SwarmClient().baseUrl}/v1/handoffs?project=${proj.id}&task=${encodeURIComponent(task)}`);
         const j = await r2.json();
         if (json)
           console.log(JSON.stringify(j.handoff));
@@ -1149,7 +1559,7 @@ ${flag("--body") ?? d.body}`);
         const i = rest.indexOf(n);
         return i >= 0 ? rest[i + 1] : undefined;
       };
-      const r = await fetch(`${new SwarmClient().baseUrl}/v1/handoffs`, {
+      const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/handoffs`, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({
@@ -1198,7 +1608,7 @@ ${flag("--body") ?? d.body}`);
         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`, {
+        const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/gates`, {
           method: "POST",
           headers: { "content-type": "application/json" },
           body: JSON.stringify({
@@ -1225,7 +1635,7 @@ ${flag("--body") ?? d.body}`);
         const [, task, ...gates2] = positionals;
         if (!task)
           throw new Error("usage: swarm gate run <task> [gate\u2026]   (default: the required gates that have a cmd)");
-        const r = await fetch(`${new SwarmClient().baseUrl}/v1/gates/run`, {
+        const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/gates/run`, {
           method: "POST",
           headers: { "content-type": "application/json" },
           body: JSON.stringify({
@@ -1309,6 +1719,125 @@ ${flag("--body") ?? d.body}`);
          session ${h.sessionId}` : ""}`);
       break;
     }
+    case "workflow": {
+      await ensureDaemon({ quiet: true });
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      if (rest[0] === "ls" || !rest[0]) {
+        const w = await api(`/v1/workflows?project=${proj.id}`);
+        const names = Object.keys(w.defs);
+        console.log(names.length ? `declared: ${names.join(", ")}` : "no [[workflows]] declared in .swarm.toml");
+        for (const r2 of w.runs.slice(0, 20))
+          console.log(`#${r2.id} ${r2.task} \xB7 ${r2.workflow} \xB7 ${r2.state === "running" ? `${r2.stepLabel} (${r2.step + 1}/${r2.steps.length})` : r2.state}${r2.detail ? ` \u2014 ${r2.detail.slice(0, 80)}` : ""}`);
+        break;
+      }
+      if (rest[0] === "stop") {
+        const task2 = rest[1];
+        if (!task2)
+          throw new Error("usage: swarm workflow stop <task>");
+        const r2 = await api("/v1/workflows/stop", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ projectId: proj.id, task: task2 })
+        });
+        if (!r2.ok)
+          throw new Error(r2.error ?? "stop failed");
+        console.log(`stopped the workflow on ${task2}`);
+        break;
+      }
+      const [name, task] = rest;
+      if (!name || !task)
+        throw new Error("usage: swarm workflow <name> <task>");
+      const r = await api("/v1/workflows", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          projectId: proj.id,
+          task,
+          workflow: name,
+          owner: process.env.USER ?? "cli"
+        })
+      });
+      if (!r.ok)
+        throw new Error(r.error ?? "workflow failed to start");
+      console.log(`workflow ${name} started on ${task} (#${r.id}) \u2014 watch the Board`);
+      break;
+    }
+    case "msg": {
+      await ensureDaemon({ quiet: true });
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      if (rest[0] === "send") {
+        const [to, ...words] = rest.slice(1).filter((a) => a !== "-p");
+        if (!to || !words.length)
+          throw new Error('usage: swarm msg send <session|task|"lead"> <text\u2026>');
+        const r = await api("/v1/messages", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            projectId: proj.id,
+            to,
+            text: words.join(" "),
+            from: process.env.USER ?? "me"
+          })
+        });
+        if (!r.ok)
+          throw new Error(r.error ?? "send failed");
+        console.log(`sent #${r.message?.id}${r.message?.sessionId ? "" : " (queued until the target appears)"}`);
+        break;
+      }
+      if (rest[0] === "ls" || !rest[0]) {
+        const ms = await api(`/v1/messages?project=${proj.id}&limit=50`);
+        if (rest.includes("--json")) {
+          console.log(JSON.stringify(ms, null, 2));
+          break;
+        }
+        if (!ms.length) {
+          console.log("no messages");
+          break;
+        }
+        for (const m of ms)
+          console.log(`#${m.id} ${m.deliveredAt ? "\u2713" : "\xB7"} ${m.from ?? "?"} \u2192 ${m.task ?? m.toKind}: ${m.text.slice(0, 100)}`);
+        break;
+      }
+      throw new Error("usage: swarm msg send <to> <text\u2026> | swarm msg ls");
+    }
+    case "audit": {
+      if (rest[0] !== "export")
+        throw new Error("usage: swarm audit export [--since 30d] [-p] [--type t] [--format jsonl|csv|json] [--limit n]");
+      await ensureDaemon({ quiet: true });
+      const q = new URLSearchParams;
+      const val = (n) => {
+        const i = rest.indexOf(n);
+        return i >= 0 ? rest[i + 1] : undefined;
+      };
+      if (val("--since"))
+        q.set("since", val("--since"));
+      if (val("--type"))
+        q.set("type", val("--type"));
+      if (val("--limit"))
+        q.set("limit", val("--limit"));
+      q.set("format", val("--format") ?? "jsonl");
+      if (rest.includes("-p")) {
+        const proj = await api("/v1/projects", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ path: resolve3(".") })
+        });
+        q.set("project", proj.id);
+      }
+      const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/audit?${q}`);
+      if (!r.ok)
+        throw new Error((await r.json()).error ?? `audit: ${r.status}`);
+      process.stdout.write(await r.text());
+      break;
+    }
     case "rules": {
       if (rest[0] !== "dryrun")
         throw new Error("usage: swarm rules dryrun [--set rule=mode,\u2026] [--limit n]");
@@ -1539,7 +2068,7 @@ would have fired (newest last):`);
           headers: { "content-type": "application/json" },
           body: JSON.stringify({ path: resolve3(".") })
         });
-        const r = await fetch(`${new SwarmClient().baseUrl}/v1/resources`, {
+        const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/resources`, {
           method: "POST",
           headers: { "content-type": "application/json" },
           body: JSON.stringify({
@@ -1575,7 +2104,7 @@ would have fired (newest last):`);
         });
         if (rest.includes("--force"))
           q.set("force", "1");
-        const r = await fetch(`${new SwarmClient().baseUrl}/v1/resources/${encodeURIComponent(name)}?${q}`, { method: "DELETE" }).then((x) => x.json());
+        const r = await authedFetch(`${new SwarmClient().baseUrl}/v1/resources/${encodeURIComponent(name)}?${q}`, { method: "DELETE" }).then((x) => x.json());
         if (json)
           console.log(JSON.stringify(r));
         else if (r.ok)
@@ -1593,7 +2122,7 @@ would have fired (newest last):`);
       const base = new SwarmClient().baseUrl;
       const pIdx = rest.indexOf("--session");
       const wantSession = pIdx >= 0 ? rest[pIdx + 1] : undefined;
-      const res = await fetch(`${base}/v1/events?since=0`);
+      const res = await authedFetch(`${base}/v1/events?since=0`);
       const reader = res.body?.getReader();
       if (!reader)
         throw new Error("no stream");
@@ -1623,9 +2152,37 @@ would have fired (newest last):`);
       }
       break;
     }
+    case "demo": {
+      const home = join5(swarmHome(), "demo");
+      const port = "7799";
+      const [cmd2, ...args] = daemonCommand();
+      if (!cmd2)
+        throw new Error("could not resolve the daemon command");
+      const env = { ...process.env, SWARM_HOME: home, SWARM_PORT: port, SWARM_DEMO: "1" };
+      const up = await authedFetch(`http://127.0.0.1:${port}/v1/health`).then((r) => r.ok).catch(() => false);
+      if (!up) {
+        Bun.spawn([cmd2, ...args], {
+          stdin: "ignore",
+          stdout: "ignore",
+          stderr: "ignore",
+          env
+        }).unref();
+        for (let i = 0;i < 40; i++) {
+          await new Promise((r) => setTimeout(r, 250));
+          if (await authedFetch(`http://127.0.0.1:${port}/v1/health`).then((r) => r.ok).catch(() => false))
+            break;
+        }
+      }
+      const tok = readToken(home);
+      const url = `http://127.0.0.1:${port}/${tok ? `?token=${tok}` : ""}`;
+      Bun.spawn(["open", url]).unref?.();
+      console.log(`demo dashboard: http://127.0.0.1:${port} (home ${home} \u2014 delete it to reset)`);
+      break;
+    }
     case "ui": {
       const base = await ensureDaemon();
-      Bun.spawn(["open", base]).unref?.();
+      const tok = readToken();
+      Bun.spawn(["open", tok ? `${base}/?token=${tok}` : base]).unref?.();
       console.log(base);
       break;
     }