ghostbus 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.5.6 — 2026-10-11
+
+Security hardening, round 5 — load & abuse resilience: what happens when many agents share one process for a long time. This round built the first repeatable load bench before changing anything, and the honest headline is that load broke no correctness property — zero errors, zero lost writes, exact reconciliation at every size. What it (and the audit around it) found instead: an unbounded subscription surface, missing server timeouts whose platform defaults do not do what their names suggest, and a measured, structural scaling limit that is now documented instead of discovered by operators.
+
+- **Load bench (`scripts/load-bench.mjs`, new)** — boots the real hosted server with per-agent tokens enforced and drives N agents through mixed operations (register, heartbeat, send, inbox, task create→claim→complete, file put), reporting ops, errors, and p50/p95 latency per op class, plus a hard reconciliation: messages sent == messages stored, tasks created == tasks completed, files put == files stored. Baseline on the development machine (Node 24): **25 agents × 30 s → 2,506 ops, ~83 ops/s, 0 errors**, p50 ~280–360 ms / p95 ~390–595 ms per op class, reconciled exactly (650 messages, 300/300 tasks, 300 files); **25 agents × 60 s → 3,438 ops, ~57 ops/s, 0 errors**, also exact. Repeat 30 s runs on this shared VM varied between ~55 and ~112 ops/s with machine load; the invariants across every run were 0 errors and exact reconciliation. A reduced smoke (6 agents × 3 s) runs in the suite. One bench disclosure: at the shipped 300 req/min per-IP limiter, a single-IP bench measures the limiter, not the bus, so the bench raises that one knob for itself (printed in its output); every other limit is at its shipped default.
+- **What the load actually showed** — throughput declines as a workspace's state grows (~83 → ~57 ops/s across the captured 30 s/60 s pair as the state file grew ~0.9 → ~1.2 MB, p95 latency roughly doubling) because every operation loads and re-saves the whole state file (O(state) per op) and all operations serialize on the per-workspace lock: with 25 agents queued, most of the p50 is queue wait. Memory plateaued (RSS oscillated in a ~140–260 MB band under sustained load — garbage collection keeping up with per-op state copies), it did not grow with op count. No fix is claimed for the scaling shape: it is the single-file store's documented trade-off, now with numbers, in `docs/hosted.md` ("Capacity & limits"). Trims (10k messages / 5k events / per-file history) held throughout.
+- **SSE subscriptions were unbounded (fixed)** — before this round, any number of `/api/stream` connections could be held per workspace, each one a permanent bus listener plus a 25 s ping timer, reaped only on socket close. There are now caps, checked before the stream opens: **100 per workspace** (`GHOSTBUS_MAX_STREAMS_PER_WORKSPACE`) and **1000 per server** (`GHOSTBUS_MAX_STREAMS_TOTAL`), with a clean `429` JSON refusal over the cap. Cleanup is now idempotent across close/error/write-failure paths, and the suite proves the cap, that a freed slot reopens, and that bus listener counts return to exactly zero after stream churn — no listener leaks.
+- **Explicit server timeouts on both servers** — slow-loris room is closed. Both HTTP servers now take commented deadlines (defaults: headers 10 s, request body 30 s, keep-alive 5 s; overridable via `GHOSTBUS_HEADERS_TIMEOUT_MS` / `GHOSTBUS_REQUEST_TIMEOUT_MS`). The implementation notes are in the code because the platform defaults mislead: Node's own header enforcement was probed to leave a partial-headers socket alive past 15 s in this configuration, and its `requestTimeout` semantics proved unsafe to reason about for long-lived responses, so that property is pinned to 0 and both deadlines are enforced by a small connection-level guard that only ever destroys a socket whose request is genuinely incomplete. The guard's first cut armed its body timer on `req.complete` — which stays false for a bodyless GET nobody reads, exactly the `/api/stream` shape — and killed live streams in testing; the shipped guard arms only on a *declared* body (Content-Length / Transfer-Encoding). The suite proves all of it at tightened deadlines (400 ms / 800 ms): a partial-headers socket dies at the header deadline, a slow body drip dies at the body deadline, and an SSE stream plus a 2 s long-poll outlive both.
+- **Recovery drill (new suite proof)** — while three agents write against a hosted FileStore workspace, the server is SIGKILLed mid-load and restarted on the same data directory. Assertions: the state file parses (temp-file + atomic rename means a kill strands at most an inert `.tmp`), every operation already answered HTTP 200 is present after restart, each agent's stored messages form a contiguous prefix of its attempts (nothing half-applied), acked files are present, and the restarted server's counts agree with the file. This is the durability claim for the JSON store, stated at its true scope: single file, one writer process, last-writer semantics per op.
+- **Long-poll pile-up (new suite proof)** — 25 concurrent `/api/wait` holders all wake with the event on a single broadcast (none hang, none miss it), and 10 idle waits all resolve on their own timeout with `waited: true` and no events, with no unhandled rejections in the server log.
+- **Limiter hygiene** — the per-IP/workspace rate limiter is now tunable (`GHOSTBUS_RATE_LIMIT_PER_MIN`, default unchanged at 300) and its over-limit message reports the live value; the limiter map and the hosted failed-auth map prune stale buckets opportunistically instead of only ever growing under address churn.
+- **Tests** — five new checks (69 in the main suite, was 64): bench smoke with exact reconciliation, server timeouts (loris + drip + SSE/long-poll survival), SSE caps + reaping, wait pile-up, and the SIGKILL recovery drill. The suite now takes ~22 s because three of the new checks are real-time proofs (a 3 s bench window, a 2 s long-poll, a 1.2 s kill drill) — that time is the evidence, not overhead. Serverless stays 6/6 and both demos pass.
+- **Scope boundary, honestly** — what did NOT change: the storage format and every API shape are untouched; the local trust model is untouched; the bench figures are one machine's evidence, not a hosted SLA; and the networked multi-writer store remains future work — this round measured the single-file store's limits rather than relitigating them.
+
+## 0.5.5 — 2026-10-11
+
+Security hardening, round 4 — the client side of the wire. Rounds 2–3 hardened what the server stores and how it authenticates; this round fuzzed what a client can *send*: MCP tool arguments over stdio JSON-RPC, board payloads end-to-end, and raw HTTP parameters. One real crash, a class of silent state corruption, and a set of numeric edge cases were found and fixed. Several surfaces audited clean and are now pinned by tests instead — the entry says which, as usual.
+
+- **A single `null` line crashed the MCP server (fixed)** — `src/mcp-server.mjs` destructured every parsed line; a client (or a prompt-injected agent driving one) that sent a bare `null`, a string, a number, or an array killed the process with an unhandled TypeError, taking the bus down for every connected agent. Non-object frames are now ignored, and message handling is wrapped so one bad message can never be fatal. Verified: the pre-fix server exits with code 1 on the first hostile line; the fixed server drops all of them and keeps answering.
+- **Tool arguments are validated against their schemas (`src/tools.mjs`)** — the tools layer passed argument values straight into the core, which coerced: a message body sent as an object was *stored* as the literal string `"[object Object]"`, a body sent as an array as its first character, a numeric file path became a state key of the same number, a `threadId` sent as an object landed in memory as `NaN` (invisible until reload, when JSON rewrote it to `null`), and a null capsule slug created a capsule named `"null"`. One shared validator now runs before dispatch: required arguments must be present, declared types are enforced (strings stay strings, numbers must be finite, arrays and plain objects must be arrays and plain objects), and violations return the suite's existing clean error results. Arguments the schema doesn't declare (the optional per-agent `token`, for one) pass through untouched.
+- **Numeric parameters are clamped in the core** — the list/sync reads trusted their numbers: `limit=0` returned *every* message (slice(-0)), `limit=-1` returned all-but-one, events the same, and a garbage `sinceSeq` cursor made `bus_sync` report an agent as caught up (`truncated: false`) while replaying nothing. Limits now clamp (≤0 → none, absurd → the documented 500 cap, non-finite → the default page size) and a garbage cursor replays honestly from the start. Message thread ids are sanitized the same way — a non-numeric `threadId` is stored as `null`, never `NaN`.
+- **`/api/wait` never waits on a garbage timeout (fixed)** — `timeout=abc` made the long-poll reply instantly with an empty inbox and `waited: true`. A non-numeric or negative timeout now means the 25 s default; real values still clamp to [0, 55] s.
+- **Board task ids escape too** — the one board interpolation not routed through `esc()` was the task id in two templates. Ids are numbers from the core, so it was unreachable in normal operation, but a hand-crafted imported snapshot could put a string there; it goes through `esc()` now like everything else.
+- **Audited, already safe — now pinned by tests.** Board data path: hostile roles, message bodies, task titles, and file names seeded through the real API come back verbatim as JSON (inert by content type), every interpolated field is escaped, and the workspace key lives in local storage and travels as a header — never in a URL. `/probe` and `/health` return exactly their documented counts-only shapes. HTTP edges: method mismatches, trailing slashes, unknown routes, and URL-encoded traversal in workspace segments (`%2e%2e%2f`) all return clean 404s; a traversal-looking file path is an inert key miss (400), never a filesystem read. CLI: missing arguments, unknown commands, and bad values already exit non-zero with one-line errors and no stack dumps — pinned as-is. Prototype pollution through tool arguments: not reachable (JSON clone discipline), canary-checked in the fuzz.
+- **Tests** — five new checks (64 in the main suite, was 59): tools-boundary validation + core clamps (including that rejected calls store nothing), a bounded stdio fuzz (hostile raw frames, one wrong-typed variant for every declared property of all 29 tools, a 100 KB body, a 300-deep nested context, then bus-integrity assertions), the board data path, HTTP parameter edges on relay + hosted, and the CLI pins. Against the 0.5.4 code the new checks fail on the crash, the coercions, and the numeric semantics; with the change the full suite is green, serverless stays 6/6, and both demos pass.
+- **Scope boundary, honestly** — what did NOT change: no tool, route, or CLI behavior changes for well-formed input (valid calls produce identical results; the fuzz asserts registered-agent counts and a normal round-trip after the battery); argument validation rejects only values the schemas never allowed; the deferred networked multi-writer store is still future work.
+
 ## 0.5.4 — 2026-10-11
 
 Security hardening, round 3 — hostile input: the values a malicious (or merely buggy) client controls, followed to the filesystem, the object graph, and state validation. Audit-first as usual: two of the five surfaces turned out to be already safe, and the entry says which and why rather than dressing them up as fixes.

