ghostbus 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.5.2 — 2026-10-11
+
+Security hardening — the pre-pilot pass. A cold source review scored GhostBus 7.4/10 with security maturity its lowest mark (5.5/10, "authentication enforcement and deployment hardening need attention"). That was the right call to answer before any hosted workspace carries a stranger's work — or their money:
+
+- **Hosted: per-agent token enforcement is now the DEFAULT** (`src/hosted-server.mjs`) — every workspace bus is created with enforcement on, no env var needed. The only opt-out is an explicit `GHOSTBUS_REQUIRE_TOKENS=0`, and using it prints a loud three-line stderr warning at startup (with enforcement off, anyone holding a workspace key can act under any agent name). Header comment updated to match.
+- **Hosted: admin-key floor** — the hosted server already refused to start without `GHOSTBUS_ADMIN_KEY`; it now also refuses keys shorter than 16 characters (exit 2). The admin key is operator root (creates/deletes workspaces, master key inside all of them) and gets a floor to match. Storage/rotation guidance (root-only file, chmod 600, rotate by restart) is documented in `docs/hosted.md`.
+- **Single relay: exposure is never silent** (`src/http-server.mjs`) — Node's `listen()` binds all network interfaces, not just loopback. Starting the relay without `GHOSTBUS_KEY` now prints a loud warning saying exactly that; with a key but token enforcement off, a one-line warning names the impersonation trade-off. Semantics unchanged: local trust is still the relay's default model.
+- **Docs** — new "Security & deployment hardening" section in `docs/hosted.md`: enforcement default + opt-out, HTTPS REQUIRED for any public deployment (reverse proxy or a *named* Cloudflare Tunnel; a quick tunnel is explicitly not for paid use), admin-key storage/rotation, per-workspace key handling, scheduled export backups. README hosted section points at it.
+- **Tests** — the two existing hosted checks now present the tokens issued at registration (they exercise the enforced path, as real clients now must), and four new checks cover the pass: default-on enforcement over real HTTP (no token → 400, wrong token → 400, issued token → 200, header and body forms), the `=0` opt-out + its startup warning, the short-admin-key refusal, and the relay's no-key warning. All four fail against the 0.5.1 servers (47 passed, 4 failed) and pass with the change.
+- **Scope boundary, honestly** — what did NOT change: core bus behavior, the local stdio/CLI trust model (tokens stay opt-in there via `GHOSTBUS_REQUIRE_TOKENS=1`), the single relay's opt-in posture beyond the new warnings, storage (memory/JSON file; a networked multi-writer store is still future work, not faked here), and the serverless pack (its `GHOSTBUS_REQUIRE_TOKENS` env remains opt-in). The hosted `open` surfaces — board page, `/health`, `/probe` — were audited, not changed: every workspace is always created with a key and no data route bypasses it; the three open paths serve the static board shell, liveness, and counts-only probe data, the same posture as the single relay, and are documented as such.
+- 51 checks in the main suite (was 47) + 6 serverless, all passing; both demos green.
+
+## 0.5.1 — 2026-10-09
+
+Reliability fix — the operation-level race above the v0.4.1 FileStore fix:
+
+- **Per-Bus mutation mutex** — every public operation on a `GhostBus` (register/heartbeat, message send, task create/claim/complete/comment, file put/delete, capsule/context writes, token ops, snapshot restore, and reads) now runs its whole load → mutate → save cycle inside a per-instance promise-chain mutex (`_serialized` in src/core.mjs), made reentrant via AsyncLocalStorage so operations that call other operations (updateCapsule → getCapsule, restore → status) can't self-deadlock. Before this fix, concurrent calls on ONE bus instance interleaved their cycles against the shared store and silently lost each other's updates: a 4-writer × 12-round probe through the public Bus API ended with one writer's file stuck at an early round and another's missing entirely, with zero errors reported. A throwing operation still releases the chain (try/finally), so one failure can never wedge the bus. Public API and behavior are unchanged.
+- **Scope boundary, honestly** — the mutex serializes operations within one Bus instance in one process. It is not a distributed lock: separate processes sharing one store file still coordinate only at single-operation granularity (each op remains an atomic read-modify-write with the v0.4.1 temp-file fix), and the serverless pack (deploy/netlify) builds a fresh bus per request over an external KV, so cross-invocation interleavings there remain bounded by the KV layer, not by this mutex.
+- **Regression tests in the main suite** — three new checks: concurrent writers lose no updates (4 writers × 12 rounds, verified on disk via a fresh instance), concurrent mixed ops (tasks + messages + files at once) all land with unique task ids, and a throwing operation releases the mutex (with a wedge timeout). All three fail on the pre-fix core (44 passed, 3 failed) and pass with the fix.
+- 47 checks in the main suite (was 44) + 6 serverless, all passing; both demos green.
+
 ## 0.5.0 — 2026-10-08
 
 The operator release — running a hosted bus day-to-day:

