ghostbus 0.0.0-stage → 0.5.2

package/src/core.mjs

@@ -0,0 +1,645 @@
+/**
+ * GhostBus core — transport-agnostic agent-to-agent message bus + shared workspace.
+ *
+ * One workspace holds: registered agents, direct/broadcast messages, claimable
+ * tasks (with leases + an approval gate), shared files, a shared context object,
+ * and an append-only provenance event log. Every mutation is stamped with the
+ * acting agent and a timestamp — nothing enters the workspace anonymously.
+ *
+ * Storage: any object with async load() -> state|null and async save(state).
+ * Ships with MemoryStore and FileStore (atomic JSON file).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const GHOSTBUS_VERSION = '0.5.2';
+const sha256 = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
+export const TASK_STATUSES = ['queued', 'claimed', 'needs-approval', 'done', 'cancelled'];
+const CLAIM_LEASE_MS = 15 * 60 * 1000;
+
+const now = () => new Date().toISOString();
+const clone = (v) => JSON.parse(JSON.stringify(v));
+
+function emptyState(workspace = {}) {
+  return {
+    workspace: {
+      id: workspace.id || 'default',
+      name: workspace.name || 'GhostBus Workspace',
+      createdAt: now(),
+    },
+    seq: 0,          // event sequence
+    msgSeq: 0,
+    taskSeq: 0,
+    agents: [],      // {name, role, capabilities, joinedAt, lastSeenAt}
+    messages: [],    // {id, from, to, channel, body, threadId, createdAt, readBy[]}
+    tasks: [],       // {id, title, body, from, assignee, status, priority, ...}
+    files: {},       // path -> {text, updatedBy, updatedAt}
+    context: null,   // arbitrary shared object (must have .projects? no — free-form)
+    events: [],      // {seq, type, actor, at, summary}
+  };
+}
+
+export class MemoryStore {
+  constructor() { this.state = null; }
+  async load() { return this.state ? clone(this.state) : null; }
+  async save(state) { this.state = clone(state); }
+}
+
+export class FileStore {
+  constructor(file) { this.file = file; this.shared = true; this._chain = Promise.resolve(); }
+  async load() {
+    try { return JSON.parse(await fs.promises.readFile(this.file, 'utf8')); }
+    catch { return null; }
+  }
+  async save(state) {
+    // Serialize saves within this process, and give every save its own temp
+    // file: two writers (this process or another sharing the same store
+    // file) must never collide on one fixed '.tmp' name — the first rename
+    // moves it away and the second save then fails ENOENT.
+    const run = async () => {
+      await fs.promises.mkdir(path.dirname(this.file), { recursive: true });
+      const tmp = this.file + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 10);
+      try {
+        await fs.promises.writeFile(tmp, JSON.stringify(state, null, 2));
+        await fs.promises.rename(tmp, this.file); // atomic replace
+      } finally {
+        await fs.promises.unlink(tmp).catch(() => {});
+      }
+    };
+    const p = this._chain.then(run, run);
+    this._chain = p.catch(() => {});
+    return p;
+  }
+}
+
+export class GhostBus {
+  constructor(store, workspace = {}, opts = {}) {
+    this.store = store;
+    this.workspaceInfo = workspace;
+    this.state = null;
+    // When true, every act by an agent that holds a token must present it.
+    // Registration issues the token once; only its sha256 is stored.
+    this.requireTokens = !!opts.requireTokens;
+    this.listeners = new Set(); // live event subscribers (SSE relay)
+    // Mutation mutex (v0.5.1): a promise chain serializing every public
+    // operation's load -> mutate -> save cycle on THIS instance. Without it,
+    // concurrent calls interleave their cycles against the shared store and
+    // silently lose each other's updates (one op's reload discards another's
+    // not-yet-saved state). The AsyncLocalStorage marker makes the chain
+    // reentrant: public methods that call other public methods (updateCapsule
+    // -> getCapsule, restore -> status, heartbeat -> listAgents) run inline
+    // instead of deadlocking on their own queue.
+    this._chain = Promise.resolve();
+    this._als = new AsyncLocalStorage();
+  }
+
+  /**
+   * Run `fn` inside this bus's serialized section. Callers queue FIFO on the
+   * promise chain; a throwing operation still releases the chain (finally),
+   * so one failure can never wedge the bus. Scope: per Bus instance, in this
+   * process — it cannot span processes sharing one store file (each op there
+   * is still a single atomic read-modify-write) nor serverless invocations.
+   */
+  async _serialized(fn) {
+    if (this._als.getStore() === this) return fn();
+    const prev = this._chain;
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    this._chain = prev.then(() => gate);
+    await prev;
+    try {
+      return await this._als.run(this, fn);
+    } finally {
+      release();
+    }
+  }
+
+  /** Subscribe to provenance events as they happen. Returns an unsubscribe fn. */
+  onEvent(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
+
+  async init() { return this._serialized(() => this._init()); }
+  async _init() {
+    // Shared (file) stores are re-read on every call: several processes
+    // (stdio servers, the CLI, a relay) can then share ONE workspace file
+    // and actually see each other's writes. Each mutation is a fresh
+    // read-modify-write with an atomic replace, so the race window is a
+    // single operation. Memory stores skip the reload.
+    if (this.state && !this.store.shared) return this;
+    const loaded = await this.store.load();
+    if (loaded) this.state = loaded;
+    else if (!this.state) this.state = emptyState(this.workspaceInfo);
+    return this;
+  }
+
+  async _save() { await this.store.save(this.state); }
+
+  _event(type, actor, summary, meta = {}) {
+    this.state.seq += 1;
+    const ev = { seq: this.state.seq, type, actor: actor || 'system', at: now(), summary, ...meta };
+    this.state.events.push(ev);
+    if (this.state.events.length > 5000) this.state.events.splice(0, this.state.events.length - 5000);
+    for (const fn of this.listeners) { try { fn(clone(ev)); } catch { /* a dead listener never breaks the bus */ } }
+  }
+
+  _agent(name) { return this.state.agents.find(a => a.name === name) || null; }
+
+  _publicAgent(a) {
+    const { tokenHash, ...pub } = a;
+    return { ...pub, online: Date.now() - Date.parse(a.lastSeenAt) < 120_000, hasToken: !!tokenHash };
+  }
+
+  _existsAgent(name) {
+    const a = this._agent(name);
+    if (!a) throw Object.assign(new Error(`agent not registered: ${name}`), { code: 'UNKNOWN_AGENT' });
+    return a;
+  }
+
+  _requireAgent(name, token) {
+    const a = this._agent(name);
+    if (!a) throw Object.assign(new Error(`agent not registered: ${name}`), { code: 'UNKNOWN_AGENT' });
+    if (this.requireTokens && a.tokenHash) {
+      if (!token || sha256(token) !== a.tokenHash) {
+        throw Object.assign(new Error(`agent token required or wrong for: ${name}`), { code: 'AGENT_AUTH' });
+      }
+    }
+    a.lastSeenAt = now();
+    return a;
+  }
+
+  // ---------- agents ----------
+  async registerAgent(...args) { return this._serialized(() => this._registerAgent(...args)); }
+  async _registerAgent({ name, role = '', capabilities = [], token = null }) {
+    await this.init();
+    if (!name || typeof name !== 'string') throw new Error('agent name required');
+    name = name.trim();
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)) throw new Error('agent name: letters, digits, . _ - only (max 64)');
+    const existing = this._agent(name);
+    if (existing) {
+      // In token mode, changing a registered identity requires its token.
+      if (this.requireTokens && existing.tokenHash && (role || (Array.isArray(capabilities) && capabilities.length))) {
+        this._requireAgent(name, token);
+      }
+      existing.role = role || existing.role;
+      if (Array.isArray(capabilities) && capabilities.length) existing.capabilities = capabilities.map(String).slice(0, 32);
+      existing.lastSeenAt = now();
+      this._event('agent.rejoin', name, `${name} rejoined`);
+      await this._save();
+      return { agent: this._publicAgent(existing), rejoined: true };
+    }
+    const rawToken = crypto.randomBytes(24).toString('hex');
+    const agent = { name, role: String(role).slice(0, 200), capabilities: Array.isArray(capabilities) ? capabilities.map(String).slice(0, 32) : [], joinedAt: now(), lastSeenAt: now(), tokenHash: sha256(rawToken) };
+    this.state.agents.push(agent);
+    this._event('agent.join', name, `${name} joined (${agent.role || 'no role'})`);
+    await this._save();
+    // The raw token is returned ONCE, here. Only its hash is ever stored.
+    return { agent: this._publicAgent(agent), rejoined: false, token: rawToken, tokenNote: 'Store this token — it is shown once and only its hash is kept. Present it as `token` (tools) or x-agent-token (HTTP) when the bus runs with requireTokens.' };
+  }
+
+  async rotateAgentToken(...args) { return this._serialized(() => this._rotateAgentToken(...args)); }
+  async _rotateAgentToken({ name, token = null }) {
+    await this.init();
+    const a = this._requireAgent(name, token);
+    const rawToken = crypto.randomBytes(24).toString('hex');
+    a.tokenHash = sha256(rawToken);
+    this._event('agent.token_rotate', name, `${name} rotated its agent token`);
+    await this._save();
+    return { agent: this._publicAgent(a), token: rawToken, tokenNote: 'New token — the old one no longer works. Shown once.' };
+  }
+
+  async heartbeat(...args) { return this._serialized(() => this._heartbeat(...args)); }
+  async _heartbeat({ name, token = null }) {
+    await this.init();
+    const a = this._requireAgent(name, token);
+    return { agent: this._publicAgent(a), agents: await this.listAgents() };
+  }
+
+  async listAgents(...args) { return this._serialized(() => this._listAgents(...args)); }
+  async _listAgents() { await this.init(); return this.state.agents.map(a => this._publicAgent(a)); }
+
+  // ---------- messages ----------
+  async sendMessage(...args) { return this._serialized(() => this._sendMessage(...args)); }
+  async _sendMessage({ from, to = '*', body, channel = 'general', threadId = null, token = null }) {
+    await this.init();
+    this._requireAgent(from, token);
+    if (to !== '*') this._existsAgent(to);
+    if (!body || !String(body).trim()) throw new Error('message body required');
+    this.state.msgSeq += 1;
+    const msg = {
+      id: this.state.msgSeq, from, to, channel: String(channel).slice(0, 64),
+      body: String(body), threadId: threadId ? Number(threadId) : null,
+      createdAt: now(), readBy: [from],
+    };
+    this.state.messages.push(msg);
+    if (this.state.messages.length > 10000) this.state.messages.splice(0, this.state.messages.length - 10000);
+    this._event('message.send', from, `${from} -> ${to} (#${msg.id})`, { to, channel: msg.channel, messageId: msg.id, excerpt: msg.body.slice(0, 280) });
+    await this._save();
+    return clone(msg);
+  }
+
+  /** Messages visible to `agent`: addressed to it, broadcast, or sent by it. Unread-first filtering optional. */
+  async inbox(...args) { return this._serialized(() => this._inbox(...args)); }
+  async _inbox(agentName, { unreadOnly = false, limit = 50, markRead = true, token = null } = {}) {
+    await this.init();
+    this._requireAgent(agentName, token);
+    let msgs = this.state.messages.filter(m =>
+      m.to === agentName || m.to === '*' || m.from === agentName);
+    if (unreadOnly) msgs = msgs.filter(m => !m.readBy.includes(agentName));
+    msgs = msgs.slice(-Math.min(limit, 500));
+    if (markRead) {
+      let changed = false;
+      for (const m of msgs) if (!m.readBy.includes(agentName)) { m.readBy.push(agentName); changed = true; }
+      if (changed) await this._save();
+    }
+    return clone(msgs);
+  }
+
+  async thread(...args) { return this._serialized(() => this._thread(...args)); }
+  async _thread(id) {
+    await this.init();
+    const root = this.state.messages.find(m => m.id === Number(id));
+    if (!root) throw new Error(`message not found: ${id}`);
+    return clone(this.state.messages.filter(m => m.id === root.id || m.threadId === root.id));
+  }
+
+  // ---------- tasks ----------
+  async createTask(...args) { return this._serialized(() => this._createTask(...args)); }
+  async _createTask({ from, title, body = '', assignee = null, priority = 'normal', needsApproval = false, blockedBy = [], token = null }) {
+    await this.init();
+    this._requireAgent(from, token);
+    if (assignee) this._existsAgent(assignee);
+    if (!title || !String(title).trim()) throw new Error('task title required');
+    this.state.taskSeq += 1;
+    const task = {
+      id: this.state.taskSeq, title: String(title).slice(0, 300), body: String(body),
+      from, assignee: assignee || null, priority: priority === 'urgent' ? 'urgent' : 'normal',
+      status: needsApproval ? 'needs-approval' : 'queued',
+      needsApproval: !!needsApproval, approvedBy: null,
+      claimedBy: null, claimExpiresAt: null, result: null, comments: [], blockedBy: Array.isArray(blockedBy) ? blockedBy.map(Number).filter(n => n >= 1) : [],
+      createdAt: now(), updatedAt: now(),
+      history: [{ at: now(), by: from, action: needsApproval ? 'created (awaiting approval)' : 'created' }],
+    };
+    for (const b of task.blockedBy) if (!this.state.tasks.some(t => t.id === b)) throw new Error(`blocker task not found: ${b}`);
+    this.state.tasks.push(task);
+    this._event('task.create', from, `task #${task.id}: ${task.title}`);
+    await this._save();
+    return clone(task);
+  }
+
+  _expireClaims() {
+    const t = Date.now();
+    for (const task of this.state.tasks) {
+      if (task.status === 'claimed' && task.claimExpiresAt && Date.parse(task.claimExpiresAt) < t) {
+        task.status = 'queued'; task.claimedBy = null; task.claimExpiresAt = null; task.updatedAt = now();
+        task.history.push({ at: now(), by: 'system', action: 'claim lease expired — returned to queue' });
+        this._event('task.claim_expired', 'system', `task #${task.id} claim expired`);
+      }
+    }
+  }
+
+  async listTasks(...args) { return this._serialized(() => this._listTasks(...args)); }
+  async _listTasks({ status = null, assignee = null } = {}) {
+    await this.init();
+    this._expireClaims(); await this._save();
+    let tasks = this.state.tasks;
+    if (status) tasks = tasks.filter(t => t.status === status);
+    if (assignee) tasks = tasks.filter(t => t.assignee === assignee || t.claimedBy === assignee);
+    return clone(tasks.sort((a, b) => b.id - a.id));
+  }
+
+  async approveTask(...args) { return this._serialized(() => this._approveTask(...args)); }
+  async _approveTask(id, { by, token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    const task = this._task(id);
+    if (task.status !== 'needs-approval') throw new Error(`task #${id} is not awaiting approval (status: ${task.status})`);
+    task.status = 'queued'; task.approvedBy = by; task.updatedAt = now();
+    task.history.push({ at: now(), by, action: 'approved' });
+    this._event('task.approve', by, `task #${id} approved`);
+    await this._save();
+    return clone(task);
+  }
+
+  /** Claim is exclusive: a second claim while a lease is live fails loudly. */
+  async claimTask(...args) { return this._serialized(() => this._claimTask(...args)); }
+  async _claimTask(id, { by, token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    this._expireClaims();
+    const task = this._task(id);
+    if (task.status === 'claimed') throw Object.assign(new Error(`task #${id} already claimed by ${task.claimedBy}`), { code: 'ALREADY_CLAIMED' });
+    if (task.status !== 'queued') throw new Error(`task #${id} cannot be claimed (status: ${task.status})`);
+    if (task.assignee && task.assignee !== by) throw new Error(`task #${id} is assigned to ${task.assignee}`);
+    const openBlockers = (task.blockedBy || []).filter(bid => { const b = this.state.tasks.find(t => t.id === bid); return b && !['done', 'cancelled'].includes(b.status); });
+    if (openBlockers.length) throw Object.assign(new Error(`task #${id} is blocked by unfinished task(s): ${openBlockers.join(', ')}`), { code: 'BLOCKED' });
+    task.status = 'claimed'; task.claimedBy = by;
+    task.claimExpiresAt = new Date(Date.now() + CLAIM_LEASE_MS).toISOString();
+    task.updatedAt = now();
+    task.history.push({ at: now(), by, action: 'claimed' });
+    this._event('task.claim', by, `task #${id} claimed by ${by}`);
+    await this._save();
+    return clone(task);
+  }
+
+  async completeTask(...args) { return this._serialized(() => this._completeTask(...args)); }
+  async _completeTask(id, { by, result = '', token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    const task = this._task(id);
+    if (task.status !== 'claimed') throw new Error(`task #${id} is not claimed (status: ${task.status})`);
+    if (task.claimedBy !== by) throw new Error(`task #${id} is claimed by ${task.claimedBy}, not ${by}`);
+    task.status = 'done'; task.result = String(result); task.claimExpiresAt = null; task.updatedAt = now();
+    task.history.push({ at: now(), by, action: 'completed' });
+    this._event('task.complete', by, `task #${id} completed`);
+    await this._save();
+    return clone(task);
+  }
+
+  async cancelTask(...args) { return this._serialized(() => this._cancelTask(...args)); }
+  async _cancelTask(id, { by, token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    const task = this._task(id);
+    if (['done', 'cancelled'].includes(task.status)) throw new Error(`task #${id} already ${task.status}`);
+    task.status = 'cancelled'; task.updatedAt = now();
+    task.history.push({ at: now(), by, action: 'cancelled' });
+    this._event('task.cancel', by, `task #${id} cancelled`);
+    await this._save();
+    return clone(task);
+  }
+
+  _task(id) {
+    const task = this.state.tasks.find(t => t.id === Number(id));
+    if (!task) throw new Error(`task not found: ${id}`);
+    return task;
+  }
+
+  // ---------- shared workspace: files + context + board ----------
+  async putFile(...args) { return this._serialized(() => this._putFile(...args)); }
+  async _putFile({ by, path: p, text, token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    if (!p || typeof text !== 'string') throw new Error('path and text required');
+    if (String(p).includes('..')) throw new Error('path may not contain ..');
+    const prev = this.state.files[p];
+    const history = prev ? [...(prev.history || []), { text: prev.text, updatedBy: prev.updatedBy, updatedAt: prev.updatedAt }].slice(-10) : [];
+    this.state.files[p] = { text, updatedBy: by, updatedAt: now(), history };
+    this._event('file.put', by, `${by} wrote ${p} (${text.length} chars)`);
+    await this._save();
+    return { path: p, bytes: Buffer.byteLength(text) };
+  }
+
+  async getFile(...args) { return this._serialized(() => this._getFile(...args)); }
+  async _getFile(p, { withHistory = false } = {}) {
+    await this.init();
+    const f = this.state.files[p];
+    if (!f) throw new Error(`file not found: ${p}`);
+    const { history, ...rest } = f;
+    return { path: p, ...clone(rest), versions: (history || []).length + 1, ...(withHistory ? { history: clone(history || []) } : {}) };
+  }
+
+  async fileHistory(...args) { return this._serialized(() => this._fileHistory(...args)); }
+  async _fileHistory(p) {
+    await this.init();
+    const f = this.state.files[p];
+    if (!f) throw new Error(`file not found: ${p}`);
+    return { path: p, current: { text: f.text, updatedBy: f.updatedBy, updatedAt: f.updatedAt }, history: clone(f.history || []) };
+  }
+
+  async listFiles(...args) { return this._serialized(() => this._listFiles(...args)); }
+  async _listFiles() {
+    await this.init();
+    return Object.entries(this.state.files).map(([p, f]) => ({ path: p, bytes: Buffer.byteLength(f.text), updatedBy: f.updatedBy, updatedAt: f.updatedAt }));
+  }
+
+  async putContext(...args) { return this._serialized(() => this._putContext(...args)); }
+  async _putContext({ by, context, token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    if (!context || typeof context !== 'object' || Array.isArray(context)) throw new Error('context must be an object');
+    this.state.context = clone(context);
+    this._event('context.put', by, `${by} published context`);
+    await this._save();
+    return { ok: true };
+  }
+
+  async getContext(...args) { return this._serialized(() => this._getContext(...args)); }
+  async _getContext() {
+    await this.init();
+    if (!this.state.context) throw new Error('no context published yet');
+    return clone(this.state.context);
+  }
+
+  async addTaskComment(...args) { return this._serialized(() => this._addTaskComment(...args)); }
+  async _addTaskComment(id, { by, body, token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    if (!body || !String(body).trim()) throw new Error('comment body required');
+    const task = this._task(id);
+    task.comments = task.comments || [];
+    const comment = { by, body: String(body), at: now() };
+    task.comments.push(comment);
+    task.updatedAt = now();
+    task.history.push({ at: now(), by, action: 'commented' });
+    this._event('task.comment', by, `${by} commented on task #${id}`, { taskId: task.id });
+    await this._save();
+    return clone(task);
+  }
+
+  async deleteFile(...args) { return this._serialized(() => this._deleteFile(...args)); }
+  async _deleteFile({ by, path: p, token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    if (!this.state.files[p]) throw new Error(`file not found: ${p}`);
+    delete this.state.files[p];
+    this._event('file.delete', by, `${by} deleted ${p}`);
+    await this._save();
+    return { path: p, deleted: true };
+  }
+
+  async listChannels(...args) { return this._serialized(() => this._listChannels(...args)); }
+  async _listChannels() {
+    await this.init();
+    const counts = {};
+    for (const m of this.state.messages) counts[m.channel] = (counts[m.channel] || 0) + 1;
+    return Object.entries(counts).map(([channel, messages]) => ({ channel, messages })).sort((a, b) => b.messages - a.messages);
+  }
+
+  /** Full-text search across messages, tasks, and shared files. */
+  async search(...args) { return this._serialized(() => this._search(...args)); }
+  async _search(query, { limit = 20 } = {}) {
+    await this.init();
+    const q = String(query || '').toLowerCase().trim();
+    if (q.length < 2) throw new Error('search query needs at least 2 characters');
+    const hit = (text) => String(text || '').toLowerCase().includes(q);
+    return {
+      query,
+      messages: clone(this.state.messages.filter(m => hit(m.body)).slice(-limit)),
+      tasks: clone(this.state.tasks.filter(t => hit(t.title) || hit(t.body) || hit(t.result)).slice(-limit)),
+      files: Object.entries(this.state.files).filter(([p, f]) => hit(p) || hit(f.text)).slice(0, limit)
+        .map(([p, f]) => ({ path: p, updatedBy: f.updatedBy, updatedAt: f.updatedAt, excerpt: f.text.slice(0, 200) })),
+    };
+  }
+
+
+  _capsulePath(slug) {
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(String(slug))) throw new Error('capsule slug: lowercase letters, digits, - only');
+    return `capsules/${slug}.md`;
+  }
+
+  _capsuleTemplate(slug, title) {
+    return `# Capsule: ${title || slug}\n\n## State\n\n## Decisions (locked)\n\n## Next\n\n## Session log\n`;
+  }
+
+  /** Read a project capsule, creating it from the template on first touch when create=true. */
+  async getCapsule(...args) { return this._serialized(() => this._getCapsule(...args)); }
+  async _getCapsule(slug, { create = false, title = '', by = null, token = null } = {}) {
+    await this.init();
+    const pth = this._capsulePath(slug);
+    if (!this.state.files[pth]) {
+      if (!create) throw new Error(`capsule not found: ${slug}`);
+      if (by) this._requireAgent(by, token);
+      this.state.files[pth] = { text: this._capsuleTemplate(slug, title), updatedBy: by || 'system', updatedAt: now(), history: [] };
+      this._event('capsule.create', by || 'system', `capsule ${slug} created`);
+      await this._save();
+    }
+    return this.getFile(pth);
+  }
+
+  /** Replace one capsule section (State / Decisions / Next) or append to the Session log. */
+  async updateCapsule(...args) { return this._serialized(() => this._updateCapsule(...args)); }
+  async _updateCapsule(slug, { by, section, text, token = null }) {
+    await this.init();
+    this._requireAgent(by, token);
+    await this.getCapsule(slug, { create: true, by, token });
+    const pth = this._capsulePath(slug);
+    const cur = this.state.files[pth].text;
+    const SECTIONS = ['State', 'Decisions (locked)', 'Next', 'Session log'];
+    if (!SECTIONS.includes(section)) throw new Error(`section must be one of: ${SECTIONS.join(' | ')}`);
+    const marker = `## ${section}`;
+    const start = cur.indexOf(marker);
+    if (start < 0) throw new Error(`capsule ${slug} is missing section ${section}`);
+    const afterHead = start + marker.length;
+    const rest = cur.slice(afterHead);
+    const nextIdx = rest.indexOf('\n## ');
+    const tail = nextIdx >= 0 ? rest.slice(nextIdx) : '';
+    const entry = section === 'Session log'
+      ? `${rest.trimEnd() ? rest.replace(/\s+$/, '') + '\n' : '\n'}- ${now()} · ${by} — ${String(text).trim()}\n`
+      : `\n\n${String(text).trim()}\n`;
+    const updated = cur.slice(0, afterHead) + entry + tail.replace(/^\n+/, tail ? '\n' : '');
+    const prev = this.state.files[pth];
+    this.state.files[pth] = { text: updated.endsWith('\n') ? updated : updated + '\n', updatedBy: by, updatedAt: now(), history: [...(prev.history || []), { text: prev.text, updatedBy: prev.updatedBy, updatedAt: prev.updatedAt }].slice(-10) };
+    this._event('capsule.update', by, `${by} updated capsule ${slug} [${section}]`, { capsule: slug });
+    await this._save();
+    return this.getFile(pth);
+  }
+
+  async listCapsules(...args) { return this._serialized(() => this._listCapsules(...args)); }
+  async _listCapsules() {
+    await this.init();
+    return Object.keys(this.state.files).filter(p => p.startsWith('capsules/') && p.endsWith('.md')).map(p => p.slice('capsules/'.length, -3)).sort();
+  }
+
+  /** A human-readable board rendered from live state — the shared picture at a glance. */
+  async board(...args) { return this._serialized(() => this._board(...args)); }
+  async _board() {
+    await this.init();
+    this._expireClaims();
+    const s = this.state;
+    const lines = [
+      `# ${s.workspace.name} — Board`,
+      `Updated: ${now()} · GhostBus v${GHOSTBUS_VERSION}`,
+      '',
+      `## Agents (${s.agents.length})`,
+      ...(s.agents.length ? s.agents.map(a => `- **${a.name}** — ${a.role || 'agent'}${a.capabilities.length ? ` · ${a.capabilities.join(', ')}` : ''} · last seen ${a.lastSeenAt}`) : ['- (none registered)']),
+      '',
+      `## Open tasks (${s.tasks.filter(t => !['done', 'cancelled'].includes(t.status)).length})`,
+      ...(s.tasks.filter(t => !['done', 'cancelled'].includes(t.status)).length
+        ? s.tasks.filter(t => !['done', 'cancelled'].includes(t.status)).map(t => `- #${t.id} [${t.status}] ${t.title}${t.claimedBy ? ` — claimed by ${t.claimedBy}` : ''}${t.assignee ? ` — for ${t.assignee}` : ''}`)
+        : ['- (none)']),
+      '',
+      `## Files (${Object.keys(s.files).length})`,
+      ...(Object.keys(s.files).length ? Object.keys(s.files).sort().map(p => `- ${p} (${s.files[p].updatedBy}, ${s.files[p].updatedAt})`) : ['- (none)']),
+      '',
+      `## Recent activity`,
+      ...s.events.slice(-10).reverse().map(e => `- ${e.at} · ${e.actor} · ${e.summary}`),
+      '',
+    ];
+    return lines.join('\n');
+  }
+
+  /** Catch-up sync: every event after `sinceSeq`, plus the current head seq.
+   *  An agent that was offline replays exactly what it missed — nothing more. */
+  async sync(...args) { return this._serialized(() => this._sync(...args)); }
+  async _sync({ sinceSeq = 0, limit = 500 } = {}) {
+    await this.init();
+    const evs = this.state.events.filter(e => e.seq > Number(sinceSeq));
+    return { events: clone(evs.slice(0, Math.min(limit, 1000))), headSeq: this.state.seq, truncated: evs.length > Math.min(limit, 1000) };
+  }
+
+  async events(...args) { return this._serialized(() => this._events(...args)); }
+  async _events({ limit = 50 } = {}) {
+    await this.init();
+    return clone(this.state.events.slice(-Math.min(limit, 500)));
+  }
+
+  async status(...args) { return this._serialized(() => this._status(...args)); }
+  async _status() {
+    await this.init();
+    this._expireClaims();
+    const s = this.state;
+    return {
+      server: 'ghostbus', version: GHOSTBUS_VERSION, workspace: s.workspace,
+      agents: s.agents.length,
+      messages: s.messages.length,
+      tasks: { total: s.tasks.length, queued: s.tasks.filter(t => t.status === 'queued').length, claimed: s.tasks.filter(t => t.status === 'claimed').length, needsApproval: s.tasks.filter(t => t.status === 'needs-approval').length, done: s.tasks.filter(t => t.status === 'done').length },
+      files: Object.keys(s.files).length,
+      hasContext: !!s.context,
+      events: s.events.length,
+    };
+  }
+
+  /** Full-state snapshot for backup / migration. The state holds agent token
+   *  HASHES only, never plaintext secrets; workspace keys live outside the
+   *  state (hosted registry) and are never part of a snapshot. */
+  async snapshot(...args) { return this._serialized(() => this._snapshot(...args)); }
+  async _snapshot() {
+    await this.init();
+    return clone(this.state);
+  }
+
+  /** Replace this workspace's state with a snapshot (restore / import).
+   *  The snapshot is shape-validated, the workspace identity is preserved
+   *  unless the snapshot carries one, and the restore itself is recorded
+   *  in the provenance log. Returns the post-restore status. */
+  async restore(...args) { return this._serialized(() => this._restore(...args)); }
+  async _restore(snapshot, { by = 'operator' } = {}) {
+    await this.init();
+    const bad = validateSnapshot(snapshot);
+    if (bad) throw Object.assign(new Error(`invalid snapshot: ${bad}`), { code: 'BAD_SNAPSHOT' });
+    const next = clone(snapshot);
+    next.workspace = { ...next.workspace, id: this.state.workspace.id, name: next.workspace.name || this.state.workspace.name };
+    this.state = next;
+    this._event('workspace.restore', by, `workspace restored from snapshot (${next.agents.length} agents, ${next.tasks.length} tasks, ${next.messages.length} messages)`);
+    await this._save();
+    return this.status();
+  }
+}
+
+/** Shape-check a candidate workspace snapshot. Returns null when valid,
+ *  otherwise a short description of the first problem found. */
+export function validateSnapshot(s) {
+  if (!s || typeof s !== 'object' || Array.isArray(s)) return 'not an object';
+  if (!s.workspace || typeof s.workspace !== 'object') return 'missing workspace';
+  for (const k of ['seq', 'msgSeq', 'taskSeq']) if (typeof s[k] !== 'number') return `missing numeric ${k}`;
+  for (const k of ['agents', 'messages', 'tasks', 'events']) if (!Array.isArray(s[k])) return `missing array ${k}`;
+  if (!s.files || typeof s.files !== 'object' || Array.isArray(s.files)) return 'missing files object';
+  return null;
+}
+
+export async function createBus(store, workspace, opts = {}) {
+  const bus = new GhostBus(store, workspace, opts);
+  await bus.init();
+  return bus;
+}