groove-dev 0.27.197 → 0.27.198

package/node_modules/@groove-dev/gui/src/views/settings.jsx

@@ -52,6 +52,15 @@ const KEY_PLACEHOLDERS = {
   grok: 'xai-...',
 };
 
+// installCommand is a string for most providers, but some (Ollama) return
+// {command, alt, platform} — normalize so an object can never reach JSX as a
+// child (React #31 white-screens the whole tab).
+function installCommandText(installCommand) {
+  if (!installCommand) return null;
+  if (typeof installCommand === 'string') return installCommand;
+  return installCommand.command || null;
+}
+
 function ProviderCard({ provider, onKeyChange }) {
   const [settingKey, setSettingKey] = useState(false);
   const [keyInput, setKeyInput] = useState('');
@@ -182,15 +191,15 @@ function ProviderCard({ provider, onKeyChange }) {
               </Button>
 
               {/* Manual install command */}
-              {provider.installCommand && (
+              {installCommandText(provider.installCommand) && (
                 <div className="space-y-1">
                   <p className="text-2xs text-text-4 font-sans">Or install manually in your terminal:</p>
                   <div className="flex items-center gap-1">
                     <code className="flex-1 px-2 py-1.5 bg-surface-0 border border-border-subtle rounded text-2xs font-mono text-text-2 select-all">
-                      {provider.installCommand}
+                      {installCommandText(provider.installCommand)}
                     </code>
                     <button
-                      onClick={() => { navigator.clipboard.writeText(provider.installCommand); addToast('success', 'Copied'); }}
+                      onClick={() => { navigator.clipboard.writeText(installCommandText(provider.installCommand)); addToast('success', 'Copied'); }}
                       className="p-1.5 text-text-4 hover:text-text-2 cursor-pointer"
                     >
                       <Copy size={10} />
@@ -1491,6 +1500,169 @@ function TrainingDataSection() {
   );
 }
 
+/* ── InnerChat Peers Section ──────────────────────────────── */
+
+// Cross-daemon InnerChat: agents on this daemon can reach agents on a peer
+// daemon as `name@alias`. A peer is another Groove daemon you can already
+// reach (a tunnel-forwarded localhost port, a Tailscale address). Trust is
+// mutual — both machines must list each other, and signatures ride the
+// federation keypair — so this panel also surfaces THIS daemon's id to hand
+// to the other side.
+function InnerChatPeersSection() {
+  const addToast = useGrooveStore((s) => s.addToast);
+  const [peers, setPeers] = useState([]);
+  const [ownId, setOwnId] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [adding, setAdding] = useState(false);
+  const [form, setForm] = useState({ alias: '', url: '', daemonId: '' });
+  const [busy, setBusy] = useState(false);
+
+  const load = () => {
+    api.get('/innerchat/peers')
+      .then((d) => setPeers(Array.isArray(d?.peers) ? d.peers : []))
+      .catch(() => {})
+      .finally(() => setLoading(false));
+    api.get('/federation').then((d) => setOwnId(d?.id || null)).catch(() => {});
+  };
+  useEffect(() => { load(); }, []);
+
+  const canSubmit = form.alias.trim() && form.url.trim() && form.daemonId.trim();
+
+  async function addPeer() {
+    if (!canSubmit) return;
+    setBusy(true);
+    try {
+      const d = await api.post('/innerchat/peers', {
+        alias: form.alias.trim(),
+        url: form.url.trim(),
+        daemonId: form.daemonId.trim().toLowerCase(),
+      });
+      setPeers(Array.isArray(d?.peers) ? d.peers : []);
+      setForm({ alias: '', url: '', daemonId: '' });
+      setAdding(false);
+      addToast('success', `Peer "${form.alias.trim()}" added`);
+    } catch (err) {
+      addToast('error', 'Could not add peer', err.message);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function removePeer(alias) {
+    try {
+      const d = await api.delete(`/innerchat/peers/${encodeURIComponent(alias)}`);
+      setPeers(Array.isArray(d?.peers) ? d.peers : []);
+      addToast('info', `Removed peer "${alias}"`);
+    } catch (err) {
+      addToast('error', 'Remove failed', err.message);
+    }
+  }
+
+  return (
+    <div>
+      <div className="flex items-center gap-2 mb-2.5 px-0.5">
+        <span className="text-2xs font-semibold text-text-3 font-sans uppercase tracking-wider">InnerChat Peers</span>
+        <div className="flex-1 h-px bg-border-subtle" />
+        <span className="text-2xs text-text-4 font-sans">
+          {peers.length} peer{peers.length !== 1 ? 's' : ''} · address as <code className="text-text-3">name@alias</code>
+        </span>
+      </div>
+
+      <div className="rounded-lg border border-border-subtle bg-surface-1 px-4 py-3.5 flex flex-col gap-3">
+        {/* This daemon's identity — to hand to the peer machine */}
+        <div className="flex items-start gap-2.5">
+          <div className="w-6 h-6 rounded bg-indigo/10 flex items-center justify-center flex-shrink-0 mt-0.5">
+            <Share2 size={12} className="text-indigo" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <div className="text-[13px] font-medium text-text-0 font-sans leading-tight">Cross-daemon agent chat</div>
+            <div className="text-2xs text-text-4 font-sans leading-relaxed mt-0.5">
+              Agents reach a peer's agents as <code className="text-text-3">name@alias</code>. Add the peer on both
+              machines — each lists the other's URL and daemon id. This daemon's id:
+            </div>
+            <div className="flex items-center gap-1.5 mt-1.5">
+              <code className="h-7 px-2 flex items-center bg-surface-0 border border-border-subtle rounded-md text-2xs font-mono text-text-2 truncate min-w-0">
+                {ownId || '—'}
+              </code>
+              {ownId && (
+                <Button variant="secondary" size="sm" onClick={() => { navigator.clipboard.writeText(ownId); addToast('success', 'Copied daemon id'); }} className="h-7 px-2 flex-shrink-0">
+                  <Copy size={11} />
+                </Button>
+              )}
+            </div>
+          </div>
+        </div>
+
+        {/* Peer list */}
+        {loading ? (
+          <Skeleton className="h-10 rounded-md" />
+        ) : peers.length > 0 ? (
+          <div className="flex flex-col gap-1.5">
+            {peers.map((p) => (
+              <div key={p.alias} className="flex items-center gap-2.5 px-2.5 py-2 rounded-md bg-surface-0 border border-border-subtle">
+                <MessageCircle size={12} className="text-indigo flex-shrink-0" />
+                <Badge variant="secondary" className="font-mono flex-shrink-0">@{p.alias}</Badge>
+                <code className="text-2xs font-mono text-text-2 truncate min-w-0 flex-1">{p.url}</code>
+                <code className="text-2xs font-mono text-text-4 flex-shrink-0 hidden sm:inline" title={p.daemonId}>{String(p.daemonId).slice(0, 8)}…</code>
+                <button
+                  onClick={() => removePeer(p.alias)}
+                  className="text-text-4 hover:text-danger transition-colors flex-shrink-0 cursor-pointer"
+                  title={`Remove ${p.alias}`}
+                >
+                  <Trash2 size={12} />
+                </button>
+              </div>
+            ))}
+          </div>
+        ) : (
+          <div className="text-2xs text-text-4 font-sans px-1 py-1">No peers configured — add one to let agents talk across machines.</div>
+        )}
+
+        {/* Add form */}
+        {adding ? (
+          <div className="flex flex-col gap-2 pt-1 border-t border-border-subtle">
+            <div className="grid grid-cols-[1fr_2fr] gap-2">
+              <input
+                value={form.alias}
+                onChange={(e) => setForm((f) => ({ ...f, alias: e.target.value }))}
+                placeholder="alias (e.g. spark)"
+                className="h-8 px-2.5 text-xs bg-surface-0 border border-border-subtle rounded-md text-text-0 font-mono placeholder:text-text-4 focus:outline-none focus:ring-1 focus:ring-accent"
+              />
+              <input
+                value={form.url}
+                onChange={(e) => setForm((f) => ({ ...f, url: e.target.value }))}
+                placeholder="http://localhost:62686 (tunnel / Tailscale URL)"
+                className="h-8 px-2.5 text-xs bg-surface-0 border border-border-subtle rounded-md text-text-0 font-mono placeholder:text-text-4 focus:outline-none focus:ring-1 focus:ring-accent"
+              />
+            </div>
+            <input
+              value={form.daemonId}
+              onChange={(e) => setForm((f) => ({ ...f, daemonId: e.target.value }))}
+              placeholder="peer daemon id (from the other machine's Settings)"
+              className="h-8 px-2.5 text-xs bg-surface-0 border border-border-subtle rounded-md text-text-0 font-mono placeholder:text-text-4 focus:outline-none focus:ring-1 focus:ring-accent"
+            />
+            <div className="flex items-center justify-end gap-2">
+              <Button variant="ghost" size="sm" onClick={() => { setAdding(false); setForm({ alias: '', url: '', daemonId: '' }); }} disabled={busy}>Cancel</Button>
+              <Button variant="primary" size="sm" onClick={addPeer} disabled={!canSubmit || busy}>
+                {busy ? <Loader2 size={12} className="animate-spin" /> : <Check size={12} />}
+                Add Peer
+              </Button>
+            </div>
+          </div>
+        ) : (
+          <button
+            onClick={() => setAdding(true)}
+            className="flex items-center justify-center gap-1.5 h-8 rounded-md border border-dashed border-border-subtle text-2xs font-sans text-text-3 hover:text-accent hover:border-accent/40 transition-colors cursor-pointer"
+          >
+            <Plus size={12} />
+            Add Peer
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
 /* ── Early Access Section ─────────────────────────────────── */
 
 function EarlyAccessSection() {
@@ -1791,6 +1963,9 @@ export default function SettingsView() {
             </div>
           )}
 
+          {/* ═══════ INNERCHAT PEERS ═══════ */}
+          <InnerChatPeersSection />
+
           {/* ═══════ EARLY ACCESS ═══════ */}
           <EarlyAccessSection />
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groove-dev",
-  "version": "0.27.197",
+  "version": "0.27.198",
   "description": "Open-source agent orchestration layer — the AI company OS. Local model agent engine (GGUF/Ollama/llama-server), HuggingFace model browser, MCP integrations (Slack, Gmail, Stripe, 15+), agent scheduling (cron), business roles (CMO, CFO, EA). GUI dashboard, multi-agent coordination, zero cold-start, infinite sessions. Works with Claude Code, Codex, Gemini CLI, Ollama, any local model.",
   "license": "FSL-1.1-Apache-2.0",
   "author": "Groove Dev <hello@groovedev.ai> (https://groovedev.ai)",
@@ -58,7 +58,7 @@
     "start:desktop": "npm run start -w packages/desktop",
     "build:desktop": "npm run build -w packages/desktop",
     "dist:desktop": "npm run build && npm run dist -w packages/desktop",
-    "test": "node --test packages/daemon/test/*.test.js",
+    "test": "node --test-force-exit --test packages/daemon/test/*.test.js",
     "prepublishOnly": "npm run build"
   },
   "bundleDependencies": [

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/cli",
-  "version": "0.27.197",
+  "version": "0.27.198",
   "description": "GROOVE CLI — manage AI coding agents from your terminal",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/packages/daemon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/daemon",
-  "version": "0.27.197",
+  "version": "0.27.198",
   "description": "GROOVE daemon — agent orchestration engine",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/packages/daemon/src/api.js

@@ -31,6 +31,7 @@ import { registerInnerChatRoutes } from './routes/innerchat.js';
 import { registerChatHistoryRoutes } from './routes/chat-history.js';
 import { registerWatchRoutes } from './routes/watch.js';
 import { registerAutoAgentRoutes } from './routes/auto-agents.js';
+import { registerAxomRoutes } from './routes/axom.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
@@ -183,6 +184,7 @@ export function createApi(app, daemon) {
   registerChatHistoryRoutes(app, daemon);
   registerWatchRoutes(app, daemon);
   registerAutoAgentRoutes(app, daemon);
+  registerAxomRoutes(app, daemon);
 
 
   // Token usage

package/packages/daemon/src/axom-connector.js

@@ -0,0 +1,340 @@
+// GROOVE — Axom Connector
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Consumes the Axom provider protocol (GROOVE ⇄ Axom Integration Contract v0,
+// Axom-Labs/Axom-Private docs/GROOVE_INTEGRATION.md):
+//
+//   GET  /about                          identity + KINDS schema handshake
+//   GET  /sessions                       [{session, started, live}]
+//   WS   /ws/session/{id}?since=<ev-id>  envelope stream, verbatim
+//   POST /session/{id}/interrupt {text}  -> {id, truncated}
+//   POST /session/{id}/stop      {}      -> {ok}
+//
+// The envelope schema is additive-only: unknown kinds are surfaced and passed
+// through, never dropped. GROOVE consumes the protocol; it never imports Axom
+// code. Host-agnostic by contract §5 — an endpoint is a URL, nothing here may
+// assume where the runtime lives.
+
+import { WebSocket } from 'ws';
+
+export const AXOM_DEFAULT_PORT = 8737;
+
+// The frozen KINDS enumeration from Axom's events.py, mirrored for the /about
+// handshake. Drift (either direction) is surfaced on the endpoint status —
+// new kinds still flow through; this list is for visibility, not filtering.
+export const KNOWN_KINDS = Object.freeze([
+  'pipeline_start', 'firing_start', 'step_start', 'firing_end', 'pipeline_done',
+  'thought', 'text', 'action', 'observation', 'resolution',
+  'delegate', 'yield', 'interrupt', 'interrupt_ack',
+  'trace_other', 'tool_start', 'tool_end', 'recall_end',
+  'swarm_start', 'swarm_weights', 'swarm_agent_done', 'swarm_agent_error',
+  'swarm_memory_fused', 'swarm_fused', 'swarm_facts_extracted', 'swarm_done',
+  'leaf_swap', 'stop_requested', 'stop_effected', 'candidate_banked',
+  'narration', 'narration_dropped',
+  'candidate_arrived', 'evidence_scored', 'champion_changed',
+  'confidence_updated', 'verifier_verdict',
+]);
+
+const RING_SIZE = 4096;
+const SESSION_POLL_MS = 15000;
+const BACKOFF_BASE_MS = 1000;
+const BACKOFF_MAX_MS = 30000;
+const FETCH_TIMEOUT_MS = 5000;
+
+export function validateEndpoint(entry) {
+  if (!entry || typeof entry !== 'object') return 'endpoint must be an object';
+  const { name, url } = entry;
+  if (!name || typeof name !== 'string' || !/^[a-zA-Z0-9_-]{1,40}$/.test(name)) {
+    return 'endpoint name must be 1-40 chars (letters, digits, dash, underscore)';
+  }
+  if (!url || typeof url !== 'string') return 'endpoint url is required';
+  let parsed;
+  try { parsed = new URL(url); } catch { return `invalid url: ${url}`; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return 'endpoint url must be http(s)';
+  }
+  if (parsed.username || parsed.password) return 'credentials in the url are not allowed';
+  return null;
+}
+
+function seqOf(eventId) {
+  if (typeof eventId !== 'string' || !eventId.startsWith('ev-')) return null;
+  const n = parseInt(eventId.slice(3), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+export class AxomConnector {
+  constructor(daemon, opts = {}) {
+    this.daemon = daemon;
+    this.ringSize = opts.ringSize || RING_SIZE;
+    this.backoffBaseMs = opts.backoffBaseMs || BACKOFF_BASE_MS;
+    this.sessionPollMs = opts.sessionPollMs || SESSION_POLL_MS;
+    this.endpoints = new Map(); // name -> endpoint state
+    this.destroyed = false;
+  }
+
+  start() {
+    const configured = this.daemon.config?.axom?.endpoints || [];
+    this.configure(configured);
+  }
+
+  // Reconcile live connections against a validated endpoint list. Persistence
+  // is the caller's job (routes save config); this manages connections only.
+  configure(entries) {
+    const keep = new Set();
+    for (const entry of entries) {
+      if (validateEndpoint(entry)) continue; // routes validate; skip defensively
+      keep.add(entry.name);
+      const existing = this.endpoints.get(entry.name);
+      if (existing && existing.url === entry.url.replace(/\/+$/, '')) continue;
+      if (existing) this._teardownEndpoint(existing);
+      this._connectEndpoint(entry);
+    }
+    for (const [name, ep] of this.endpoints) {
+      if (!keep.has(name)) {
+        this._teardownEndpoint(ep);
+        this.endpoints.delete(name);
+      }
+    }
+  }
+
+  _connectEndpoint({ name, url }) {
+    const ep = {
+      name,
+      url: url.replace(/\/+$/, ''),
+      status: 'connecting', // connecting | connected | error
+      error: null,
+      about: null,
+      drift: null, // {novel: [], missing: []} vs KNOWN_KINDS
+      sessions: new Map(), // sessionId -> session state
+      pollTimer: null,
+      backoffMs: this.backoffBaseMs,
+    };
+    this.endpoints.set(name, ep);
+    this._handshake(ep);
+    return ep;
+  }
+
+  async _fetch(ep, path, options = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await fetch(`${ep.url}${path}`, { ...options, signal: controller.signal });
+      if (!res.ok) throw new Error(`HTTP ${res.status} from ${path}`);
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async _handshake(ep) {
+    if (this.destroyed) return;
+    try {
+      const about = await this._fetch(ep, '/about');
+      ep.about = about;
+      // Mechanical schema handshake (contract §6): compare, surface, never drop.
+      const remote = Array.isArray(about.kinds) ? about.kinds : [];
+      ep.drift = {
+        novel: remote.filter((k) => !KNOWN_KINDS.includes(k)),
+        missing: remote.length ? KNOWN_KINDS.filter((k) => !remote.includes(k)) : [],
+      };
+      ep.status = 'connected';
+      ep.error = null;
+      ep.backoffMs = this.backoffBaseMs;
+      this._broadcastStatus();
+      await this._pollSessions(ep);
+      ep.pollTimer = setInterval(() => {
+        this._pollSessions(ep).catch(() => this._endpointLost(ep));
+      }, this.sessionPollMs);
+    } catch (err) {
+      ep.status = 'error';
+      ep.error = err.message;
+      this._broadcastStatus();
+      this._scheduleEndpointRetry(ep);
+    }
+  }
+
+  _endpointLost(ep) {
+    if (this.destroyed || ep.status === 'error') return;
+    ep.status = 'error';
+    ep.error = 'endpoint unreachable';
+    if (ep.pollTimer) { clearInterval(ep.pollTimer); ep.pollTimer = null; }
+    this._broadcastStatus();
+    this._scheduleEndpointRetry(ep);
+  }
+
+  _scheduleEndpointRetry(ep) {
+    if (this.destroyed) return;
+    ep.retryTimer = setTimeout(() => {
+      ep.backoffMs = Math.min(ep.backoffMs * 2, BACKOFF_MAX_MS);
+      this._handshake(ep);
+    }, ep.backoffMs);
+  }
+
+  async _pollSessions(ep) {
+    const list = await this._fetch(ep, '/sessions');
+    if (!Array.isArray(list)) return;
+    for (const info of list) {
+      const id = info.session;
+      if (!id || typeof id !== 'string') continue;
+      let s = ep.sessions.get(id);
+      if (!s) {
+        s = {
+          id,
+          started: info.started ?? null,
+          live: !!info.live,
+          ws: null,
+          lastSeq: 0,
+          ring: [],
+          overflow: 0,
+          unknownKinds: {},
+          reconnectTimer: null,
+        };
+        ep.sessions.set(id, s);
+      }
+      // §12: `live` means a turn is in flight; sessions persist between turns
+      // and events can start at any moment — stay attached regardless.
+      s.live = !!info.live;
+      if (!s.ws) this._watchSession(ep, s);
+    }
+  }
+
+  _watchSession(ep, s) {
+    if (this.destroyed) return;
+    const since = s.lastSeq > 0 ? `?since=ev-${String(s.lastSeq).padStart(6, '0')}` : '';
+    const wsUrl = `${ep.url.replace(/^http/, 'ws')}/ws/session/${encodeURIComponent(s.id)}${since}`;
+    const ws = new WebSocket(wsUrl);
+    s.ws = ws;
+
+    ws.on('message', (data) => {
+      let envelope;
+      try { envelope = JSON.parse(data.toString()); } catch { return; }
+      const seq = seqOf(envelope.id);
+      // Dedup on ring-buffer replay after reconnect — ids are monotonic.
+      if (seq !== null && seq <= s.lastSeq) return;
+      if (seq !== null) s.lastSeq = seq;
+      if (s.ring.length >= this.ringSize) {
+        s.ring.shift();
+        // The ring bounds memory, not delivery: overflow is counted, never
+        // silent, and every event still broadcasts — mirrors the runtime.
+        s.overflow += 1;
+      }
+      s.ring.push(envelope);
+      if (envelope.kind && !KNOWN_KINDS.includes(envelope.kind)) {
+        s.unknownKinds[envelope.kind] = (s.unknownKinds[envelope.kind] || 0) + 1;
+      }
+      // Verbatim passthrough — the envelope is the contract, GROOVE adds
+      // routing metadata around it, never inside it.
+      this.daemon.broadcast({ type: 'axom:event', endpoint: ep.name, session: s.id, envelope });
+    });
+
+    const onGone = () => {
+      if (s.ws !== ws) return;
+      s.ws = null;
+      // Identity check, not name check: after configure() replaces an
+      // endpoint, a late close from the old socket must not re-arm a
+      // reconnect loop on the orphaned object — destroy() could never reach
+      // it (this exact leak wedged a test worker into an infinite loop).
+      if (this.destroyed || this.endpoints.get(ep.name) !== ep) return;
+      s.reconnectTimer = setTimeout(() => this._watchSession(ep, s), ep.backoffMs);
+    };
+    ws.on('close', onGone);
+    ws.on('error', onGone);
+  }
+
+  // §12 message verb: starts a turn (interrupt steers, stop halts). Status is
+  // part of the contract (202 accepted / 409 busy / 413 too_long) so this
+  // returns {status, body} verbatim instead of throwing on non-2xx.
+  async message(endpointName, sessionId, text) {
+    const ep = this._requireEndpoint(endpointName);
+    const res = await fetch(`${ep.url}/session/${encodeURIComponent(sessionId)}/message`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text }),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    // First message creates the session (caller-chosen id) — poll now so the
+    // WS attaches before the turn's first events age out of nothing.
+    if (res.status === 202) this._pollSessions(ep).catch(() => {});
+    return { status: res.status, body };
+  }
+
+  async interrupt(endpointName, sessionId, text) {
+    const ep = this._requireEndpoint(endpointName);
+    return this._fetch(ep, `/session/${encodeURIComponent(sessionId)}/interrupt`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text }),
+    });
+  }
+
+  async stop(endpointName, sessionId) {
+    const ep = this._requireEndpoint(endpointName);
+    return this._fetch(ep, `/session/${encodeURIComponent(sessionId)}/stop`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+  }
+
+  _requireEndpoint(name) {
+    // Single-endpoint convenience: an omitted name resolves iff unambiguous.
+    if (!name && this.endpoints.size === 1) return this.endpoints.values().next().value;
+    const ep = this.endpoints.get(name);
+    if (!ep) throw new Error(`No Axom endpoint named "${name}"`);
+    return ep;
+  }
+
+  events(endpointName, sessionId, sinceSeq = 0) {
+    const ep = this._requireEndpoint(endpointName);
+    const s = ep.sessions.get(sessionId);
+    if (!s) throw new Error(`No session "${sessionId}" on endpoint "${ep.name}"`);
+    const events = sinceSeq > 0 ? s.ring.filter((e) => (seqOf(e.id) || 0) > sinceSeq) : s.ring;
+    return { session: s.id, overflow: s.overflow, events };
+  }
+
+  status() {
+    return {
+      endpoints: [...this.endpoints.values()].map((ep) => ({
+        name: ep.name,
+        url: ep.url,
+        status: ep.status,
+        error: ep.error,
+        about: ep.about,
+        drift: ep.drift,
+        sessions: [...ep.sessions.values()].map((s) => ({
+          session: s.id,
+          started: s.started,
+          live: s.live,
+          watching: !!s.ws,
+          lastEventId: s.lastSeq > 0 ? `ev-${String(s.lastSeq).padStart(6, '0')}` : null,
+          buffered: s.ring.length,
+          overflow: s.overflow,
+          unknownKinds: s.unknownKinds,
+        })),
+      })),
+    };
+  }
+
+  _broadcastStatus() {
+    this.daemon.broadcast({ type: 'axom:status', data: this.status() });
+  }
+
+  _teardownEndpoint(ep) {
+    if (ep.pollTimer) clearInterval(ep.pollTimer);
+    if (ep.retryTimer) clearTimeout(ep.retryTimer);
+    for (const s of ep.sessions.values()) {
+      if (s.reconnectTimer) clearTimeout(s.reconnectTimer);
+      // terminate, not close: close() on a CONNECTING socket defers teardown
+      // until the connect completes — a live handle that can outlast us.
+      if (s.ws) { try { s.ws.terminate(); } catch { /* already gone */ } s.ws = null; }
+    }
+  }
+
+  destroy() {
+    this.destroyed = true;
+    for (const ep of this.endpoints.values()) this._teardownEndpoint(ep);
+    this.endpoints.clear();
+  }
+}