package/README.md

@@ -23,7 +23,7 @@ Built and in use: 29 MCP tools across presence, messages, tasks, a shared worksp
 ```bash
 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                      # 59 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security, hostile input
+node test.mjs                      # 69 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security, hostile input, input fuzz, load & resilience
 node examples/three-agent-team.mjs # planner + builder + reviewer, no human relaying
 ```
 

package/docs/hosted.md

@@ -165,6 +165,91 @@ validation:
   codebase, and the suite carries canary checks that try anyway through
   the context writer and restore payloads.
 
+Round 4 (v0.5.5) treated the clients themselves as untrusted input —
+including MCP clients and any agent driving one:
+
+- **MCP clients are untrusted input — say it plainly.** A client (or a
+  prompt-injected agent behind one) can send any argument shapes it wants.
+  Tool arguments are validated against each tool's declared schema at the
+  tools boundary: wrong-typed or non-finite values are rejected with a
+  clean error result, never coerced into shared state, and a malformed
+  JSON-RPC frame can no longer kill the stdio server process — bad frames
+  are dropped, the bus keeps serving every other agent.
+- **Numeric parameters are clamped everywhere.** Query and argument
+  numbers (`limit`, `sinceSeq`, timeouts) that arrive as garbage,
+  negatives, or absurd magnitudes fall back to defaults and documented
+  caps instead of slice-arithmetic surprises (a `limit` of 0 or -1 used
+  to return *more* data, and a garbage sync cursor falsely reported an
+  agent as caught up).
+- **The board's data path is pinned end-to-end.** Hostile roles, message
+  bodies, task titles, and file names are served verbatim as JSON data
+  (inert by content type), the page routes every interpolated field
+  through its HTML escaper, and the workspace key lives in local storage
+  and travels as a header — never in a URL, where it would land in logs
+  and referers. `/health` and `/probe` return exactly their documented
+  counts-only shapes.
+
+## Capacity & limits (measured, v0.5.6)
+
+First published load figures, from `scripts/load-bench.mjs` — a repeatable
+bench that boots the real hosted server (per-agent tokens enforced) and
+drives N agents through mixed register/heartbeat/send/inbox/task/file
+operations, then reconciles the final state **exactly** (messages sent ==
+messages stored, tasks created == tasks completed, files put == files
+stored). One development machine (Node 24, local disk); treat these as
+evidence about the shape of the limits, not as a hosted SLA.
+
+| run | ops | throughput | errors | latency (p50 / p95) |
+|---|---|---|---|---|
+| 25 agents × 30 s | 2,506 | ~83 ops/s | 0 | ~280–360 ms / ~390–595 ms per op class |
+| 25 agents × 60 s | 3,438 | ~57 ops/s | 0 | ~315–470 ms / ~910–1,870 ms per op class |
+
+Repeat runs vary with machine load — five 30 s runs on the shared
+development VM landed between ~55 and ~112 ops/s. What did not vary, in
+any run: **0 errors, and exact reconciliation.**
+
+What the numbers mean:
+
+- **Correctness holds under concurrency.** Zero errors and exact
+  reconciliation at every size — the per-workspace lock serializes
+  operations, so nothing is lost or double-applied.
+- **Throughput is bounded by design, and declines as a workspace grows.**
+  Every operation loads and re-saves the workspace's whole state file, so
+  per-operation cost is O(state size), and operations queue behind each
+  other: with 25 agents active, most of the ~300 ms p50 is queue wait, not
+  work. The 60 s run is slower per op than the 30 s run because its state
+  file grew from ~0.9 MB to ~1.2 MB during the run. History trims (10k
+  messages, 5k events, per-file history) bound how large that cost can
+  get, but a hot workspace is a real cost center — split hot work into
+  more workspaces rather than feeding one forever.
+- **Memory plateaus.** Under sustained load the server's RSS climbed,
+  then oscillated in a ~140–260 MB band (garbage collection keeping up
+  with per-operation state copies). It did not grow linearly with the
+  operation count; no leak was found.
+- **Durability under a hard kill is proven, not assumed.** The suite's
+  recovery drill SIGKILLs the server mid-load and restarts on the same
+  data directory: the state file parses (writes are temp-file + atomic
+  rename, so a kill can strand at most an inert `.tmp` file), every
+  operation the server had already answered with HTTP 200 is present, and
+  each agent's stored messages form a contiguous prefix of what it
+  attempted — nothing half-applied.
+
+Abuse limits an operator can tune (environment variables):
+
+| variable | default | meaning |
+|---|---|---|
+| `GHOSTBUS_MAX_STREAMS_PER_WORKSPACE` | 100 | concurrent `/api/stream` subscribers per workspace; over the cap → `429` |
+| `GHOSTBUS_MAX_STREAMS_TOTAL` | 1000 | concurrent streams across the whole server (hosted) |
+| `GHOSTBUS_HEADERS_TIMEOUT_MS` | 10000 | deadline for a client to deliver complete request headers |
+| `GHOSTBUS_REQUEST_TIMEOUT_MS` | 30000 | deadline to deliver a declared request body (never bounds a response — SSE and long-poll outlive it by design) |
+| `GHOSTBUS_RATE_LIMIT_PER_MIN` | 300 | per-IP, per-workspace request budget (the v0.4 limiter, now tunable) |
+
+When to scale out: one process serving a handful of team-sized workspaces
+is the design point. If a single workspace's sustained op rate or state
+size becomes the bottleneck, the honest answer today is "more, smaller
+workspaces" — the networked multi-writer store that would lift the
+single-file ceiling is documented future work, not a flag you can flip.
+
 ## Option B — serverless on Netlify (Blobs)
 
 `deploy/netlify/` contains a Netlify Function implementing the same multi-workspace semantics over Netlify Blobs (strong consistency):