package/PLAN.md

@@ -1,6 +1,6 @@
 # GhostBus — Agent-to-Agent Message Bus / Shared Workspace MCP
 
-**Status:** PUBLISHED — v0.5.0 live Oct 8, 2026 (github.com/littlestjames82-sys/ghostbus). v0.5.0 is the operator release: hosted workspace key rotation (old key dies immediately), full-state export/import for backup + host migration (fresh key on import, keys never inside exports), core snapshot/restore + CLI export/import, and the FileStore race regression test in the main suite — 44/44 + 6/6. v0.4.0 added the hosted multi-workspace server + Docker + Netlify serverless pack (41/41 + 6/6 tests). v0.4.1 fixed the FileStore temp-file race (unique temp per save + serialized saves; stress 0 failures vs 59/60 failing before), shipped the docker-compose + one-shot VPS setup assets, and passed a full hosted smoke test. Still not deployed to a public host — that waits on Ryan's VPS choice. npm: name `ghostbus` verified available; publish rides the Trusted-Publishing workflow after Ryan's one-time npm setup (see LAUNCH.md).
+**Status:** PUBLISHED — v0.5.1 live Oct 9, 2026 (github.com/littlestjames82-sys/ghostbus). v0.5.1 is a reliability patch: a per-Bus mutation mutex in the core serializes every operation's load → mutate → save cycle, closing the silent lost-update race under concurrent writers on one bus instance — 47/47 + 6/6 with three new concurrency regression checks (all red on the pre-fix core). v0.5.0 is the operator release: hosted workspace key rotation (old key dies immediately), full-state export/import for backup + host migration (fresh key on import, keys never inside exports), core snapshot/restore + CLI export/import, and the FileStore race regression test in the main suite — 44/44 + 6/6. v0.4.0 added the hosted multi-workspace server + Docker + Netlify serverless pack (41/41 + 6/6 tests). v0.4.1 fixed the FileStore temp-file race (unique temp per save + serialized saves; stress 0 failures vs 59/60 failing before), shipped the docker-compose + one-shot VPS setup assets, and passed a full hosted smoke test. Still not deployed to a public host — that waits on Ryan's VPS choice. npm: name `ghostbus` verified available; publish rides the Trusted-Publishing workflow after Ryan's one-time npm setup (see LAUNCH.md).
 **Origin:** Generalizes Ghost Bridge (Ryan's private Muse ↔ Antigravity relay, Level 3, live since Oct 6) into a standalone product any agents can join. Ghost Bridge stays private; GhostBus is the clean, general version — same proven patterns, no Ryan-specific context, no studio data in the box.
 
 ## The problem (one line)

package/README.md

@@ -6,12 +6,24 @@ Agents today work alone in separate windows — when two of them need to coopera
 
 Zero dependencies. Node 18+. MIT.
 
+## Install
+
+```bash
+npm install ghostbus
+```
+
+GhostBus is published on npm as [`ghostbus`](https://www.npmjs.com/package/ghostbus) (v0.5.0) — zero dependencies, Node 18+. You can also run it straight from a clone of this repository, as the quick start below shows.
+
+## Status
+
+Built and in use: 29 MCP tools across presence, messages, tasks, a shared workspace, and a provenance log; local stdio servers, an HTTP relay, and a hosted multi-workspace server are all included in this repo, along with a live web board, SSE event pushes, per-agent tokens, and a terminal CLI. See `CHANGELOG.md` for release history and `docs/` for the client setup and hosted-operator guides.
+
 ## Quick start
 
 ```bash
-git clone <this repo> ghostbus && cd ghostbus
+git clone https://github.com/littlestjames82-sys/ghostbus.git ghostbus && cd ghostbus
 node examples/two-agent-demo.mjs   # watch a planner and a builder cooperate
-node test.mjs                      # 40 checks: core, tokens, capsules, dependencies, sync, persistence, MCP stdio, HTTP, SSE, CLI
+node test.mjs                      # 51 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security
 node examples/three-agent-team.mjs # planner + builder + reviewer, no human relaying
 ```
 
@@ -46,6 +58,8 @@ GHOSTBUS_ADMIN_KEY=pick-a-long-secret node src/hosted-server.mjs --port 8388
 
 One process serves many **isolated** workspaces under `/w/<id>/` — each with its own key (issued once at creation, hash-only in the registry), board, REST, MCP, SSE and probe. The admin API creates/lists/deletes workspaces, **rotates keys** (old key dies instantly), and **exports/imports** full workspace state for backup and host migration — imports always mint a fresh key. A Dockerfile and a serverless Netlify/Blobs pack are included. Operator guide: `docs/hosted.md`.
 
+Hosted mode is the deployment that serves strangers, so it is hardened by default (v0.5.2): per-agent tokens are **enforced** in every workspace (`GHOSTBUS_REQUIRE_TOKENS=0` opts out, loudly), the admin key must be at least 16 characters, and any public deployment belongs behind HTTPS. Details: the "Security & deployment hardening" section of `docs/hosted.md`.
+
 Same tools over `POST /mcp`, plus a REST mirror under `/api/*`. `/health` and a counts-only `/probe` stay open for monitoring and wake hooks. A **live web board** is served at `/`, and agents can subscribe to **pushed events** over SSE (`GET /api/stream?agent=<name>`) instead of polling. Set `GHOSTBUS_REQUIRE_TOKENS=1` to enforce the per-agent tokens issued at registration. There's also a terminal CLI (`src/cli.mjs`) and full client setup docs in `docs/client-setup.md`.
 
 ## The 29 tools
@@ -77,6 +91,19 @@ Same tools over `POST /mcp`, plus a REST mirror under `/api/*`. `/health` and a
 
 GhostBus generalizes a private relay that has run in production for one studio's own agents since Oct 2026 (task handoffs, shared project capsules, a live board). This is the clean, general version of that proven pattern. Built by Ghost Developer Studio.
 
+## From Ghost Developer Studio
+
+GhostBus is one part of the studio's agent-infrastructure family:
+
+- **Visual roadmap board** — where every studio product stands, in one picture: [ghost-roadmaps](https://github.com/littlestjames82-sys/ghost-roadmaps)
+- **GhostGuard** — the governance layer for autonomous systems: [ghostguard](https://github.com/littlestjames82-sys/ghostguard)
+- **Ghost Bridge** — MCP bridge + self-hostable relay for handing tasks to a personal agent, with scoped keys and approvals: [ghost-bridge](https://github.com/littlestjames82-sys/ghost-bridge)
+- **Ghost Hands** — governed, recorded, replayable agent hands for the web: [ghost-hands](https://github.com/littlestjames82-sys/ghost-hands)
+- **Agent Seatbelt** — deterministic guardrails that gate what an AI coding agent does before it does it: [agent-seatbelt](https://github.com/littlestjames82-sys/agent-seatbelt)
+- **Ghost Developer Studio storefront** — [storefront](https://github.com/littlestjames82-sys/storefront)
+
+Built in public by Ryan Cotten / Ghost Developer Studio.
+
 ## License
 
 MIT — see `LICENSE`.

package/docs/hosted.md

@@ -53,20 +53,65 @@ Everything from the single-workspace relay works under the prefix:
 
 - Board: `https://host/w/acme/` (asks for the workspace key in-page)
 - REST: `https://host/w/acme/api/*` with header `x-bus-key: <workspace key>`
-- MCP: `POST https://host/w/acme/mcp` (same header; plus `x-agent-token` when token mode is on)
+- MCP: `POST https://host/w/acme/mcp` (same header; plus `x-agent-token` — per-agent token enforcement is ON by default in hosted mode, see below)
 - Probe (open, counts only): `GET https://host/w/acme/probe`
 - Push: SSE at `/w/acme/api/stream?agent=…`, long-poll at `/w/acme/api/wait?agent=…`
 
 The admin key also works as a master key inside any workspace — treat it like root: operators only, never hand it to agents.
 
-Set `GHOSTBUS_REQUIRE_TOKENS=1` to enforce per-agent tokens in every workspace, exactly as on the single relay.
+## Security & deployment hardening
+
+The hosted server is the one GhostBus deployment that serves people other than
+the operator, so its defaults are stricter than the local relay's (v0.5.2):
+
+- **Per-agent tokens are enforced by default** in every workspace: an agent
+  registers once, receives its token once, and must present it
+  (`x-agent-token` header or `token` field) for every act. A stolen agent
+  *name* alone cannot impersonate it. `GHOSTBUS_REQUIRE_TOKENS=0` is the only
+  opt-out — the server prints a loud startup warning when it is used, because
+  with enforcement off, anyone holding a workspace key can act under any
+  agent name. Don't disable it for a public or paid deployment.
+- **HTTPS is REQUIRED for any public deployment.** The server itself speaks
+  plain HTTP; terminate TLS in front of it — a reverse proxy with automatic
+  certificates (Caddy, nginx + certbot) or a **named** Cloudflare Tunnel with
+  a stable hostname. A Cloudflare *quick* tunnel (`trycloudflare.com`) is
+  fine for a demo and **not** for paid use: its URL changes on restart and it
+  carries no uptime expectation. Never expose the plain-HTTP port directly.
+- **Admin key hygiene.** The admin key is operator root: it creates and
+  deletes workspaces, rotates their keys, exports their state, and works as a
+  master key inside every workspace. The server refuses to start with a key
+  shorter than 16 characters; use 32+ random hex. Store it in a root-only
+  file, never in the repo, a ticket, or a chat log:
+  ```bash
+  head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' > /root/ghostbus-admin-key
+  chmod 600 /root/ghostbus-admin-key
+  GHOSTBUS_ADMIN_KEY=$(cat /root/ghostbus-admin-key) node src/hosted-server.mjs
+  ```
+  (The shipped `deploy/docker/vps-setup.sh` already generates it this way.)
+  To rotate the admin key, restart the server with a new one — existing
+  workspace keys are unaffected (they live in the registry as hashes, not
+  derived from the admin key).
+- **Per-workspace keys.** Each workspace key is shown exactly once, at
+  creation (or import); only its SHA-256 is stored. Hand it to that
+  workspace's owner over a secure channel, never publish it, and if one
+  leaks, rotate it — `POST /api/workspaces/<id>/rotate-key` kills the old
+  key immediately (see above).
+- **Backups are a schedule, not a feature.** The data dir *is* the state
+  (`registry.json` + one `<id>.json` per workspace), so back it up on a
+  timer, and per-workspace exports give you portable copies:
+  ```bash
+  # nightly, e.g. from cron — plus a plain copy of the data dir
+  curl -s localhost:8388/api/workspaces/acme/export -H 'x-bus-key: <admin>' > backups/acme-$(date +%F).json
+  ```
+  Drill a restore (delete + import) before you need one; a restore lands in
+  the workspace's provenance log as `workspace.restore`.
 
 ## Option B — serverless on Netlify (Blobs)
 
 `deploy/netlify/` contains a Netlify Function implementing the same multi-workspace semantics over Netlify Blobs (strong consistency):
 
 1. Create a Netlify site using `deploy/netlify/` as the site root (or copy `functions/` + `netlify.toml` into a site).
-2. Set site env: `GHOSTBUS_ADMIN_KEY` (required), optionally `GHOSTBUS_REQUIRE_TOKENS=1`.
+2. Set site env: `GHOSTBUS_ADMIN_KEY` (required), optionally `GHOSTBUS_REQUIRE_TOKENS=1`. (The serverless pack keeps token enforcement opt-in via this env; the Node hosted server above enforces by default since v0.5.2.)
 3. Add `@netlify/blobs` to that site's dependencies (`npm i @netlify/blobs` in the site root) and deploy.
 
 The routing, admin API, per-workspace keys, and REST/MCP surface match Option A, with two honest differences: **no board page, no SSE, no long-poll** (serverless invocations can't hold them) — agents poll `/w/<id>/probe` + inbox or use `bus_sync`. State per workspace is one Blobs entry, written per request from a fresh bus instance; concurrent writes to the *same* workspace can race (last writer wins a single operation), so very hot single-workspace traffic belongs on Option A.

package/package.json

@@ -44,5 +44,5 @@
     "hosted": "node src/hosted-server.mjs"
   },
   "type": "module",
-  "version": "0.5.0"
+  "version": "0.5.2"
 }

package/src/core.mjs

@@ -12,8 +12,9 @@
 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.0';
+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;
@@ -82,12 +83,44 @@ export class GhostBus {
     // 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() {
+  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
@@ -136,7 +169,8 @@ export class GhostBus {
   }
 
   // ---------- agents ----------
-  async registerAgent({ name, role = '', capabilities = [], token = null }) {
+  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();
@@ -163,7 +197,8 @@ export class GhostBus {
     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({ name, token = null }) {
+  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');
@@ -173,16 +208,19 @@ export class GhostBus {
     return { agent: this._publicAgent(a), token: rawToken, tokenNote: 'New token — the old one no longer works. Shown once.' };
   }
 
-  async heartbeat({ name, token = null }) {
+  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() { await this.init(); return this.state.agents.map(a => this._publicAgent(a)); }
+  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({ from, to = '*', body, channel = 'general', threadId = null, token = null }) {
+  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);
@@ -201,7 +239,8 @@ export class GhostBus {
   }
 
   /** Messages visible to `agent`: addressed to it, broadcast, or sent by it. Unread-first filtering optional. */
-  async inbox(agentName, { unreadOnly = false, limit = 50, markRead = true, token = null } = {}) {
+  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 =>
@@ -216,7 +255,8 @@ export class GhostBus {
     return clone(msgs);
   }
 
-  async thread(id) {
+  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}`);
@@ -224,7 +264,8 @@ export class GhostBus {
   }
 
   // ---------- tasks ----------
-  async createTask({ from, title, body = '', assignee = null, priority = 'normal', needsApproval = false, blockedBy = [], token = null }) {
+  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);
@@ -257,7 +298,8 @@ export class GhostBus {
     }
   }
 
-  async listTasks({ status = null, assignee = null } = {}) {
+  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;
@@ -266,7 +308,8 @@ export class GhostBus {
     return clone(tasks.sort((a, b) => b.id - a.id));
   }
 
-  async approveTask(id, { by, token = null }) {
+  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);
@@ -279,7 +322,8 @@ export class GhostBus {
   }
 
   /** Claim is exclusive: a second claim while a lease is live fails loudly. */
-  async claimTask(id, { by, token = null }) {
+  async claimTask(...args) { return this._serialized(() => this._claimTask(...args)); }
+  async _claimTask(id, { by, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     this._expireClaims();
@@ -298,7 +342,8 @@ export class GhostBus {
     return clone(task);
   }
 
-  async completeTask(id, { by, result = '', token = null }) {
+  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);
@@ -311,7 +356,8 @@ export class GhostBus {
     return clone(task);
   }
 
-  async cancelTask(id, { by, token = null }) {
+  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);
@@ -330,7 +376,8 @@ export class GhostBus {
   }
 
   // ---------- shared workspace: files + context + board ----------
-  async putFile({ by, path: p, text, token = null }) {
+  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');
@@ -343,7 +390,8 @@ export class GhostBus {
     return { path: p, bytes: Buffer.byteLength(text) };
   }
 
-  async getFile(p, { withHistory = false } = {}) {
+  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}`);
@@ -351,19 +399,22 @@ export class GhostBus {
     return { path: p, ...clone(rest), versions: (history || []).length + 1, ...(withHistory ? { history: clone(history || []) } : {}) };
   }
 
-  async fileHistory(p) {
+  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() {
+  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({ by, context, token = null }) {
+  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');
@@ -373,13 +424,15 @@ export class GhostBus {
     return { ok: true };
   }
 
-  async getContext() {
+  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(id, { by, body, token = null }) {
+  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');
@@ -394,7 +447,8 @@ export class GhostBus {
     return clone(task);
   }
 
-  async deleteFile({ by, path: p, token = null }) {
+  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}`);
@@ -404,7 +458,8 @@ export class GhostBus {
     return { path: p, deleted: true };
   }
 
-  async listChannels() {
+  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;
@@ -412,7 +467,8 @@ export class GhostBus {
   }
 
   /** Full-text search across messages, tasks, and shared files. */
-  async search(query, { limit = 20 } = {}) {
+  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');
@@ -437,7 +493,8 @@ export class GhostBus {
   }
 
   /** Read a project capsule, creating it from the template on first touch when create=true. */
-  async getCapsule(slug, { create = false, title = '', by = null, token = null } = {}) {
+  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]) {
@@ -451,7 +508,8 @@ export class GhostBus {
   }
 
   /** Replace one capsule section (State / Decisions / Next) or append to the Session log. */
-  async updateCapsule(slug, { by, section, text, token = null }) {
+  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 });
@@ -477,13 +535,15 @@ export class GhostBus {
     return this.getFile(pth);
   }
 
-  async listCapsules() {
+  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() {
+  async board(...args) { return this._serialized(() => this._board(...args)); }
+  async _board() {
     await this.init();
     this._expireClaims();
     const s = this.state;
@@ -511,18 +571,21 @@ export class GhostBus {
 
   /** 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({ sinceSeq = 0, limit = 500 } = {}) {
+  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({ limit = 50 } = {}) {
+  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() {
+  async status(...args) { return this._serialized(() => this._status(...args)); }
+  async _status() {
     await this.init();
     this._expireClaims();
     const s = this.state;
@@ -540,7 +603,8 @@ export class GhostBus {
   /** 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() {
+  async snapshot(...args) { return this._serialized(() => this._snapshot(...args)); }
+  async _snapshot() {
     await this.init();
     return clone(this.state);
   }
@@ -549,7 +613,8 @@ export class GhostBus {
    *  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(snapshot, { by = 'operator' } = {}) {
+  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' });

package/src/hosted-server.mjs

@@ -18,7 +18,11 @@
  *     GET    /api/workspaces/<id>/export   -> full-state export envelope (backup/migrate)
  *     POST   /api/workspaces/import {id?, name?, state|export} -> {id, name, key (once)}
  * - Registry + one data file per workspace live in the data dir.
- *   Set GHOSTBUS_REQUIRE_TOKENS=1 to enforce per-agent tokens in all workspaces.
+ * - Per-agent tokens are ENFORCED in all workspaces by default (v0.5.2):
+ *   hosted mode serves strangers, so a stolen agent name must not be enough
+ *   to act. GHOSTBUS_REQUIRE_TOKENS=0 is the only opt-out and starts with a
+ *   loud warning. GHOSTBUS_ADMIN_KEY is required and must be at least 16
+ *   characters — it is the operator root key (see docs/hosted.md).
  */
 import http from 'node:http';
 import fs from 'node:fs';
@@ -32,12 +36,25 @@ const argVal = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i
 const port = Number(argVal('--port') || process.env.GHOSTBUS_PORT || 8388);
 const dataDir = argVal('--data-dir') || process.env.GHOSTBUS_DATA_DIR || './ghostbus-hosted';
 const ADMIN_KEY = process.env.GHOSTBUS_ADMIN_KEY || '';
-const REQUIRE_TOKENS = process.env.GHOSTBUS_REQUIRE_TOKENS === '1';
+// v0.5.2: enforcement is the hosted DEFAULT. Only an explicit
+// GHOSTBUS_REQUIRE_TOKENS=0 turns it off (anything else, including unset,
+// means on) — the hosted server is the one deployment that serves people
+// other than the operator, so the safe posture cannot be opt-in.
+const REQUIRE_TOKENS = process.env.GHOSTBUS_REQUIRE_TOKENS !== '0';
 
 if (!ADMIN_KEY) {
   process.stderr.write('GHOSTBUS_ADMIN_KEY is required for the hosted server (workspace creation must not be open).\n');
   process.exit(2);
 }
+if (ADMIN_KEY.length < 16) {
+  process.stderr.write('GHOSTBUS_ADMIN_KEY is too short: use at least 16 characters (32+ random hex recommended). The admin key is the operator root key — it creates/deletes workspaces and acts as a master key inside every one of them.\n');
+  process.exit(2);
+}
+if (!REQUIRE_TOKENS) {
+  process.stderr.write('WARNING: GHOSTBUS_REQUIRE_TOKENS=0 — per-agent token enforcement is DISABLED in every workspace.\n');
+  process.stderr.write('WARNING: anyone holding a workspace key can act under ANY agent name in that workspace (impersonation).\n');
+  process.stderr.write('WARNING: hosted mode serves strangers; run with enforcement on unless you have a specific reason not to.\n');
+}
 
 fs.mkdirSync(dataDir, { recursive: true });
 const registryPath = path.join(dataDir, 'registry.json');

package/src/http-server.mjs

@@ -23,8 +23,9 @@ const storePath = argVal('--store') || process.env.GHOSTBUS_STORE || './ghostbus
 const wsName = argVal('--name') || process.env.GHOSTBUS_WORKSPACE_NAME || 'GhostBus Workspace';
 const KEY = process.env.GHOSTBUS_KEY || '';
 
+const REQUIRE_TOKENS = process.env.GHOSTBUS_REQUIRE_TOKENS === '1';
 const store = storePath === ':memory:' ? new MemoryStore() : new FileStore(storePath);
-const bus = await createBus(store, { name: wsName }, { requireTokens: process.env.GHOSTBUS_REQUIRE_TOKENS === '1' });
+const bus = await createBus(store, { name: wsName }, { requireTokens: REQUIRE_TOKENS });
 const handle = createBusHandler({ id: 'default', bus, key: KEY });
 
 const server = http.createServer((req, res) => {
@@ -33,4 +34,14 @@ const server = http.createServer((req, res) => {
 });
 server.listen(port, () => {
   process.stderr.write(`ghostbus http relay v${GHOSTBUS_VERSION} · http://127.0.0.1:${port} · store=${storePath} · auth=${KEY ? 'workspace key required' : 'open (set GHOSTBUS_KEY)'}\n`);
+  // Node's listen() with no host binds ALL network interfaces, not just
+  // loopback — the 127.0.0.1 above is the local URL, not a bind restriction.
+  // Local trust is the relay's default model and stays unchanged, but an
+  // unkeyed or tokenless relay must never be network-reachable *silently*.
+  if (!KEY) {
+    process.stderr.write('WARNING: GHOSTBUS_KEY is not set — this relay is OPEN: anyone who can reach this port can read and write the workspace.\n');
+    process.stderr.write('WARNING: the relay listens on all network interfaces, not just localhost. Set GHOSTBUS_KEY (a long secret) before exposing it beyond this machine, or firewall the port.\n');
+  } else if (!REQUIRE_TOKENS) {
+    process.stderr.write('WARNING: per-agent tokens are not enforced (GHOSTBUS_REQUIRE_TOKENS is not 1): anyone holding the workspace key can act under any agent name. The relay listens on all network interfaces — set GHOSTBUS_REQUIRE_TOKENS=1 if untrusted agents share the key.\n');
+  }
 });