@possumtech/rummy 2.0.1 → 2.1.0

package/src/plugins/telemetry/telemetry.js

@@ -1,12 +1,16 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+// model://N is a diagnostic slice; full content is in assistant://N.
+const MODEL_SNAPSHOT_BYTES = 4096;
+
 export default class Telemetry {
 	#core;
 	#starts = new Map();
 	#lastRunPath = null;
 	#turnsDir = null;
 	#turnLog = [];
+	#turnStartIdx = 0;
 	#currentRunAlias = null;
 	#currentTurn = null;
 
@@ -31,8 +35,8 @@ export default class Telemetry {
 	async #onRpcStarted({ method, id, params }) {
 		this.#starts.set(id, Date.now());
 		let summary = "";
-		if (method === "ask" || method === "act") {
-			const prompt = params?.prompt ? params.prompt : "";
+		if (method === "set" && params?.path?.startsWith("run://")) {
+			const prompt = params?.body ? params.body : "";
 			summary = `prompt="${prompt.slice(0, 60)}"`;
 		} else if (method === "run/abort") {
 			summary = `run=${params?.run}`;
@@ -40,10 +44,6 @@ export default class Telemetry {
 			summary = `run=${params?.run} action=${params?.resolution?.action}`;
 		}
 		console.log(`[RPC] → ${method}(${id})${summary ? ` ${summary}` : ""}`);
-
-		if (method === "ask" || method === "act") {
-			this.#turnLog = [];
-		}
 	}
 
 	async #onRpcCompleted({ method, id, result }) {
@@ -136,7 +136,7 @@ export default class Telemetry {
 				reasoning_content: responseMessage?.reasoning_content
 					? responseMessage.reasoning_content
 					: null,
-				content: content.slice(0, 4096),
+				content: content.slice(0, MODEL_SNAPSHOT_BYTES),
 				usage: result.usage ? result.usage : null,
 				model: result.model ? result.model : null,
 			}),
@@ -161,10 +161,7 @@ export default class Telemetry {
 			}
 		}
 
-		// content://N — unparsed text. 400 Bad Request because anything in
-		// unparsed is text the parser couldn't dispatch (malformed XML, native
-		// tool call attempts, reasoning bleed). Visible to the model so it
-		// sees the rejection on its next turn and can correct.
+		// content://N — visible-rejected unparsed text so the model can correct next turn.
 		if (unparsed) {
 			await store.set({
 				runId,
@@ -179,9 +176,7 @@ export default class Telemetry {
 			});
 		}
 
-		// Commit usage stats. Providers surface token counts under
-		// incompatible keys; walk them in priority order and fall back
-		// to 0 only as the definitional "not reported" value.
+		// Per-provider key drift; walk in priority order, 0 = not reported.
 		const usage = result.usage ? result.usage : {};
 		const cachedSources = [
 			usage.cached_tokens,
@@ -206,8 +201,7 @@ export default class Telemetry {
 				reasoningTokens = v;
 				break;
 			}
-		// Use LLM's actual prompt_tokens as the ground-truth context size
-		// when available; falls back to our pre-call estimate.
+		// LLM's prompt_tokens is ground truth; estimator is pre-call fallback.
 		let actualContextTokens = 0;
 		if (usage.prompt_tokens) actualContextTokens = usage.prompt_tokens;
 		else if (assembledTokens) actualContextTokens = assembledTokens;
@@ -223,15 +217,27 @@ export default class Telemetry {
 			completion_tokens: numberOrZero(usage.completion_tokens),
 			reasoning_tokens: reasoningTokens,
 			total_tokens: numberOrZero(usage.total_tokens),
-			cost: numberOrZero(usage.cost),
+			// usage.cost is what the relay BILLED us; it reads 0 when routed
+			// via BYOK (relay didn't bill — upstream charged our key directly).
+			// upstream_inference_cost is the true compute cost in either case.
+			cost:
+				numberOrZero(usage.cost) ||
+				numberOrZero(usage.cost_details?.upstream_inference_cost),
 		});
 	}
 
 	async #logMessages(messages, context) {
-		this.#currentRunAlias = context.runAlias
+		const newAlias = context.runAlias
 			? context.runAlias
 			: `run_${context.runId}`;
+		// Reset on alias change (the semantic run boundary).
+		if (newAlias !== this.#currentRunAlias) {
+			this.#turnLog = [];
+		}
+		this.#currentRunAlias = newAlias;
 		this.#currentTurn = context.turn === undefined ? null : context.turn;
+		// Per-turn slice index; turn_NNN.txt = this turn only, last_run.txt = cumulative.
+		this.#turnStartIdx = this.#turnLog.length;
 		const turnLabel = this.#currentTurn === null ? "?" : this.#currentTurn;
 		this.#turnLog.push(
 			`\n${"=".repeat(60)}\nTURN ${turnLabel} — model=${context.model} run=${this.#currentRunAlias}\n${"=".repeat(60)}`,
@@ -272,6 +278,7 @@ export default class Telemetry {
 		const runDir = join(this.#turnsDir, this.#currentRunAlias);
 		await mkdir(runDir, { recursive: true });
 		const fileName = `turn_${String(this.#currentTurn).padStart(3, "0")}.txt`;
-		await writeFile(join(runDir, fileName), `${this.#turnLog.join("\n")}\n`);
+		const turnSlice = this.#turnLog.slice(this.#turnStartIdx);
+		await writeFile(join(runDir, fileName), `${turnSlice.join("\n")}\n`);
 	}
 }

package/src/plugins/think/think.js

@@ -1,13 +1,12 @@
+import config from "../../agent/config.js";
 import docs from "./thinkDoc.js";
 
-const THINK_ENABLED = process.env.RUMMY_THINK;
-if (THINK_ENABLED === undefined)
-	throw new Error("RUMMY_THINK must be set (1 or 0)");
+const { THINK } = config;
 
 export default class Think {
 	constructor(core) {
 		core.registerScheme({ modelVisible: 0, category: "logging" });
-		if (THINK_ENABLED === "1") {
+		if (THINK === "1") {
 			core.ensureTool();
 			core.filter("instructions.toolDocs", async (docsMap) => {
 				docsMap.think = docs;
@@ -15,9 +14,7 @@ export default class Think {
 			});
 		}
 
-		// Merge <think> tag bodies into the turn's reasoning_content so
-		// models without a dedicated reasoning channel still expose their
-		// reasoning through the same field.
+		// Merge <think> bodies into reasoning_content for models without a reasoning channel.
 		core.filter("llm.reasoning", (reasoning, { commands }) => {
 			const thinkText = commands
 				.filter((c) => c.name === "think")

package/src/plugins/unknown/unknown.js

@@ -1,8 +1,5 @@
 export default class Unknown {
-	#core;
-
 	constructor(core) {
-		this.#core = core;
 		core.ensureTool();
 		core.registerScheme({
 			category: "unknown",
@@ -10,28 +7,28 @@ export default class Unknown {
 		core.on("handler", this.handler.bind(this));
 		core.on("visible", this.full.bind(this));
 		core.on("summarized", this.summary.bind(this));
-		core.filter("assembly.user", this.assembleUnknowns.bind(this), 200);
+		core.filter("assembly.user", this.assembleUnknowns.bind(this), 150);
 		core.markHidden();
 	}
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 
-		// Deduplicate — if this exact body already exists, skip
 		const existingValues = await store.getUnknownValues(runId);
 		if (existingValues.has(entry.body)) {
-			await this.#core.hooks.error.log.emit({
-				store,
+			await store.set({
 				runId,
 				turn,
 				loopId,
-				message: `Unknown deduped: "${entry.body.slice(0, 60)}"`,
+				path: entry.resultPath || entry.path,
+				body: `Unknown deduped: "${entry.body.slice(0, 60)}"`,
+				state: "failed",
+				outcome: "duplicate",
 			});
 			return;
 		}
 
-		// Generate slug path and upsert. Summary (if provided) becomes the
-		// path so the model can round-trip it via <get>; body is the fallback.
+		// summary > body for slug; lets the model round-trip via <get>.
 		const unknownPath = await store.slugPath(
 			runId,
 			"unknown",
@@ -52,9 +49,7 @@ export default class Unknown {
 		return entry.body;
 	}
 
-	// Same principle as knowns: keep the first 500 characters on
-	// summarized unknowns so demotion doesn't erase the question,
-	// but cap large bodies to bound the packet cost.
+	// First 500 chars; matches knowns/prompt summarized.
 	summary(entry) {
 		if (!entry.body) return "";
 		if (entry.body.length <= 500) return entry.body;

package/src/plugins/update/update.js

@@ -32,60 +32,61 @@ export default class Update {
 	}
 
 	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const status = entry.attributes?.status ?? 102;
 		const validation = await rummy.hooks.instructions.validateNavigation(
 			status,
 			rummy,
 		);
-		const attributes = validation.ok ? {} : { rejected: true };
-		await rummy.update(entry.body, { status, attributes });
 		if (!validation.ok) {
-			await rummy.hooks.error.log.emit({
-				store: rummy.entries,
-				runId: rummy.runId,
-				turn: rummy.sequence,
-				loopId: rummy.loopId,
-				message: validation.reason,
-				status: 422,
+			entry.state = "failed";
+			entry.outcome = "invalid_navigation";
+			entry.body = validation.reason;
+			await store.set({
+				runId,
+				turn,
+				loopId,
+				path: entry.resultPath,
+				body: validation.reason,
+				state: "failed",
+				outcome: "invalid_navigation",
+				attributes: { status },
+			});
+			return;
+		}
+		if (!isValidStatus(status)) {
+			entry.state = "failed";
+			entry.outcome = "invalid_status";
+			const message = `Invalid status ${status} on update — use 1xx to continue or 200 to conclude.`;
+			entry.body = message;
+			await store.set({
+				runId,
+				turn,
+				loopId,
+				path: entry.resultPath,
+				body: message,
+				state: "failed",
+				outcome: "invalid_status",
+				attributes: { status },
 			});
+			return;
 		}
+		await rummy.update(entry.body, { status });
 	}
 
-	/**
-	 * Classify this turn's update state.
-	 *
-	 * Returns { summaryText, updateText }:
-	 *   - summaryText: non-null → model claimed terminal (200/204/422)
-	 *   - updateText:  non-null → model is continuing (1xx)
-	 *
-	 * Errors (invalid status, missing update) emit via hooks.error.log.
-	 * The "terminal + turn had errors → not actually terminal" rule
-	 * lives in the error plugin's verdict, not here.
-	 */
 	async resolve({ recorded, content, runId, turn, loopId, rummy }) {
 		const entry = recorded.findLast((e) => e.scheme === "update");
 		const status = entry?.attributes?.status ?? 102;
-		const rejected = entry?.attributes?.rejected === true;
-		const isTerminal = TERMINAL_STATUSES.has(status) && !rejected;
+		const failed = entry?.state === "failed";
+		const isTerminal = TERMINAL_STATUSES.has(status) && !failed;
 		let summaryText = null;
 		let updateText = null;
-		if (entry?.body) {
+		if (entry?.body && !failed) {
 			if (isTerminal) summaryText = entry.body;
 			else updateText = entry.body;
 		}
 
-		if (entry && !isValidStatus(status)) {
-			await rummy.hooks.error.log.emit({
-				store: rummy.entries,
-				runId,
-				turn,
-				loopId,
-				message: `Invalid status ${entry.attributes?.status} on update — use 1xx to continue or 200 to conclude.`,
-				status: 422,
-			});
-		}
-
-		if (!summaryText && !updateText) {
+		if (!summaryText && !updateText && !failed) {
 			const empty = !content || content.trim() === "";
 			await rummy.hooks.error.log.emit({
 				store: rummy.entries,

package/src/plugins/update/updateDoc.md

@@ -1,8 +1,8 @@
-## <update status="N">{brief status}</update> - Status report (exactly one per turn, at the end)
+## <update status="N">{brief status}</update> - Report turn status (exactly one per turn, at the end)
 <!-- Header defines position, frequency, and status code requirement. -->
 
-REQUIRED: the valid values of N are defined by your current stage instructions.
+YOU MUST refer to your current stage instructions for valid values of N.
 <!-- Single source of truth for codes is the current phase instructions block, not this doc. Listing codes here leaks termination knowledge (e.g. 200) that strong models use to short-circuit the protocol. -->
 
-REQUIRED: YOU MUST keep <update></update> body to <= 80 characters.
+YOU MUST keep <update></update> body to <= 80 characters.
 <!-- Length cap. -->

package/src/plugins/xai/xai.js

@@ -1,16 +1,12 @@
+import config from "../../agent/config.js";
 import msg from "../../agent/messages.js";
+import { parseRetryAfter } from "../../llm/errors.js";
 
-const FETCH_TIMEOUT = Number(process.env.RUMMY_FETCH_TIMEOUT);
-if (!FETCH_TIMEOUT) throw new Error("RUMMY_FETCH_TIMEOUT must be set");
+const { FETCH_TIMEOUT } = config;
 
 const PROVIDER = "xai";
 
-/**
- * xAI (Grok) LLM provider plugin. Registers with hooks.llm.providers if
- * XAI_BASE_URL is set; inert otherwise. Handles model aliases of the
- * form `xai/{modelName}`. Normalizes xAI's distinct response shape
- * into the common OpenAI-shaped envelope.
- */
+// Inert unless XAI_BASE_URL set; xai/{model} aliases; normalizes to OpenAI envelope.
 export default class Xai {
 	#baseUrl;
 	#apiKey;
@@ -39,6 +35,11 @@ export default class Xai {
 		const body = { model, input: messages };
 		if (options.temperature !== undefined)
 			body.temperature = options.temperature;
+		// xAI auto-caches per-server; stable prompt_cache_key keeps a multi-
+		// turn run pinned to the same backend so the cached prefix actually
+		// hits. Without this, requests load-balance and cache_tokens stays
+		// near-zero. See https://docs.x.ai/developers/advanced-api-usage/prompt-caching.
+		if (options.runAlias) body.prompt_cache_key = options.runAlias;
 
 		const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT);
 		const signal = options.signal
@@ -56,15 +57,27 @@ export default class Xai {
 		});
 
 		if (!response.ok) {
-			const error = await response.text();
+			const errorBody = await response.text();
+			const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
 			if (response.status === 401 || response.status === 403) {
-				throw new Error(
-					msg("error.xai_auth", { status: `${response.status} - ${error}` }),
+				const err = new Error(
+					msg("error.xai_auth", {
+						status: `${response.status} - ${errorBody}`,
+					}),
 				);
+				err.status = response.status;
+				err.body = errorBody;
+				throw err;
 			}
-			throw new Error(
-				msg("error.xai_api", { status: `${response.status} - ${error}` }),
+			const err = new Error(
+				msg("error.xai_api", {
+					status: `${response.status} - ${errorBody}`,
+				}),
 			);
+			err.status = response.status;
+			err.body = errorBody;
+			err.retryAfter = retryAfter;
+			throw err;
 		}
 
 		return this.#normalize(await response.json());
@@ -133,12 +146,11 @@ export default class Xai {
 		const modelsUrl = this.#baseUrl.replace(/\/responses$/, "/models");
 		const res = await fetch(modelsUrl, {
 			headers: { Authorization: `Bearer ${this.#apiKey}` },
-			signal: AbortSignal.timeout(5000),
+			signal: AbortSignal.timeout(FETCH_TIMEOUT),
 		});
 		if (res.ok) {
 			const data = await res.json();
-			// xAI's /models returns either { data: [...] } or { models: [...] }
-			// depending on the API version; accept either and crash otherwise.
+			// xAI /models response shape varies by API version.
 			let models;
 			if (data.data) models = data.data;
 			else if (data.models) models = data.models;
@@ -156,12 +168,10 @@ export default class Xai {
 			/\/responses$/,
 			`/language-models/${model}`,
 		);
-		// Optional endpoint probe. If the network call fails (404 on older
-		// API versions, timeout, etc.) we fall through to the next strategy
-		// below; a terminal throw fires if no strategy resolves.
+		// Optional probe; failure falls through to terminal throw below.
 		const langRes = await fetch(langUrl, {
 			headers: { Authorization: `Bearer ${this.#apiKey}` },
-			signal: AbortSignal.timeout(5000),
+			signal: AbortSignal.timeout(FETCH_TIMEOUT),
 		}).catch(() => null);
 		if (langRes?.ok) {
 			const langData = await langRes.json();

package/src/plugins/yolo/yolo.js

@@ -3,35 +3,17 @@ import { logPathToDataBase } from "../helpers.js";
 
 const SH_PATH_RE = /^log:\/\/turn_\d+\/(sh|env)\//;
 
-/**
- * YOLO plugin — for runs started with `yolo: true`, auto-resolves every
- * proposal server-side and spawns sh/env commands locally, streaming
- * output to the same data-channel entries the existing `stream`/
- * `stream/completed` RPC contract uses.
- *
- * Pattern parallel to `noRepo`/`noWeb`/`noInteraction`/`noProposals`:
- * `yolo` is a run attribute plumbed via rpc.js → AgentLoop loop config →
- * RummyContext.yolo. This plugin reads `rummy.yolo` off the proposal
- * payload and engages only when set; non-yolo runs are unaffected.
- *
- * The plugin replicates AgentLoop.resolve()'s accept path inline rather
- * than calling an exposed projectAgent — keeps yolo logic contained in
- * the yolo plugin and out of backbone files.
- */
+// Auto-resolves proposals + spawns sh/env locally for runs started with yolo:true. SPEC #yolo_mode.
 export default class Yolo {
 	constructor(core) {
 		this.core = core;
 		core.hooks.proposal.pending.on(this.#onPending.bind(this));
 	}
 
-	async #onPending({ run, proposed, rummy }) {
+	async #onPending({ proposed, rummy }) {
 		if (!rummy?.yolo) return;
 		for (const p of proposed) {
-			// Resolve first — that fires proposal.accepted, which lets the
-			// sh/env plugin seed the streaming channel entries. Then spawn
-			// into those existing channels. If we spawned first, sh.js's
-			// post-accept channel creation would clobber the body we just
-			// streamed (sets state=streaming, body="").
+			// Resolve first so sh/env's post-accept seeds channels before we stream into them.
 			await this.#serverResolve(rummy, p.path);
 			if (SH_PATH_RE.test(p.path)) {
 				await this.#executeShellProposal(rummy, p.path);
@@ -39,11 +21,7 @@ export default class Yolo {
 		}
 	}
 
-	/**
-	 * Replicate AgentLoop.resolve()'s accept path: accepting filter
-	 * (veto check), content filter (resolved body), set state="resolved",
-	 * emit proposal.accepted for plugin side effects.
-	 */
+	// Inline mirror of AgentLoop.resolve()'s accept path.
 	async #serverResolve(rummy, path) {
 		const runId = rummy.runId;
 		const entries = rummy.entries;
@@ -88,13 +66,7 @@ export default class Yolo {
 		await this.core.hooks.proposal.accepted.emit({ ...ctx, resolvedBody });
 	}
 
-	/**
-	 * Spawn the sh/env command locally and stream stdout/stderr into
-	 * `{dataBase}_1` and `{dataBase}_2` data entries. Mirrors the
-	 * stream/stream-completed RPC contract — same channel layout, same
-	 * terminal-state transitions on exit. Done inline (no RPC roundtrip)
-	 * so the run is fully autonomous.
-	 */
+	// Spawn locally and stream into {dataBase}_{1,2}; mirrors stream/stream-completed RPC.
 	async #executeShellProposal(rummy, logPath) {
 		const runId = rummy.runId;
 		const entries = rummy.entries;
@@ -118,9 +90,7 @@ export default class Yolo {
 			cwd: projectRoot,
 			env: process.env,
 		});
-		// Buffer chunks synchronously and write once after exit. Avoids
-		// the race where multiple async appends interleave with the
-		// terminal-state transition fired on 'close'.
+		// Buffer + write-once-on-exit; async appends would race the terminal-state transition.
 		const stdoutChunks = [];
 		const stderrChunks = [];
 		child.stdout.on("data", (data) => stdoutChunks.push(data.toString()));
@@ -154,10 +124,7 @@ export default class Yolo {
 				const duration = `${Math.round((Date.now() - start) / 1000)}s`;
 				const terminalState = exitCode === 0 ? "resolved" : "failed";
 				const outcome = exitCode === 0 ? null : `exit:${exitCode}`;
-				// Transition state without touching body — getState doesn't
-				// return body, and entries.set with body=undefined preserves
-				// the streamed content already in place. (`body: ""` would
-				// wipe everything we just streamed.)
+				// body=undefined preserves streamed content; body="" would wipe it.
 				for (const path of [stdoutPath, stderrPath]) {
 					try {
 						await entries.set({
@@ -175,7 +142,7 @@ export default class Yolo {
 						null,
 					);
 					const summary = channels
-						.map((c) => `${c.path} (${c.tokens || 0} tokens)`)
+						.map((c) => `${c.path} (${c.tokens} tokens)`)
 						.join(", ");
 					const exitLabel = exitCode === 0 ? "exit=0" : `exit=${exitCode}`;
 					await entries.set({

package/src/server/ClientConnection.js

@@ -23,8 +23,7 @@ export default class ClientConnection {
 
 		this.#ws.on("message", (data) => this.#handleMessage(data));
 		this.#ws.on("close", () => {
-			// Fire-and-forget: the Promise is cached by `shutdown()` so
-			// server-initiated close can await the same work.
+			// Fire-and-forget; shutdown() caches the Promise for server-initiated close to await.
 			this.shutdown().catch((err) => {
 				console.warn(`[RUMMY] shutdown on ws close failed: ${err.message}`);
 			});
@@ -33,25 +32,6 @@ export default class ClientConnection {
 		this.#setupNotifications();
 	}
 
-	#onProgress = (payload) => {
-		if (payload.projectId === this.#context.projectId) {
-			this.#sendNotification("run/progress", {
-				run: payload.run,
-				turn: payload.turn,
-				status: payload.status,
-			});
-		}
-	};
-
-	#onProposal = (payload) => {
-		if (payload.projectId === this.#context.projectId) {
-			this.#sendNotification("run/proposal", {
-				run: payload.run,
-				proposed: payload.proposed,
-			});
-		}
-	};
-
 	#onRender = (payload) => {
 		if (payload.projectId === this.#context.projectId) {
 			this.#sendNotification("ui/render", {
@@ -80,44 +60,35 @@ export default class ClientConnection {
 		}
 	};
 
-	#onState = (payload) => {
-		if (payload.projectId === this.#context.projectId) {
-			this.#sendNotification("run/state", {
-				run: payload.run,
-				turn: payload.turn,
-				status: payload.status,
-				summary: payload.summary,
-				history: payload.history,
-				unknowns: payload.unknowns,
-				telemetry: payload.telemetry,
-			});
-		}
+	// Pulse: any entry write in this client's project. Content-free hint
+	// — client reconciles via getEntriesByPattern with `since`.
+	#onEntryChanged = async ({ runId, path, changeType }) => {
+		if (this.#context.projectId == null) return;
+		const run = await this.#db.get_run_by_id.get({ id: runId });
+		if (!run || run.project_id !== this.#context.projectId) return;
+		this.#sendNotification("run/changed", {
+			run: run.alias,
+			runId,
+			path,
+			changeType,
+		});
 	};
 
 	#setupNotifications() {
-		this.#hooks.run.progress.on(this.#onProgress);
-		this.#hooks.proposal.pending.on(this.#onProposal);
 		this.#hooks.ui.render.on(this.#onRender);
 		this.#hooks.ui.notify.on(this.#onNotify);
-		this.#hooks.run.state.on(this.#onState);
 		this.#hooks.stream.cancelled.on(this.#onStreamCancelled);
+		this.#hooks.entry.changed.on(this.#onEntryChanged);
 	}
 
 	#teardown() {
-		this.#hooks.run.progress.off(this.#onProgress);
-		this.#hooks.proposal.pending.off(this.#onProposal);
 		this.#hooks.ui.render.off(this.#onRender);
 		this.#hooks.ui.notify.off(this.#onNotify);
-		this.#hooks.run.state.off(this.#onState);
 		this.#hooks.stream.cancelled.off(this.#onStreamCancelled);
+		this.#hooks.entry.changed.off(this.#onEntryChanged);
 	}
 
-	/**
-	 * Abort in-flight runs on this connection and wait for them to
-	 * settle. Idempotent: `ws.on("close")` and server-initiated close
-	 * both call this; the cached Promise guarantees the work happens
-	 * exactly once and both callers observe the same completion.
-	 */
+	// Idempotent abort+drain; cached Promise lets ws.close and server.close share completion.
 	shutdown() {
 		if (!this.#shutdownPromise) {
 			this.#shutdownPromise = (async () => {
@@ -241,8 +212,7 @@ export default class ClientConnection {
 		} catch (error) {
 			console.error(`[RUMMY] RPC Error: ${error.message}`);
 			console.error(`[RUMMY] Stack: ${error.stack}`);
-			// JSON-RPC: error responses for malformed requests with no id
-			// MUST carry null per the spec.
+			// JSON-RPC requires null id for malformed requests with no id.
 			this.#send({
 				jsonrpc: "2.0",
 				error: { code: -32603, message: error.message },

package/src/server/SocketServer.js

@@ -15,18 +15,13 @@ export default class SocketServer {
 		this.#wss.on("connection", (ws, _req) => {
 			const conn = new ClientConnection(ws, this.#db, this.#hooks);
 			this.#connections.add(conn);
-			// Remove from the tracking set only after the connection's
-			// shutdown drain has fully settled — not on raw ws-close —
-			// so server close() can still find and await an in-progress
-			// shutdown kicked off by a client-initiated disconnect.
+			// Delete after drain settles so server.close() can await client-initiated shutdowns.
 			ws.on("close", () => {
 				conn.shutdown().finally(() => this.#connections.delete(conn));
 			});
 		});
 
-		this.#wss.on("error", (_err) => {
-			// Proxy to registry or handle locally
-		});
+		this.#wss.on("error", (_err) => {});
 	}
 
 	address() {
@@ -38,14 +33,19 @@ export default class SocketServer {
 	}
 
 	async close() {
-		// Drain in-flight runs on each connection before closing the
-		// socket — otherwise detached kickoff Promises keep the Node
-		// event loop alive past server shutdown.
-		const shutdowns = [];
-		for (const conn of this.#connections) {
-			shutdowns.push(conn.shutdown().catch(() => {}));
+		// Drain in-flight runs first; otherwise detached kickoffs pin the event loop.
+		// Best-effort: a single connection failing to shut down cleanly should not
+		// prevent the others from closing, but the failure must be visible.
+		const results = await Promise.allSettled(
+			Array.from(this.#connections, (conn) => conn.shutdown()),
+		);
+		for (const r of results) {
+			if (r.status === "rejected") {
+				console.error(
+					`[RUMMY] Connection shutdown failed: ${r.reason?.message ?? r.reason}`,
+				);
+			}
 		}
-		await Promise.all(shutdowns);
 		this.#connections.clear();
 
 		await new Promise((resolve) => {