package/package.json

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

package/src/board.html

@@ -64,7 +64,7 @@ async function refresh(){
       `<div class="agent"><strong>${esc(a.name)}</strong><span class="pill ${a.online?'green':''}">${a.online?'online':'away'}</span><br><span class="muted">${esc(a.role||'agent')}${a.capabilities?.length ? ' · ' + esc(a.capabilities.join(', ')) : ''} · last seen ${esc(a.lastSeenAt)}</span></div>`).join('') : '<span class="muted">none registered</span>';
     const open = tasks.tasks.filter(t => !['done','cancelled'].includes(t.status));
     $('tasks').innerHTML = open.length ? open.map(t =>
-      `<div class="task">#${t.id} <strong>${esc(t.title)}</strong><span class="pill ${t.status==='needs-approval'?'amber':''}">${esc(t.status)}</span><br><span class="muted">from ${esc(t.from)}${t.claimedBy ? ' · claimed by ' + esc(t.claimedBy) : ''}${t.assignee ? ' · for ' + esc(t.assignee) : ''}</span></div>`).join('') : '<span class="muted">queue is empty</span>';
+      `<div class="task">#${esc(t.id)} <strong>${esc(t.title)}</strong><span class="pill ${t.status==='needs-approval'?'amber':''}">${esc(t.status)}</span><br><span class="muted">from ${esc(t.from)}${t.claimedBy ? ' · claimed by ' + esc(t.claimedBy) : ''}${t.assignee ? ' · for ' + esc(t.assignee) : ''}</span></div>`).join('') : '<span class="muted">queue is empty</span>';
     $('files').innerHTML = files.files.length ? files.files.map(f =>
       `<div class="file">📄 ${esc(f.path)}<br><span class="muted">${f.bytes} bytes · ${esc(f.updatedBy)} · ${esc(f.updatedAt)}</span></div>`).join('') : '<span class="muted">no shared files</span>';
     $('events').innerHTML = events.events.slice().reverse().map(e =>

package/src/core.mjs

@@ -14,7 +14,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-export const GHOSTBUS_VERSION = '0.5.4';
+export const GHOSTBUS_VERSION = '0.5.6';
 const sha256 = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
 // Timing-safe equality for hex digests (v0.5.3): secret comparisons must not
 // short-circuit on the first differing character the way === does.
@@ -36,6 +36,19 @@ const RESERVED_FILE_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
 
 const now = () => new Date().toISOString();
 const clone = (v) => JSON.parse(JSON.stringify(v));
+// Untrusted numeric inputs (HTTP query params, MCP arguments, direct API
+// callers) arrive as NaN, negatives, and absurd magnitudes, and raw
+// slice(-n) arithmetic turns them into nonsense: limit=0 or NaN returned
+// EVERYTHING (slice(-0) / slice(NaN) both mean "from the start"), limit=-1
+// returned all-but-one (v0.5.5). Every list/read path clamps through here:
+// non-finite -> the default, fractional -> floored, out-of-range -> the
+// [0, max] bound; a clamped limit of 0 honestly means "return none".
+const clampLimit = (v, def, max) => {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return def;
+  return Math.max(0, Math.min(Math.floor(n), max));
+};
+const tailSlice = (arr, lim) => (lim > 0 ? arr.slice(-lim) : []);
 
 function emptyState(workspace = {}) {
   return {
@@ -245,9 +258,13 @@ export class GhostBus {
     if (to !== '*') this._existsAgent(to);
     if (!body || !String(body).trim()) throw new Error('message body required');
     this.state.msgSeq += 1;
+    // threadId names a message id; anything that isn't a positive finite
+    // number (an object used to land here as NaN, invisible to thread()
+    // until a reload quietly rewrote it to null) is simply "no thread".
+    const tid = Number(threadId);
     const msg = {
       id: this.state.msgSeq, from, to, channel: String(channel).slice(0, 64),
-      body: String(body), threadId: threadId ? Number(threadId) : null,
+      body: String(body), threadId: Number.isFinite(tid) && tid >= 1 ? Math.floor(tid) : null,
       createdAt: now(), readBy: [from],
     };
     this.state.messages.push(msg);
@@ -265,7 +282,7 @@ export class GhostBus {
     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));
+    msgs = tailSlice(msgs, clampLimit(limit, 50, 500));
     if (markRead) {
       let changed = false;
       for (const m of msgs) if (!m.readBy.includes(agentName)) { m.readBy.push(agentName); changed = true; }
@@ -399,7 +416,7 @@ export class GhostBus {
   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 (typeof p !== 'string' || !p || typeof text !== 'string') throw new Error('path and text required');
     if (String(p).includes('..')) throw new Error('path may not contain ..');
     if (RESERVED_FILE_NAMES.has(p)) throw new Error('path is a reserved name');
     const prev = this.state.files[p];
@@ -495,11 +512,12 @@ export class GhostBus {
     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);
+    const lim = clampLimit(limit, 20, 500);
     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)
+      messages: clone(tailSlice(this.state.messages.filter(m => hit(m.body)), lim)),
+      tasks: clone(tailSlice(this.state.tasks.filter(t => hit(t.title) || hit(t.body) || hit(t.result)), lim)),
+      files: Object.entries(this.state.files).filter(([p, f]) => hit(p) || hit(f.text)).slice(0, lim)
         .map(([p, f]) => ({ path: p, updatedBy: f.updatedBy, updatedAt: f.updatedAt, excerpt: f.text.slice(0, 200) })),
     };
   }
@@ -596,14 +614,20 @@ export class GhostBus {
   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) };
+    // A garbage cursor (NaN from a non-numeric query param) used to match
+    // NOTHING and report truncated:false — an offline agent would believe
+    // itself caught up while missing everything (v0.5.5). It now means
+    // what a missing cursor means: replay from the start, limit-bounded.
+    const since = Number.isFinite(Number(sinceSeq)) ? Math.max(0, Math.floor(Number(sinceSeq))) : 0;
+    const lim = clampLimit(limit, 500, 1000);
+    const evs = this.state.events.filter(e => e.seq > since);
+    return { events: clone(evs.slice(0, lim)), headSeq: this.state.seq, truncated: evs.length > lim };
   }
 
   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)));
+    return clone(tailSlice(this.state.events, clampLimit(limit, 50, 500)));
   }
 
   async status(...args) { return this._serialized(() => this._status(...args)); }

package/src/handler.mjs

@@ -75,16 +75,117 @@ export const HTML_SECURITY_HEADERS = {
 
 const TOO_LARGE = Symbol('body-too-large');
 
+// Per-IP request limiter (per workspace — one handler serves one workspace).
+// The default (300/min) is unchanged since v0.3; GHOSTBUS_RATE_LIMIT_PER_MIN
+// is an operator knob for two legitimate cases: many agents behind one NAT
+// address sharing a single source IP, and load benchmarking, where the
+// limiter — not the bus — would otherwise be the first ceiling (v0.5.6).
+const rateLimitPerMin = () => {
+  const n = Number(process.env.GHOSTBUS_RATE_LIMIT_PER_MIN);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : 300;
+};
+
+// Server timeouts (v0.5.6). Three different clocks, three different jobs:
+// - headersMs bounds how long a client may take to deliver complete request
+//   HEADERS (the classic slow-loris drip).
+// - requestMs bounds how long it may take to deliver the request BODY after
+//   that. It must never bound a response: /api/stream and /api/wait are
+//   long-lived BY DESIGN.
+// - keepAliveMs is Node's own idle keep-alive lifetime.
+// Why this is not just "set the three Node properties": Node's own
+// enforcement of both knobs was probed on Node 24 before this design was
+// chosen, and neither is a deterministic drop-in for the deadlines above.
+// - server.headersTimeout IS set (it only governs the header phase), but
+//   its enforcement rides on Node's socket-timeout machinery: with the
+//   default server.timeout of 0, a partial-headers socket was probed to
+//   survive 15 s at headersTimeout=1000.
+// - server.requestTimeout is pinned to 0: its semantics proved impossible
+//   to reason about safely for long-lived responses (a handler that
+//   writes constantly masks its clock entirely), and the deadline it is
+//   documented for — receiving the request — is exactly the one the
+//   guard below enforces deterministically instead.
+// The guard: arm the header deadline on connect, clear it when headers
+// land, bound a *declared* body from there, re-arm while the socket sits
+// between keep-alive requests. server.timeout stays 0 on purpose — socket
+// *inactivity* is not a deadline here, because a long-poll legitimately
+// idles for up to 55 s and an SSE stream between events for longer.
+export const SERVER_TIMEOUT_DEFAULTS = { headersMs: 10_000, requestMs: 30_000, keepAliveMs: 5_000 };
+export function applyServerTimeouts(server, opts = {}) {
+  const headersMs = opts.headersMs ?? SERVER_TIMEOUT_DEFAULTS.headersMs;
+  const requestMs = opts.requestMs ?? SERVER_TIMEOUT_DEFAULTS.requestMs;
+  const keepAliveMs = opts.keepAliveMs ?? SERVER_TIMEOUT_DEFAULTS.keepAliveMs;
+  server.headersTimeout = headersMs;
+  server.requestTimeout = 0; // see above — Node's clock kills live streams; the guard owns this deadline
+  server.keepAliveTimeout = keepAliveMs;
+  server.timeout = 0; // see above — inactivity is not the deadline
+  server.on('connection', (socket) => {
+    const armHeaderDeadline = () => {
+      clearTimeout(socket._gbHeaderTimer);
+      socket._gbHeaderTimer = setTimeout(() => socket.destroy(), headersMs);
+      socket._gbHeaderTimer.unref?.();
+    };
+    socket._gbArmHeaderDeadline = armHeaderDeadline;
+    armHeaderDeadline();
+    socket.on('close', () => clearTimeout(socket._gbHeaderTimer));
+  });
+  server.on('request', (req, res) => {
+    const socket = req.socket;
+    clearTimeout(socket._gbHeaderTimer); // headers are in — that deadline is met
+    clearTimeout(socket._gbBodyTimer);
+    // Bound the body ONLY when one was declared. req.complete cannot be
+    // the trigger: for a bodyless GET whose stream nobody reads (exactly
+    // the /api/stream and /api/wait shape) it stays false indefinitely, so
+    // a timer armed on it would destroy healthy long-lived exchanges —
+    // the first cut of this guard did precisely that to SSE streams.
+    const declaresBody = Number(req.headers['content-length'] || 0) > 0 || 'transfer-encoding' in req.headers;
+    if (declaresBody && !req.complete) {
+      socket._gbBodyTimer = setTimeout(() => socket.destroy(), requestMs);
+      socket._gbBodyTimer.unref?.();
+      const clear = () => clearTimeout(socket._gbBodyTimer);
+      req.on('end', clear);
+      req.on('close', clear);
+      res.on('finish', clear);
+      res.on('close', clear);
+    }
+    // Between keep-alive requests the socket owes us a fresh set of
+    // headers: re-arm the header deadline when this exchange finishes so a
+    // stalled *next* request is bounded too. A still-open response (SSE)
+    // never emits 'finish', and its request completed on arrival, so no
+    // timer is ever pending against a live stream or long-poll.
+    res.on('finish', () => { if (!socket.destroyed && socket._gbArmHeaderDeadline) socket._gbArmHeaderDeadline(); });
+    res.on('close', () => clearTimeout(socket._gbHeaderTimer));
+  });
+  return server;
+}
+
+// SSE stream caps (v0.5.6): before this round a workspace's /api/stream
+// subscribers were bounded by nothing but the request limiter — each one
+// holds a bus listener, a socket, and a 25 s ping interval, forever, and a
+// buggy client reconnect-looping could pile them up without limit. Caps are
+// generous against real teams (an agent holds at most a stream or two) and
+// refuse cleanly with 429 past them. The per-process total spans every
+// handler in the process, which is what protects the hosted server.
+const streamCap = (envName, def) => {
+  const n = Number(process.env[envName]);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : def;
+};
+let activeStreamsTotal = 0;
+
 export function createBusHandler({ id = 'default', bus, key = '' }) {
   const buckets = new Map();
+  const rateLimit = rateLimitPerMin();
   const rateOk = (req) => {
     const ip = (req.socket && req.socket.remoteAddress) || 'unknown';
     const t = Date.now();
+    // Opportunistic sweep: one bucket per source IP per minute would
+    // otherwise accumulate forever on a long-lived server (v0.5.6).
+    if (buckets.size > 4096) { for (const [k, v] of buckets) if (t - v.start > 60_000) buckets.delete(k); }
     let b = buckets.get(ip);
     if (!b || t - b.start > 60_000) { b = { start: t, count: 0 }; buckets.set(ip, b); }
     b.count += 1;
-    return b.count <= 300;
+    return b.count <= rateLimit;
   };
+  let activeStreams = 0; // this workspace's live /api/stream subscribers
   const keyOk = (req) => {
     if (!key) return true;
     const given = req.headers['x-bus-key'] || String(req.headers.authorization || '').replace(/^Bearer\s+/i, '');
@@ -99,7 +200,7 @@ export function createBusHandler({ id = 'default', bus, key = '' }) {
       res.writeHead(status, { 'content-type': type }); res.end(body);
     };
     if (!rateOk(req) && url.pathname !== '/health' && url.pathname !== '/probe') {
-      return send(429, { error: 'rate limit: 300 requests/min per IP per workspace' });
+      return send(429, { error: `rate limit: ${rateLimit} requests/min per IP per workspace` });
     }
     const send413 = () => {
       try {
@@ -124,22 +225,45 @@ export function createBusHandler({ id = 'default', bus, key = '' }) {
       if (req.method === 'GET' && url.pathname === '/api/stream') {
         const agent = url.searchParams.get('agent');
         if (!agent) return send(400, { error: 'agent query param required' });
+        // Stream caps (v0.5.6): refuse BEFORE opening the stream — a 429 the
+        // client can back off from, not a socket that dies later.
+        const maxPerWorkspace = streamCap('GHOSTBUS_MAX_STREAMS_PER_WORKSPACE', 100);
+        const maxTotal = streamCap('GHOSTBUS_MAX_STREAMS_TOTAL', 1000);
+        if (activeStreams >= maxPerWorkspace) return send(429, { error: `too many event streams for this workspace (limit ${maxPerWorkspace})` });
+        if (activeStreamsTotal >= maxTotal) return send(429, { error: `too many event streams on this server (limit ${maxTotal})` });
+        activeStreams += 1; activeStreamsTotal += 1;
         res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
         res.write(`event: ready\ndata: ${JSON.stringify({ agent, workspace: id, version: GHOSTBUS_VERSION })}\n\n`);
+        let cleaned = false;
         const off = bus.onEvent((ev) => {
           const forMe = ev.type === 'message.send' ? (ev.to === agent || ev.to === '*' || ev.actor === agent) : true;
           if (!forMe) return;
-          res.write(`event: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`);
+          try { res.write(`event: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`); } catch { cleanup(); }
         });
-        const ping = setInterval(() => res.write(': ping\n\n'), 25000);
-        req.on('close', () => { clearInterval(ping); off(); });
+        const ping = setInterval(() => { try { res.write(': ping\n\n'); } catch { cleanup(); } }, 25000);
+        // Reaping (v0.5.6): whichever side of the connection dies first —
+        // request close, response close, or a write into a dead socket —
+        // the listener, the ping, and both cap slots are released exactly
+        // once, so churn can neither leak listeners nor strand cap slots.
+        function cleanup() {
+          if (cleaned) return; cleaned = true;
+          clearInterval(ping); off();
+          activeStreams -= 1; activeStreamsTotal -= 1;
+        }
+        req.on('close', cleanup);
+        res.on('close', cleanup);
+        res.on('error', cleanup);
         return;
       }
 
       if (req.method === 'GET' && url.pathname === '/api/wait') {
         const agent = url.searchParams.get('agent');
         if (!agent) return send(400, { error: 'agent query param required' });
-        const timeout = Math.min(Number(url.searchParams.get('timeout') || 25), 55) * 1000;
+        // Garbage timeouts (timeout=abc -> NaN -> an instant empty reply;
+        // negative -> the same) fall back to the 25s default; real values
+        // clamp into [0, 55]s (v0.5.5).
+        const tParam = Number(url.searchParams.get('timeout') || 25);
+        const timeout = (Number.isFinite(tParam) ? Math.min(Math.max(tParam, 0), 55) : 25) * 1000;
         const sinceSeq = url.searchParams.has('sinceSeq') ? Number(url.searchParams.get('sinceSeq')) : (await bus.sync({})).headSeq;
         const immediate = await bus.sync({ sinceSeq, limit: 100 });
         const relevantNow = immediate.events.filter(ev => ev.type !== 'message.send' || ev.to === agent || ev.to === '*' || ev.actor === agent);

package/src/hosted-server.mjs

@@ -37,7 +37,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { createBus, FileStore, GHOSTBUS_VERSION, validateSnapshot } from './core.mjs';
-import { createBusHandler, keyMatches, hashMatches, readJsonBody, MAX_BODY_BYTES, HTML_SECURITY_HEADERS } from './handler.mjs';
+import { createBusHandler, keyMatches, hashMatches, readJsonBody, MAX_BODY_BYTES, HTML_SECURITY_HEADERS, applyServerTimeouts, SERVER_TIMEOUT_DEFAULTS } from './handler.mjs';
 
 const argv = process.argv.slice(2);
 const argVal = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
@@ -145,6 +145,9 @@ const authThrottled = (ip) => {
 };
 const noteAuthFail = (ip) => {
   const t = Date.now();
+  // Opportunistic sweep (v0.5.6): one entry per attacking IP per window
+  // would otherwise accumulate forever on a long-lived server.
+  if (authFails.size > 4096) { for (const [k, v] of authFails) if (t - v.start > AUTH_FAIL_WINDOW_MS) authFails.delete(k); }
   let b = authFails.get(ip);
   if (!b || t - b.start > AUTH_FAIL_WINDOW_MS) { b = { start: t, count: 0 }; authFails.set(ip, b); }
   b.count += 1;
@@ -316,6 +319,15 @@ const server = http.createServer(async (req, res) => {
   }
 });
 
+// Explicit server timeouts (v0.5.6): slow-loris header/body deadlines, set
+// here rather than inherited from Node defaults — see applyServerTimeouts
+// in handler.mjs for the scoping (long-lived streams are never bounded).
+const timeoutOpt = (envName, def) => { const n = Number(process.env[envName]); return Number.isFinite(n) && n > 0 ? Math.floor(n) : def; };
+applyServerTimeouts(server, {
+  headersMs: timeoutOpt('GHOSTBUS_HEADERS_TIMEOUT_MS', SERVER_TIMEOUT_DEFAULTS.headersMs),
+  requestMs: timeoutOpt('GHOSTBUS_REQUEST_TIMEOUT_MS', SERVER_TIMEOUT_DEFAULTS.requestMs),
+});
+
 server.listen(port, () => {
   process.stderr.write(`ghostbus HOSTED v${GHOSTBUS_VERSION} · http://127.0.0.1:${port} · data=${dataDir} · workspaces=${Object.keys(loadRegistry().workspaces).length} · agentTokens=${REQUIRE_TOKENS ? 'enforced' : 'issued, not enforced'}\n`);
 });

package/src/http-server.mjs

@@ -14,7 +14,7 @@
  */
 import http from 'node:http';
 import { createBus, MemoryStore, FileStore, GHOSTBUS_VERSION } from './core.mjs';
-import { createBusHandler } from './handler.mjs';
+import { createBusHandler, applyServerTimeouts, SERVER_TIMEOUT_DEFAULTS } from './handler.mjs';
 
 const argv = process.argv.slice(2);
 const argVal = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
@@ -32,6 +32,14 @@ const server = http.createServer((req, res) => {
   const url = new URL(req.url, 'http://localhost');
   handle(req, res, url).catch((e) => { process.stderr.write(`ghostbus relay: internal error: ${(e && e.stack) || e}\n`); try { res.writeHead(500, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: 'internal error' })); } catch {} });
 });
+// Explicit server timeouts (v0.5.6): slow-loris header/body deadlines, set
+// here rather than inherited from Node defaults — see applyServerTimeouts
+// in handler.mjs for the scoping (long-lived streams are never bounded).
+const timeoutOpt = (envName, def) => { const n = Number(process.env[envName]); return Number.isFinite(n) && n > 0 ? Math.floor(n) : def; };
+applyServerTimeouts(server, {
+  headersMs: timeoutOpt('GHOSTBUS_HEADERS_TIMEOUT_MS', SERVER_TIMEOUT_DEFAULTS.headersMs),
+  requestMs: timeoutOpt('GHOSTBUS_REQUEST_TIMEOUT_MS', SERVER_TIMEOUT_DEFAULTS.requestMs),
+});
 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

package/src/mcp-server.mjs

@@ -56,6 +56,12 @@ rl.on('line', async (line) => {
   if (!line.trim()) return;
   let msg;
   try { msg = JSON.parse(line); } catch { return; }
-  await handle(msg);
+  // A JSON-RPC message is a plain object. Anything else on the wire — null,
+  // a bare string/number, an array — is ignored, never fatal (v0.5.5: one
+  // bare `null` line used to throw in handle() and kill the server process
+  // for every connected agent). And handle() itself is wrapped: one bad
+  // message must never take the bus down.
+  if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return;
+  try { await handle(msg); } catch { /* a malformed message is dropped, not fatal */ }
 });
 process.stderr.write(`ghostbus mcp-server v${GHOSTBUS_VERSION} · store=${storePath} · workspace="${wsName}"\n`);

package/src/tools.mjs

@@ -35,7 +35,45 @@ export const TOOLS = [
   { name: 'bus_events', description: 'Read the provenance event log (who did what, when).', inputSchema: { type: 'object', properties: { limit: { type: 'number', default: 50 } } } },
 ];
 
+// Argument validation (v0.5.5): an MCP client — or a prompt-injected agent
+// driving one — can send ANY argument shapes, and the core bus deliberately
+// coerces a lot (String(body) turned an object body into a stored
+// "[object Object]" message; a numeric `path` became a state key). The
+// tools layer is the trust boundary, so arguments are checked against the
+// tool's own declared inputSchema here, once, instead of per-tool ad-hoc
+// checks: required arguments must be present (null counts as missing, the
+// codebase's absent-value convention), and every provided argument must
+// match its declared type — numbers must be finite, objects must be plain
+// objects (not arrays/null). Undeclared extra arguments pass through
+// untouched (several tools read an undeclared `token`). Violations throw a
+// plain Error, which both transports already surface as a clean isError /
+// 400 result — never a crash, never coerced garbage in shared state.
+const ARG_TYPE_CHECKS = {
+  string: { ok: (v) => typeof v === 'string', label: 'a string' },
+  number: { ok: (v) => typeof v === 'number' && Number.isFinite(v), label: 'a finite number' },
+  boolean: { ok: (v) => typeof v === 'boolean', label: 'a boolean' },
+  array: { ok: (v) => Array.isArray(v), label: 'an array' },
+  object: { ok: (v) => !!v && typeof v === 'object' && !Array.isArray(v), label: 'an object' },
+};
+function validateToolArgs(tool, args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    throw new Error(`tool ${tool.name}: arguments must be an object`);
+  }
+  const schema = tool.inputSchema || {};
+  for (const k of schema.required || []) {
+    if (args[k] === undefined || args[k] === null) throw new Error(`tool ${tool.name}: missing required argument "${k}"`);
+  }
+  for (const [k, spec] of Object.entries(schema.properties || {})) {
+    const v = args[k];
+    if (v === undefined || v === null) continue; // absent optional — the ?? defaults below apply
+    const check = ARG_TYPE_CHECKS[spec.type];
+    if (check && !check.ok(v)) throw new Error(`tool ${tool.name}: argument "${k}" must be ${check.label}`);
+  }
+}
+
 export async function callTool(bus, name, args = {}) {
+  const tool = TOOLS.find(t => t.name === name);
+  if (tool) validateToolArgs(tool, args);
   switch (name) {
     case 'bus_status': return bus.status();
     case 'bus_register': return bus.registerAgent({ name: args.agent, role: args.role, capabilities: args.capabilities, token: args.token ?? null });