sloptimize 0.3.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sloptimize",
   "displayName": "sloptimize",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The agent-native profiler for browser games: always-on incident recording, zero-setup attach with file:line attribution, budgets with exit codes — the agent's senses and ruler for performance work.",
   "license": "MIT",
   "keywords": ["profiler", "three.js", "webgpu", "performance", "draw-calls"]

package/README.md

@@ -1,5 +1,7 @@
 # sloptimize
 
+[![npm](https://img.shields.io/npm/v/sloptimize.svg)](https://www.npmjs.com/package/sloptimize)
+
 sloptimize optimizes your game's rendering performance by finding the
 bottlenecks and reporting them to Claude Code to fix — all while you just play
 the game. No action is required on your end.
@@ -64,12 +66,18 @@ and `sloptimize history` read that ledger back.
 
 ## Install
 
+Published on npm as [`sloptimize`](https://www.npmjs.com/package/sloptimize).
+Node 22+.
+
 ```bash
-npm i -D sloptimize        # in your game repo
-# or one-off: npx sloptimize attach --launch http://localhost:3000
-# or from a checkout: node sloptimize/bin/sloptimize.mjs … (bare Node, no install)
+npm i -D sloptimize          # in your game repo (recommended)
+npx sloptimize --version     # confirm: prints the installed version
 ```
 
+No install at all for a one-off: `npx sloptimize attach --launch http://localhost:3000`.
+Working from a git checkout instead? `node /path/to/sloptimize/bin/sloptimize.mjs …`
+runs on bare Node.
+
 Zero dependencies, no postinstall, no supply chain — npm is delivery only.
 
 ## Quickest start: zero integration (tier 0)
@@ -164,14 +172,17 @@ top where the engine grants scene access — see `docs/SPEC.md` §4.
 
 ## Claude Code integration — the whole point
 
-This repo IS a Claude Code plugin. One install:
+The npm package IS a Claude Code plugin — skill, prompt hook, and MCP server
+ship inside it. After `npm i -D sloptimize`, point Claude at it:
 
 ```bash
-claude --plugin-dir node_modules/sloptimize    # after npm i -D sloptimize
-claude --plugin-dir /path/to/sloptimize        # from a checkout
-# or via marketplace: /plugin marketplace add m0dE/sloptimize && /plugin install sloptimize
+claude --plugin-dir node_modules/sloptimize
 ```
 
+Alternatives: `claude --plugin-dir /path/to/sloptimize` from a git checkout,
+or via the marketplace:
+`/plugin marketplace add m0dE/sloptimize` then `/plugin install sloptimize`.
+
 Then let the agent wire your game: `/sloptimize:install` walks it through
 the tier-1 integration (runtime, sink, budgets, hooks) and refuses to call
 itself done until the feed is proven live end-to-end.
@@ -192,6 +203,72 @@ prompt needed), arm `sloptimize watch` as a session Monitor — one line, in
 `docs/INTEGRATION.md` §5. Wire it into a `SessionStart` hook and every
 session arms it by itself.
 
+## Cloud (paid, invite-only)
+
+Everything above is local: one machine's `.sloptimize/` directory, read by
+that machine's shell and that machine's Claude Code session. sloptimize
+cloud is a separate, optional, invite-only service that widens the same
+catalogue to **every player, every build** — not just the one in front of
+you: 24h/7d/30d or any custom range, client incidents and server incidents
+(`sloptimize/node`) folded into the same footprint identity, plus uncaught
+errors (`sloptimize/errors`) as their own incident kind. The local product
+stays the default story — nothing below changes what a project with no
+cloud key does.
+
+Where the endpoint and key live: your project's settings page on the
+service (there is no public hostname to document here — sloptimize cloud
+is invite-only, and the endpoint you use is whatever that page shows you).
+It hands you three snippets:
+
+```js
+// browser: the cloud sink is a TEE beside your existing drain, never instead
+// of it — errors ride the same recorder as hitches, so one drain feeds both
+import { createRecorder, createErrorMonitor, createCloudSink } from 'sloptimize';
+const rec = createRecorder({ budgetFrameMs: 16.7 });
+createErrorMonitor(rec);
+const cloud = createCloudSink({ key: '<publishable key from settings>', endpoint: '<endpoint from settings>', build });
+// in the ~2s drain you already have (docs/INTEGRATION.md §1):
+const batch = rec.drainRecords();
+post('records', batch);   // unchanged: .sloptimize/perf.jsonl, still the source of truth
+cloud.enqueue(batch);     // the same records, teed to the cloud sink's own queue
+```
+
+(The `sources: [rec]` option exists only for a host with no file sink at all:
+the sink drains those sources itself, so anything it takes never reaches your
+own `drainRecords()`.)
+
+```js
+// game server (Node): ticks, event-loop stalls, and uncaught errors
+import { createServerRuntime } from 'sloptimize/node';
+const server = createServerRuntime({ key: '<secret key from settings>', endpoint: '<endpoint from settings>', build });
+```
+
+The server runtime registers `uncaughtExceptionMonitor` only, so it observes
+a crash without ever becoming part of the crash path. One consequence worth
+knowing: under `--unhandled-rejections=warn` or `none`, unhandled rejections
+are **not** captured — that event sees them only in Node's default `throw`
+mode, and listening to `unhandledRejection` instead would suppress the throw
+your process relies on.
+
+```bash
+# CLI: read the cloud catalogue instead of this machine's ledger
+export SLOPTIMIZE_KEY=<secret key from settings> SLOPTIMIZE_ENDPOINT=<endpoint from settings>
+npx sloptimize issues --cloud --preset 7d
+npx sloptimize fix --title "…" --push   # records locally, then pushes
+```
+
+Honesty is the whole pitch: a dropped-locally count rides every batch the
+sink sends, so the dashboard's numbers say what they could not see rather
+than pretending nothing was lost.
+
+Two kinds of key, and the difference matters. The **publishable** key is
+public and write-only (it can post incidents, never read anyone else's), so
+shipping it in a client bundle is the intended use, not a leak — that is the
+key in the browser snippet above. The **secret** key is the one the server
+runtime, the CLI (`SLOPTIMIZE_KEY`) and the MCP server use: it reads your
+whole catalogue (`/v1/issues`) and writes fixes (`/v1/fixes`). A secret key
+never goes in a client bundle.
+
 ## Budgets: "fast enough" as an exit code
 
 `.sloptimize/budgets.json` (the one file a human reviews):

package/bin/sloptimize.mjs

@@ -88,8 +88,24 @@ if (cmd === 'issues') {
   // The issue catalogue (SPEC §3.7): every incident type grouped by
   // footprint, with occurrences, first/last, builds, worst, and the fixes
   // applied to it. `--from/--to` scope the count; `--all` includes robots.
-  const { buildIssues, agoText } = await import('../src/history.js');
   const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+  const { buildIssues, agoText } = await import('../src/history.js');
+  if (args.includes('--cloud')) {
+    // The cloud catalogue (SPEC cloud §8.4): every player, every build, not
+    // just this machine's ledger. Configuration is explicit — a missing key
+    // or endpoint is said, never guessed.
+    const { cloudConfig, fetchIssues } = await import('../src/cloud-client.js');
+    const cfg = cloudConfig(process.env, args);
+    if (!cfg) { console.error('sloptimize issues --cloud: set SLOPTIMIZE_KEY and SLOPTIMIZE_ENDPOINT (or --key/--endpoint)'); process.exit(2); }
+    let rows;
+    try { rows = await fetchIssues(cfg, { preset: get('--preset'), from: get('--from'), to: get('--to'), source: get('--source'), kind: get('--kind') }); }
+    catch (e) { console.error(`sloptimize issues --cloud: ${e.message}`); process.exit(4); }
+    if (json) { out(rows); process.exit(0); }
+    if (rows.length === 0) { console.log('no incidents in this range on the cloud catalogue'); process.exit(4); }
+    console.log(`cloud ${cfg.endpoint} · ${get('--preset') ?? (get('--from') ? 'custom' : '24h')} · ${rows.length} footprints`);
+    for (const i of rows) console.log(`${i.glyph} fp=${i.id} ×${String(i.count).padEnd(5)} ${i.label.padEnd(44)} [${i.phase}] ${i.source}  last ${agoText(i.lastAgoMs).padEnd(8)} first ${i.first.slice(0, 16)}  builds ${i.builds.length}${i.fixCount ? `  fixes ${i.fixCount}` : ''}`);
+    process.exit(0);
+  }
   const issues = buildIssues(readJsonl('perf.jsonl', Infinity), {
     fixes: readJsonl('fixes.jsonl', Infinity), from: get('--from'), to: get('--to'), includeAutomated: args.includes('--all'),
   });
@@ -161,6 +177,8 @@ if (cmd === 'doctor') {
   console.log('  stated limits: no per-draw GPU timing; bisection ranks, never sums; workload repro not trajectory repro;');
   console.log('  gpu:* instruments fire only under a real WebGPU backend — a WebGL2-fallback session reads them as zeros, honestly;');
   console.log('  bench/gate (M3) not built yet in this install — verify fixes with counters (exact grade) + real-hardware sessions.');
+  const cfg = (await import('../src/cloud-client.js')).cloudConfig(process.env, args);
+  console.log(cfg ? `  cloud: configured (${cfg.endpoint})` : '  cloud: not configured (SLOPTIMIZE_KEY, SLOPTIMIZE_ENDPOINT)');
   process.exit(0);
 }
 
@@ -300,6 +318,14 @@ if (cmd === 'history' || cmd === 'fix') {
     const { appendFileSync, mkdirSync } = await import('node:fs');
     mkdirSync(DIR, { recursive: true });
     appendFileSync(join(DIR, 'fixes.jsonl'), JSON.stringify(fix) + '\n');
+    if (args.includes('--push')) {
+      // The local ledger is the source of truth — a push failure is
+      // reported but never turns a recorded fix into a failed command.
+      const { cloudConfig, pushFix } = await import('../src/cloud-client.js');
+      const cfg = cloudConfig(process.env, args);
+      if (!cfg) console.error('push skipped: set SLOPTIMIZE_KEY and SLOPTIMIZE_ENDPOINT');
+      else { try { await pushFix(cfg, fix); console.log('pushed to cloud'); } catch (e) { console.error(`push failed: ${e.message}`); } }
+    }
     out(fix, `fix recorded: ${fix.title}${fix.commit ? ` (${fix.commit})` : ''}\n  before ${fix.before.build ?? fix.before.from}: ${line(fix.before)}\n  after  ${fix.after.build ?? fix.after.from}: ${line(fix.after)}`);
     process.exit(0);
   }
@@ -342,5 +368,5 @@ if (cmd === 'attach') {
   await new Promise(() => {});
 }
 
-console.log('usage: sloptimize <report|issues|check|census|history|fix|doctor|hook-status|watch|attach> [--json] [--dir <path>]... [--counters-only] [--interval <s>] [--min-hitch-ms N] [--launch <url>] [--port N] [--headless]\n       sloptimize fix --title "…" [--issue "…"] [--solution "…"] [--commit sha] [--files a,b] [--footprints id,id] [--before <build|ISO..ISO>] [--after <build|ISO..ISO>]\n       sloptimize issues [--json] [--from ISO] [--to ISO] [--fp <id>] [--all]');
+console.log('usage: sloptimize <report|issues|check|census|history|fix|doctor|hook-status|watch|attach> [--json] [--dir <path>]... [--counters-only] [--interval <s>] [--min-hitch-ms N] [--launch <url>] [--port N] [--headless]\n       sloptimize fix --title "…" [--issue "…"] [--solution "…"] [--commit sha] [--files a,b] [--footprints id,id] [--before <build|ISO..ISO>] [--after <build|ISO..ISO>] [--push]\n       sloptimize issues [--json] [--from ISO] [--to ISO] [--fp <id>] [--all] [--cloud [--preset 24h|7d|30d] [--source s] [--kind k] [--key k] [--endpoint url]]');
 process.exit(2);

package/docs/INTEGRATION.md

@@ -164,6 +164,61 @@ panel.open();
 Flush cadence: post `profile` every ~2s, drain records with it.
 Gitignore `.sloptimize/*` except `budgets.json`.
 
+### Cloud sink (optional, paid, invite-only)
+
+The dev-endpoint sink above stays the default: it is what makes the files
+useful with nobody watching. sloptimize cloud is a separate, additive tee —
+never a replacement — that ships the same records to a service so the
+catalogue spans every player and build, not just this machine. Run it
+BESIDE the local `post()`, never instead of it:
+
+```js
+import { createCloudSink } from 'sloptimize/cloud';
+const cloud = createCloudSink({ key: '<publishable key>', endpoint: '<endpoint>', build });   // publishable: safe in the client bundle
+// wherever the local sink drains and posts:
+const batch = [...rec.drainRecords(), ...motion.drainRecords()];
+post('records', batch);   // unchanged: the local ledger, still the source of truth
+cloud.enqueue(batch);     // same records, teed to the cloud sink's own queue and flush timer
+```
+
+`enqueue(records)` just appends to the sink's internal queue (capped at
+`maxQueue`, oldest dropped and counted honestly) — it does not fetch or
+flush itself; the sink's own timer (and `pagehide`/`visibilitychange`) drain
+and post it on the usual backoff. Pair it with `createErrorMonitor(rec)` —
+the SAME recorder from §1, not a bare call — so uncaught client errors land
+in `rec` via `recorder.emit()` and ride `rec.drainRecords()` into `batch`
+above like any hitch, with no separate wiring to the cloud sink needed.
+
+### Game server (optional, paid, invite-only)
+
+The server side of the same catalogue: ticks that overran their budget,
+event-loop stalls the runtime itself measured, and uncaught errors — each
+attributed by a sampling profiler and shipped through the same cloud sink
+the browser uses.
+
+```js
+import { createServerRuntime } from 'sloptimize/node';
+const server = createServerRuntime({ key: '<secret key>', endpoint: '<endpoint>', build, tickBudgetMs: 16 });
+
+function gameLoop() {
+  server.tick(() => {          // wraps one tick; records a server-hitch if it overran tickBudgetMs
+    // … the game's own tick work …
+  });
+}
+```
+
+The key here is a SECRET key (`server-*` record types and the read routes
+are secret-only) — it never goes in a client bundle.
+
+`createServerRuntime` registers `uncaughtExceptionMonitor` only (never
+`uncaughtException`/`unhandledRejection`) — it observes a crash, it never
+becomes part of the crash path. That also means that under
+`--unhandled-rejections=warn` or `none`, unhandled rejections are NOT
+captured: `uncaughtExceptionMonitor` sees them only in Node's default
+`throw` mode. Call `await server.close()` on shutdown to
+flush the queue; a `beforeExit` hook already races a best-effort flush so a
+clean exit does not lose the last batch.
+
 ## 3. The CLI (the agent's shell surface)
 
 `sloptimize report|check|census|doctor --dir <game>/.sloptimize` — no

package/docs/SPEC.md

@@ -359,7 +359,8 @@ fixes applied to it, or the exact command that would record one.
 
 Cloud path: the footprint is computed by the writer, so a service that
 ingests many clients' records dedupes on `footprint.id` from day one; the
-fold is the same code.
+fold is the same code. The service is specified in the sloptimize-cloud repo
+(`docs/superpowers/specs/2026-09-02-sloptimize-cloud-design.md`).
 
 ---
 

package/docs/USAGE.md

@@ -160,6 +160,31 @@ npx sloptimize history --dir <game>/.sloptimize  # p95/calls/hitches over time,
 npx sloptimize doctor --dir <game>/.sloptimize   # what is wired/degraded
 ```
 
+## The cloud catalogue (optional, paid, invite-only)
+
+With a project on sloptimize cloud, `SLOPTIMIZE_KEY` and `SLOPTIMIZE_ENDPOINT`
+(or `--key`/`--endpoint`) point the same CLI at every player's ledger
+instead of just this machine's:
+
+```bash
+export SLOPTIMIZE_KEY=<secret key from the settings page>   # secret, not publishable: /v1/issues is secret-only
+export SLOPTIMIZE_ENDPOINT=<endpoint from the settings page>
+npx sloptimize issues --cloud                     # last 24h across every player/build, by default
+npx sloptimize issues --cloud --preset 7d         # or 30d
+npx sloptimize issues --cloud --from <ISO> --to <ISO> --source client --kind hitch
+```
+
+Unconfigured, it exits 2 and names the missing variable rather than
+silently falling back to the local ledger; a request that fails once
+configured (bad key, unreachable endpoint) exits 4. `sloptimize doctor`
+reports which state you're in (`cloud: configured (<endpoint>)` or
+`cloud: not configured (...)`).
+
+`sloptimize fix --push` records the fix locally exactly as `sloptimize fix`
+always has — the local ledger stays the source of truth — and then also
+POSTs it to the cloud service; a push failure prints `push failed: <reason>`
+but the command still exits 0, since the fix was recorded either way.
+
 ## Recording a fix (the agent's last step)
 
 Once a fix is verified — the new build is live and the ledger has evidence

package/mcp/server.mjs

@@ -13,9 +13,12 @@
 // wake is not a contract this host documents; when it becomes one, the
 // watcher moves here (SPEC-attach §2, delivery edge).
 import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 
+const PKG_VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version;
+
 const DIR = () => join(process.cwd(), '.sloptimize');
 let attachSession = null;
 
@@ -27,7 +30,9 @@ const TOOLS = [
   { name: 'get_history', description: 'The deployment’s timeline folded from perf.jsonl: time buckets (frame p95, draw calls, hitch spikes, build), one measured window per build, and the fix ledger (fixes.jsonl) — the before/after evidence behind every recorded fix.',
     inputSchema: { type: 'object', properties: { buckets: { type: 'number', description: 'time slices (default 24)' } } } },
   { name: 'get_issues', description: 'The issue catalogue (SPEC §3.7): every incident type on the ledger grouped by FOOTPRINT — the identity of a cause (type, phase, verdict, site, the game’s situation), never its time — with occurrences, first/last seen, builds, worst, the last verdict, and the fixes applied to it. Read this before proposing a fix: an issue with a fix already recorded is not new.',
-    inputSchema: { type: 'object', properties: { fp: { type: 'string', description: 'one footprint id' }, from: { type: 'string', description: 'ISO lower bound' }, to: { type: 'string', description: 'ISO upper bound' }, includeAutomated: { type: 'boolean', description: 'count robots’ sessions too (default false)' }, limit: { type: 'number', description: 'max rows (default 50)' } } } },
+    inputSchema: { type: 'object', properties: { fp: { type: 'string', description: 'one footprint id' }, from: { type: 'string', description: 'ISO lower bound' }, to: { type: 'string', description: 'ISO upper bound' }, includeAutomated: { type: 'boolean', description: 'count robots’ sessions too (default false)' }, limit: { type: 'number', description: 'max rows (default 50)' },
+      cloud: { type: 'boolean', description: 'read the cloud catalogue (every player, every build) instead of this machine\'s ledger — requires SLOPTIMIZE_KEY/SLOPTIMIZE_ENDPOINT' },
+      preset: { type: 'string', description: 'cloud only: 24h | 7d | 30d' }, source: { type: 'string', description: 'cloud only: filter by source (client|server)' }, kind: { type: 'string', description: 'cloud only: filter by incident kind' } } } },
   { name: 'record_fix', description: 'Append a fix report to .sloptimize/fixes.jsonl: title, issue, solution, commit, the FOOTPRINTS it addresses (from get_issues — this is how the Issues tab shows which fixes were applied to an issue), and MEASURED before/after windows of the ledger (default: the previous build vs the latest build with evidence; or name a build / an <ISO>..<ISO> range). Call this after verifying a perf fix — never with numbers of your own.',
     inputSchema: { type: 'object', properties: { title: { type: 'string' }, issue: { type: 'string' }, solution: { type: 'string' }, commit: { type: 'string' },
       files: { type: 'array', items: { type: 'string' } }, footprints: { type: 'array', items: { type: 'string' }, description: 'footprint ids this fix addresses' },
@@ -69,6 +74,15 @@ async function callTool(name, args = {}) {
     return buildHistory(readJsonl('perf.jsonl', Infinity), { fixes: readJsonl('fixes.jsonl', Infinity), buckets: args.buckets ?? 24 });
   }
   if (name === 'get_issues') {
+    if (args.cloud === true) {
+      const { cloudConfig, fetchIssues } = await import('../src/cloud-client.js');
+      const cfg = cloudConfig(process.env, []);
+      if (!cfg) return { error: 'cloud not configured: set SLOPTIMIZE_KEY and SLOPTIMIZE_ENDPOINT' };
+      try {
+        const rows = await fetchIssues(cfg, { preset: args.preset, from: args.from, to: args.to, source: args.source, kind: args.kind });
+        return { source: 'cloud', endpoint: cfg.endpoint, footprints: rows.length, occurrences: rows.reduce((n, i) => n + i.count, 0), issues: args.fp ? rows.filter((i) => i.id === args.fp) : rows.slice(0, args.limit ?? 50) };
+      } catch (e) { return { error: e.message }; }
+    }
     const { buildIssues } = await import('../src/history.js');
     const issues = buildIssues(readJsonl('perf.jsonl', Infinity), { fixes: readJsonl('fixes.jsonl', Infinity), from: args.from, to: args.to, includeAutomated: args.includeAutomated === true });
     const rows = args.fp ? issues.filter((i) => i.id === args.fp) : issues.slice(0, args.limit ?? 50);
@@ -111,7 +125,7 @@ rl.on('line', (line) => {
     try {
       if (msg.method === 'initialize') {
         reply(msg.id, { protocolVersion: msg.params?.protocolVersion ?? '2024-11-05',
-          capabilities: { tools: {} }, serverInfo: { name: 'sloptimize', version: '0.3.0' } });
+          capabilities: { tools: {} }, serverInfo: { name: 'sloptimize', version: PKG_VERSION } });
       } else if (msg.method === 'tools/list') {
         reply(msg.id, { tools: TOOLS });
       } else if (msg.method === 'tools/call') {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "sloptimize",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "The agent-native profiler for three.js games: an always-on flight recorder, per-entity cost attribution, and a deterministic bench — so a coding agent can measure, attribute, and verify instead of guessing.",
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "repository": {
     "type": "git",
@@ -21,7 +21,10 @@
   "exports": {
     ".": "./src/index.js",
     "./history": "./src/history.js",
-    "./panel": "./src/panel.js"
+    "./panel": "./src/panel.js",
+    "./cloud": "./src/cloud-sink.js",
+    "./errors": "./src/errors.js",
+    "./node": "./src/node/index.js"
   },
   "files": [
     "bin",
@@ -29,7 +32,7 @@
     "skills",
     "hooks",
     "mcp",
-    "docs",
+    "docs/*.md",
     ".claude-plugin",
     ".mcp.json",
     "LICENSE",

package/skills/install/SKILL.md

@@ -16,7 +16,8 @@ not report success until step 7 shows your test keyframe in
 
 ## 1. Locate the package and the game's shape
 
-- Find sloptimize: `node_modules/sloptimize` (npm) or a sibling checkout.
+- Find sloptimize: `node_modules/sloptimize` (from `npm i -D sloptimize`) or a
+  sibling checkout. If neither exists, install it from npm first.
 - Identify: the render loop's stats site (wherever `renderer.info` is
   already read), the dev-server topology (vite? own server? esbuild?), and
   the dev-only switch the project already uses for debug endpoints.

package/src/cloud-client.js

@@ -0,0 +1,29 @@
+// ============================================================
+// cloud-client.js — read side of sloptimize cloud (SPEC cloud §8.4)
+// ============================================================
+// Read side of sloptimize cloud for the CLI and MCP: the catalogue over every
+// player, not just this machine's ledger. Configuration is explicit — a key
+// and an endpoint — and a missing one is said, never guessed.
+export function cloudConfig(env = process.env, args = []) {
+  const flag = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+  const key = flag('--key') ?? env.SLOPTIMIZE_KEY;
+  const endpoint = (flag('--endpoint') ?? env.SLOPTIMIZE_ENDPOINT ?? '').replace(/\/+$/, '');
+  return key && endpoint ? { key, endpoint } : null;
+}
+
+export async function fetchIssues(cfg, q = {}, fetchImpl = globalThis.fetch, now = Date.now) {
+  const u = new URL(`${cfg.endpoint}/v1/issues`);
+  for (const k of ['preset', 'from', 'to', 'source', 'kind']) if (q[k]) u.searchParams.set(k, q[k]);
+  const res = await fetchImpl(u.toString(), { headers: { authorization: `Bearer ${cfg.key}` } });
+  if (!res.ok) throw new Error(`cloud ${res.status}: ${(await res.json().catch(() => ({}))).error ?? 'request failed'}`);
+  const rows = await res.json();
+  const t = now();
+  return rows.map((r) => ({ id: r.id, key: r.key, type: r.kind, glyph: r.glyph, label: r.label, phase: r.phase, ctx: r.ctx, source: r.source,
+    count: r.count, first: r.firstSeen, last: r.lastSeen, lastAgoMs: Math.max(0, t - Date.parse(r.lastSeen)), builds: r.builds ?? [], fixCount: r.fixes ?? 0, fixes: [], daily: r.daily ?? [], exact: r.exact }));
+}
+
+export async function pushFix(cfg, fix, fetchImpl = globalThis.fetch) {
+  const res = await fetchImpl(`${cfg.endpoint}/v1/fixes`, { method: 'POST', headers: { authorization: `Bearer ${cfg.key}`, 'content-type': 'application/json' }, body: JSON.stringify(fix) });
+  if (!res.ok) throw new Error(`cloud ${res.status}: ${(await res.json().catch(() => ({}))).error ?? 'request failed'}`);
+  return res.json();
+}

package/src/cloud-sink.js

@@ -0,0 +1,159 @@
+// ============================================================
+// cloud-sink.js — ship records to sloptimize cloud (SPEC cloud §8.2)
+// ============================================================
+// Runs BESIDE the file sink, never instead of it. Drains every source on a
+// timer, posts batches with the publishable key, backs off on 429/5xx, caps
+// its queue, and tells the service how many it had to drop locally so the
+// dashboard's "dropped" column is honest. Never throws into the host.
+const BACKOFF_MS = [5000, 30000, 120000, 300000];
+
+export function createCloudSink(opts = {}) {
+  if (!opts.key) throw new Error('createCloudSink: key is required');
+  if (!opts.endpoint) throw new Error('createCloudSink: endpoint is required');
+  const { key, endpoint, build } = opts;
+  const sources = opts.sources ?? [];
+  const flushMs = opts.flushMs ?? 5000, maxBatch = opts.maxBatch ?? 100, maxQueue = opts.maxQueue ?? 500;
+  // The Fetch spec caps a keepalive body at 64 KiB and sendBeacon has a limit
+  // of its own, so a batch is bounded by bytes as well as by count.
+  const maxBatchBytes = opts.maxBatchBytes ?? 60 * 1024;
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  const beacon = opts.sendBeacon ?? (typeof navigator !== 'undefined' && navigator.sendBeacon ? navigator.sendBeacon.bind(navigator) : null);
+  const target = opts.target ?? globalThis;
+  const setI = opts.setInterval ?? globalThis.setInterval, clearI = opts.clearInterval ?? globalThis.clearInterval;
+  const now = opts.now ?? (() => Date.now());
+
+  let queue = [];
+  let droppedLocally = 0;
+  let failures = 0, backoffUntil = 0, inflight = false;
+  const stats = { sent: 0, lastError: null, lastStatus: null };
+
+  function trim() {
+    if (queue.length > maxQueue) { droppedLocally += queue.length - maxQueue; queue = queue.slice(queue.length - maxQueue); }
+  }
+  function drain() {
+    for (const s of sources) {
+      let r; try { r = s.drainRecords(); } catch { continue; }
+      if (r && r.length) queue.push(...r);
+    }
+    trim();
+  }
+  function body(records) {
+    const b = { records };
+    if (build) b.build = build;
+    if (droppedLocally) b.droppedLocally = droppedLocally;
+    return b;
+  }
+  const encoder = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
+  const byteLen = (s) => (encoder ? encoder.encode(s).length : s.length);
+  /** How many of the queue's leading records fit in one body under
+   *  `maxBatchBytes`. A single record too large to ever fit is DROPPED and
+   *  counted, never retried: re-prepending it would wedge the sink forever,
+   *  and a silent wedge is the one failure this sink must not have. */
+  function fitCount() {
+    let envelope = byteLen(JSON.stringify(body([])));
+    let total = envelope, n = 0;
+    while (n < queue.length && n < maxBatch) {
+      const size = byteLen(JSON.stringify(queue[n])) + (n > 0 ? 1 : 0);   // +1 for the comma
+      if (total + size > maxBatchBytes) {
+        if (n > 0) break;
+        queue.shift();
+        droppedLocally++;
+        stats.lastError = `record dropped: ${size} bytes over maxBatchBytes (${maxBatchBytes})`;
+        envelope = byteLen(JSON.stringify(body([])));   // droppedLocally just grew
+        total = envelope;
+        continue;
+      }
+      total += size; n++;
+    }
+    return n;
+  }
+  async function flush() {
+    drain();
+    if (inflight || queue.length === 0 || now() < backoffUntil) return;
+    inflight = true;
+    // Remove the batch from the queue BEFORE sending, not after the await:
+    // otherwise a concurrent onHide()/enqueue() during the in-flight request
+    // sees records that are already (or about to be) accounted for elsewhere,
+    // causing duplicate delivery or silently corrupting the queue.
+    const errBefore = stats.lastError;
+    const n = fitCount();
+    // A success clears transport errors, but must not erase the report of a
+    // record this sink itself had to throw away in the same pass.
+    const droppedThisPass = stats.lastError !== errBefore;
+    if (n === 0) { inflight = false; return; }   // everything queued was oversized
+    const batch = queue.splice(0, n);
+    const sentDropped = droppedLocally;
+    try {
+      // No `keepalive` here: it caps the body at 64 KiB in browsers, and the
+      // unload path already uses sendBeacon. This is the periodic flush.
+      const res = await fetchImpl(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+        body: JSON.stringify(body(batch)),
+      });
+      stats.lastStatus = res.status;
+      if (res.ok) {
+        droppedLocally = Math.max(0, droppedLocally - sentDropped);
+        failures = 0; backoffUntil = 0; stats.sent += batch.length; if (!droppedThisPass) stats.lastError = null;
+      } else if (res.status === 429 || res.status >= 500) {
+        // Retryable: put the batch back at the front (it's the oldest data)
+        // and re-apply the cap, counting any resulting drops.
+        queue = batch.concat(queue);
+        trim();
+        const ra = Number(res.headers?.get?.('retry-after'));
+        const wait = BACKOFF_MS[Math.min(failures, BACKOFF_MS.length - 1)];
+        backoffUntil = now() + (Number.isFinite(ra) && ra > 0 ? Math.max(ra * 1000, wait) : wait);
+        failures++;
+        stats.lastError = `HTTP ${res.status}`;
+      } else {
+        // 4xx other than 429: the batch is unacceptable and already out of
+        // the queue (spliced above); drop it rather than retry forever.
+        droppedLocally += batch.length;
+        stats.lastError = `HTTP ${res.status}`;
+      }
+    } catch (e) {
+      // Network failure: the batch never left, so put it back and retry later.
+      queue = batch.concat(queue);
+      trim();
+      stats.lastError = e?.message ?? String(e);
+      const wait = BACKOFF_MS[Math.min(failures, BACKOFF_MS.length - 1)];
+      backoffUntil = now() + wait; failures++;
+    } finally { inflight = false; }
+  }
+  function onHide() {
+    try {
+      drain();
+      if (queue.length === 0 || !beacon) return;
+      // Any batch currently in flight via flush() was already spliced out of
+      // `queue`, so what's here is guaranteed disjoint from it — no duplicate
+      // delivery risk.
+      const n = fitCount();
+      if (n === 0) return;
+      const batch = queue.slice(0, n);
+      const beaconedDropped = droppedLocally;
+      const ok = beacon(`${endpoint}?key=${encodeURIComponent(key)}`, new Blob([JSON.stringify(body(batch))], { type: 'application/json' }));
+      if (ok) { queue = queue.slice(batch.length); droppedLocally = Math.max(0, droppedLocally - beaconedDropped); stats.sent += batch.length; }
+    } catch { /* never throw into the host */ }
+  }
+  const timer = setI(() => { flush(); }, flushMs);
+  // Never keep a game server's (or any Node host's) event loop alive just
+  // to poll for records — this sink runs beside the host's own liveness,
+  // not instead of it. A browser's setInterval returns a number, so the
+  // optional chaining below is a no-op there.
+  timer?.unref?.();
+  target.addEventListener?.('pagehide', onHide);
+  const onVis = () => { if (typeof document !== 'undefined' && document.visibilityState === 'hidden') onHide(); };
+  target.addEventListener?.('visibilitychange', onVis);
+  return {
+    flush,
+    enqueue(records) {
+      // A host tee that hands over something other than an array is a wiring
+      // bug in the host, not a reason to throw into its drain loop.
+      if (!Array.isArray(records)) { stats.lastError = 'enqueue: expected an array of records'; return; }
+      if (records.length) queue.push(...records);
+      trim();
+    },
+    stats() { return { queued: queue.length, sent: stats.sent, droppedLocally, backoffUntil, lastError: stats.lastError, lastStatus: stats.lastStatus }; },
+    dispose() { clearI(timer); target.removeEventListener?.('pagehide', onHide); target.removeEventListener?.('visibilitychange', onVis); },
+  };
+}

package/src/errors.js

@@ -0,0 +1,67 @@
+// ============================================================
+// errors.js — the browser's errors as incidents (SPEC cloud §8.1)
+// ============================================================
+// An uncaught error is a bottleneck of a different kind: the frame it killed
+// never rendered. It is recorded with the same identity model as a hitch —
+// the footprint names the cause (class, normalized message, top frame),
+// never the occurrence — so a thousand players hitting one bug is one row.
+// The monitor NEVER preventDefault()s: the console and the host's own
+// handlers see exactly what they saw before.
+import { footprintOf } from './footprint.js';
+
+export function createErrorMonitor(recorder, opts = {}) {
+  const target = opts.target ?? globalThis;
+  const dedupeMs = opts.dedupeMs ?? 10000;
+  const maxFrames = opts.maxFrames ?? 10;
+  const now = opts.now ?? (() => Date.now());
+  const lastByFp = new Map();
+  const stats = { seen: 0, emitted: 0, deduped: 0 };
+
+  // V8 frames start with "at "; SpiderMonkey/JavaScriptCore frames are
+  // "fn@url:line:col" (or "@url:line:col" when anonymous). Keeping only the
+  // V8 shape gave every Firefox and Safari player an empty stack — and a
+  // second catalogue row for the same bug.
+  const FRAME_RE = /^at |^[^\s]*@.+:\d+/;
+  function frames(stack) {
+    return String(stack ?? '').split('\n').map((l) => l.trim()).filter((l) => FRAME_RE.test(l)).slice(0, maxFrames);
+  }
+
+  /** A rejection reason that is not an Error, said as plainly as it can be
+   *  said. JSON.stringify throws on a circular object (and on a throwing
+   *  toJSON); an uncaught throw here would lose the incident entirely. */
+  function reasonMessage(r) {
+    if (typeof r === 'string') return r;
+    try { const j = JSON.stringify(r ?? null); if (j !== undefined) return j; } catch { /* circular / throwing toJSON */ }
+    try { return String(r); } catch { return '[unstringifiable]'; }
+  }
+  function toRecord(name, message, stack) {
+    return { type: 'error', at: new Date().toISOString(), source: 'client', name, message: String(message ?? ''), stack: frames(stack) };
+  }
+  function handle(rec) {
+    stats.seen++;
+    const fp = footprintOf(rec);
+    const t = now();
+    const last = fp ? lastByFp.get(fp.id) : undefined;
+    if (last !== undefined && t - last < dedupeMs) { stats.deduped++; return; }
+    if (fp) lastByFp.set(fp.id, t);
+    if (recorder.emit(rec)) stats.emitted++;
+  }
+  const onError = (ev) => {
+    try {
+      const e = ev?.error;
+      handle(e instanceof Error ? toRecord(e.name || 'Error', e.message, e.stack) : toRecord('Error', ev?.message ?? String(e ?? ''), ''));
+    } catch { /* never throw into the host */ }
+  };
+  const onRejection = (ev) => {
+    try {
+      const r = ev?.reason;
+      handle(r instanceof Error ? toRecord(r.name || 'Error', r.message, r.stack) : toRecord('UnhandledRejection', reasonMessage(r), ''));
+    } catch { /* never throw into the host */ }
+  };
+  target.addEventListener('error', onError);
+  target.addEventListener('unhandledrejection', onRejection);
+  return {
+    dispose() { target.removeEventListener('error', onError); target.removeEventListener('unhandledrejection', onRejection); },
+    stats() { return { ...stats }; },
+  };
+}

package/src/footprint.js

@@ -71,6 +71,62 @@ export function contextOfKey(key) {
   return out;
 }
 
+/** Scrub an error message down to its shape: quoted strings, hex ids and
+ *  numbers collapse to placeholders, whitespace and `|` (the key separator)
+ *  are normalized, and the result is capped so a huge message never bloats a
+ *  key. Two errors that differ only by which mesh id or how many ms are the
+ *  SAME cause once normalized. */
+export function normalizeErrorMessage(msg) {
+  return String(msg ?? '')
+    .replace(/(['"`])(?:\\.|(?!\1).)*\1/g, '"…"')
+    .replace(/0x[0-9a-f]{6,}/gi, '#')
+    .replace(/\b[0-9a-f]{6,}\b/gi, '#')
+    .replace(/\d+(\.\d+)?/g, '#')
+    .replace(/\s+/g, ' ')
+    .replace(/\|/g, '¦')
+    .trim()
+    .slice(0, 120);
+}
+
+/** `<path>#<function>` of the top stack frame, without origin, query, hash,
+ *  line or column — the site an error is thrown from, apart from which build
+ *  served it or which line the minifier put it on. */
+export function topFrameSite(stack) {
+  const lines = Array.isArray(stack) ? stack : String(stack ?? '').split('\n');
+  for (const raw of lines) {
+    const line = String(raw).trim();
+    let fn, loc;
+    if (line.startsWith('at ')) {
+      // V8/Chromium/Node: "at fn (loc)" | "at loc" | "at async fn (loc)" | "at new Cls (loc)"
+      const m = /^at (?:(.+?) \()?(.+?)\)?$/.exec(line);
+      if (!m) continue;
+      fn = m[1] ? m[1].replace(/^(?:async |new )+/, '') : '';
+      loc = m[2];
+    } else {
+      // SpiderMonkey/JavaScriptCore: "fn@loc" | "@loc" (anonymous). Half the
+      // players are on Firefox or Safari; without this their stacks parse to
+      // nothing and one bug becomes two catalogue rows.
+      const m = /^([^@]*)@((?:[a-z][a-z0-9+.-]*:)?\/\/?.+?:\d+(?::\d+)?)$/.exec(line);
+      if (!m) continue;
+      fn = m[1];
+      loc = m[2];
+    }
+    loc = loc.replace(/:\d+:\d+$/, '').replace(/:\d+$/, '');
+    try { const u = new URL(loc); loc = u.pathname; } catch { /* not a URL: a path */ }
+    loc = loc.replace(/[?#].*$/, '');
+    return `${loc}#${fn || 'anonymous'}`;
+  }
+  return 'unknown';
+}
+
+/** The site a server incident's top self-time frame names — `unattributed`
+ *  when attribution was turned off or the server sent no frames at all. */
+function serverSite(rec) {
+  const f = Array.isArray(rec.frames) ? rec.frames[0] : undefined;
+  if (rec.attribution === 'off' || !f) return 'unattributed';
+  return `${f.file ?? '?'}#${f.fn ?? 'anonymous'}`;
+}
+
 /** The verdict a record leads with, or 'unclassified'. */
 function topGuess(rec) {
   return rec.classification?.[0]?.guess ?? 'unclassified';
@@ -132,6 +188,12 @@ function baseKey(rec) {
     case 'gpu-settle':
       // Only a cap hit is an incident; a settled wait is verification evidence.
       return rec.settled === false ? `gpu-settle|${rec.tag ?? '?'}` : null;
+    case 'error':
+      return `error|${rec.source ?? 'client'}|${rec.name ?? 'Error'}|${normalizeErrorMessage(rec.message)}|${topFrameSite(rec.stack)}`;
+    case 'server-hitch':
+      return `server-hitch|${phase}|${serverSite(rec)}`;
+    case 'server-stall':
+      return `server-stall|${phase}|${serverSite(rec)}`;
     default:
       return null;
   }
@@ -152,11 +214,11 @@ export function footprintOf(rec) {
 export function describeFootprint(key) {
   const parts = String(key ?? '').split('|').filter((p) => !p.startsWith('ctx:'));
   const ctx = contextOfKey(key);
-  const d = describeBase(parts);
+  const d = describeBase(parts, String(key ?? ''));
   return { ...d, ctx };
 }
 
-function describeBase(parts) {
+function describeBase(parts, key) {
   const [type] = parts;
   switch (type) {
     case 'hitch': return { glyph: '⚡', label: `hitch · ${parts[2] ?? '?'}${parts[3] ? ` · ${parts[3].split(',').length} mint site(s)` : ''}`, phase: parts[1] ?? '?' };
@@ -165,6 +227,9 @@ function describeBase(parts) {
     case 'warm': return { glyph: '🔥', label: `warm · ${parts[1] ?? '?'} (${parts[2] ?? '?'})`, phase: parts[3] ?? '?' };
     case 'gpu-stall': return { glyph: '⏳', label: 'gpu-process stall', phase: parts[1] ?? '?' };
     case 'gpu-settle': return { glyph: '⏳', label: `gpu-settle cap hit · ${parts[1] ?? '?'}`, phase: '' };
+    case 'error': return { glyph: '✖', label: `error · ${parts[2] ?? '?'} · ${(parts[3] ?? '').slice(0, 60)}`, phase: '' };
+    case 'server-hitch': return { glyph: '▣', label: `server tick over budget · ${parts[2] ?? '?'}`, phase: parts[1] ?? '?' };
+    case 'server-stall': return { glyph: '▦', label: `event-loop stall · ${parts[2] ?? '?'}`, phase: parts[1] ?? '?' };
     default: return { glyph: '·', label: String(key ?? ''), phase: '' };
   }
 }

package/src/history.js

@@ -256,6 +256,9 @@ function worstOf(r) {
     case 'warm': return typeof r.worstBatchMs === 'number' ? { value: r.worstBatchMs, unit: 'ms' } : undefined;
     case 'gpu-stall': return typeof r.queueDoneMs === 'number' ? { value: r.queueDoneMs, unit: 'ms' } : undefined;
     case 'gpu-settle': return typeof r.ms === 'number' ? { value: r.ms, unit: 'ms' } : undefined;
+    case 'error': return undefined;
+    case 'server-hitch': return typeof r.tickMs === 'number' ? { value: r.tickMs, unit: 'ms' } : undefined;
+    case 'server-stall': return typeof r.p99Ms === 'number' ? { value: r.p99Ms, unit: 'ms' } : undefined;
     default: return undefined;
   }
 }

package/src/index.js

@@ -3,6 +3,8 @@ export { createRecorder } from './recorder.js';
 export { buildCensus } from './census.js';
 export { classifyHitch } from './classify.js';
 export { createMotionMonitor } from './motion.js';
+export { createErrorMonitor } from './errors.js';
+export { createCloudSink } from './cloud-sink.js';
 export { footprintOf, footprintKey, describeFootprint, canonicalContext, contextOfKey, FOOTPRINT_VERSION } from './footprint.js';
 export { buildHistory, summarizeWindow, buildFix, latestBuilds, buildIssues, agoText } from './history.js';
 export { createPanel } from './panel.js';

package/src/node/index.js

@@ -0,0 +1,164 @@
+// ============================================================
+// sloptimize/node — the game server's recorder (SPEC cloud §8.3)
+// ============================================================
+// Three signals, one ledger: a tick the host timed that overran its budget
+// (server-hitch), an event-loop stall the runtime saw on its own
+// (server-stall), and an uncaught error (error, source: server). Each is
+// attributed by the V8 sampler's top self-time frames, and shipped with the
+// same cloud sink the browser uses. Nothing here changes how the process
+// dies: only uncaughtExceptionMonitor is registered — never uncaughtException
+// or unhandledRejection, which would turn this recorder into part of the
+// crash path itself.
+import { createCloudSink } from '../cloud-sink.js';
+import { canonicalContext } from '../footprint.js';
+// Static import: monitorEventLoopDelay() is synchronous and cheap, and
+// createServerRuntime() must itself stay synchronous (callers do not await
+// it), so this cannot be a dynamic `await import('node:perf_hooks')`.
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+
+export function createServerRuntime(opts = {}) {
+  if (!opts.key) throw new Error('createServerRuntime: key is required');
+  if (!opts.endpoint) throw new Error('createServerRuntime: endpoint is required');
+  const tickBudgetMs = opts.tickBudgetMs ?? 16, stallMs = opts.stallMs ?? 50;
+  const phaseFn = opts.phase ?? (() => undefined), ctxFn = opts.context ?? (() => undefined);
+  const now = opts.now ?? (() => Date.now());
+  const proc = opts.process ?? process;
+  const setI = opts.setInterval ?? setInterval, clearI = opts.clearInterval ?? clearInterval;
+  const profileOn = opts.profile !== false;
+  let closed = false;
+
+  const pending = [];
+  const source = { drainRecords() { return pending.splice(0, pending.length); } };
+  const sink = createCloudSink({
+    key: opts.key, endpoint: opts.endpoint, build: opts.build, sources: [source], flushMs: opts.flushMs ?? 5000,
+    fetch: opts.fetch, sendBeacon: null, target: { addEventListener() {}, removeEventListener() {} }, setInterval: setI, clearInterval: clearI, now,
+  });
+
+  const stats = { hitches: 0, stalls: 0, errors: 0, droppedByRate: 0, hostErrors: 0 };
+  let lastHitchAt = -Infinity, lastStallAt = -Infinity;
+
+  // The profiler: injectable for tests (never touches node:inspector), or
+  // lazily imported for real use so the fake-profiler test path never loads
+  // the inspector module. `closed` is re-checked once the import (and the
+  // inspector session it builds) resolves, so a close() that races the lazy
+  // init stops the profiler instead of starting a session nobody will ever
+  // stop.
+  let profiler = opts.profiler ?? null;
+  let profilerReady = profileOn && profiler ? Promise.resolve(profiler.start()) : null;
+  if (profileOn && !profiler) {
+    profilerReady = import('./profiler.js')
+      .then(async (m) => {
+        if (closed) return;
+        const p = await m.createProfiler();
+        if (closed) { await p.stop?.(); return; }
+        profiler = p;
+        await profiler.start();
+      })
+      .catch((e) => { stats.profilerError = e?.message; profiler = null; });
+  }
+  async function frames() {
+    if (!profileOn) return { frames: [], attribution: 'off' };
+    try {
+      // Wait for the (possibly still-lazily-importing) profiler before
+      // deciding attribution is unavailable — otherwise every hitch/stall
+      // during startup is permanently recorded as attribution: 'off' even
+      // though the real profiler comes up moments later.
+      await profilerReady;
+      if (!profiler) return { frames: [], attribution: 'off' };
+      return { frames: await profiler.take(), attribution: 'profiler' };
+    } catch { return { frames: [], attribution: 'off' }; }
+  }
+  // Host-supplied phase()/context() callbacks run on every record; a
+  // throwing one must never break the record (or crash a bare setInterval
+  // callback) — it just leaves that field unset, counted in hostErrors.
+  function stamp(rec) {
+    try { const p = phaseFn(); if (p) rec.phase = p; } catch { stats.hostErrors++; }
+    try { const c = ctxFn(); if (c) rec.ctx = typeof c === 'string' ? c : canonicalContext(c); } catch { stats.hostErrors++; }
+    rec.at = new Date().toISOString();
+    return rec;
+  }
+  function pushAsync(rec, withFrames) {
+    // After close() the sink is disposed and nothing will ever drain `pending`
+    // again: a frame promise that resolves later must not grow it forever.
+    if (closed) return;
+    if (!withFrames) { pending.push(rec); return; }
+    frames().then((f) => {
+      if (closed) return;
+      rec.frames = f.frames; rec.attribution = f.attribution; pending.push(rec);
+    });
+  }
+
+  function endTick(startMs) {
+    try {
+      const tickMs = now() - startMs;
+      if (tickMs <= tickBudgetMs) return;
+      const t = now();
+      if (t - lastHitchAt < 1000) { stats.droppedByRate++; return; }
+      lastHitchAt = t; stats.hitches++;
+      const rec = stamp({ type: 'server-hitch', tickMs: +tickMs.toFixed(2), budgetMs: tickBudgetMs, frames: [], attribution: 'off' });
+      pushAsync(rec, profileOn);
+    } catch { stats.hostErrors++; }
+  }
+
+  // Event-loop delay: sampled every second, an incident when p99 crosses
+  // stallMs, rate-limited to one record per 5s.
+  const monitor = opts.monitor ?? monitorEventLoopDelay({ resolution: 20 });
+  monitor?.enable?.();
+  const sampler = setI(() => {
+    try {
+      if (!monitor) return;
+      const p99 = monitor.percentiles.get(99) / 1e6, p50 = monitor.percentiles.get(50) / 1e6, max = monitor.max / 1e6;
+      monitor.reset();
+      if (!(p99 > stallMs)) return;
+      const t = now();
+      if (t - lastStallAt < 5000) { stats.droppedByRate++; return; }
+      lastStallAt = t; stats.stalls++;
+      const rec = stamp({ type: 'server-stall', p50Ms: +p50.toFixed(1), p99Ms: +p99.toFixed(1), maxMs: +max.toFixed(1), frames: [], attribution: 'off' });
+      pushAsync(rec, profileOn);
+    } catch { stats.hostErrors++; }
+  }, 1000);
+  sampler?.unref?.();
+
+  const onUncaught = (err) => {
+    try {
+      stats.errors++;
+      const e = err instanceof Error ? err : new Error(String(err));
+      const stack = String(e.stack ?? '').split('\n').map((l) => l.trim()).filter((l) => l.startsWith('at ')).slice(0, 10);
+      pending.push(stamp({ type: 'error', source: 'server', name: e.name || 'Error', message: e.message, stack }));
+    } catch { /* never throw from a monitor */ }
+  };
+  proc.on('uncaughtExceptionMonitor', onUncaught);
+  // The watchdog timer must be unref'd too: Promise.race never cancels its
+  // losing arm, so a plain setTimeout here would itself become a handle
+  // that keeps a real host's event loop alive for up to 2s on every exit
+  // attempt (and, since that can make the loop look non-empty again,
+  // potentially re-trigger beforeExit indefinitely).
+  const onBeforeExit = () => {
+    Promise.race([sink.flush(), new Promise((r) => { const t = setTimeout(r, 2000); t?.unref?.(); })]).catch(() => {});
+  };
+  proc.on('beforeExit', onBeforeExit);
+
+  return {
+    tick(fn) { const s = now(); try { return fn(); } finally { endTick(s); } },
+    beginTick() { return now(); },
+    endTick,
+    mark(label, meta = {}) {
+      try { pending.push(stamp({ type: 'usermark', label, ...meta })); } catch { stats.hostErrors++; }
+    },
+    // Awaits one macrotask before draining the sink so that pushAsync's
+    // frame promise (resolved on a microtask, even for a synchronous fake
+    // profiler) has already landed its record in `pending`.
+    async flush() { await new Promise((r) => setTimeout(r, 0)); await sink.flush(); },
+    stats() { return { ...stats, sink: sink.stats() }; },
+    async close() {
+      closed = true;
+      clearI(sampler);
+      monitor?.disable?.();
+      proc.off?.('uncaughtExceptionMonitor', onUncaught);
+      proc.off?.('beforeExit', onBeforeExit);
+      await profiler?.stop?.();
+      await sink.flush();
+      sink.dispose();
+    },
+  };
+}

package/src/node/profiler.js

@@ -0,0 +1,63 @@
+// ============================================================
+// profiler.js — the V8 sampling profiler over node:inspector (SPEC cloud §8.3)
+// ============================================================
+// The V8 sampling profiler over the inspector protocol: started once, read
+// on demand. take() returns the top self-time frames since the last take and
+// restarts the sampler — the same "rolling window" attach.mjs uses in the
+// browser, here for the game server's own event loop.
+
+/** Pure fold of a Profiler.stop() result's `.profile` into the top 5
+ *  self-time frames as `{ file, fn, selfMs }`, keyed by (url, functionName).
+ *  Runtime/VM bookkeeping frames (root/program/gc/idle with no url) are
+ *  dropped, and any frame whose url contains `excludeUrl` (the profiler's
+ *  own module) is dropped so the recorder never attributes its own cost. */
+export function foldProfile(profile, excludeUrl) {
+  const byId = new Map((profile?.nodes ?? []).map((n) => [n.id, n]));
+  const selfUs = new Map();
+  const samples = profile?.samples ?? [], deltas = profile?.timeDeltas ?? [];
+  for (let i = 0; i < samples.length; i++) {
+    const n = byId.get(samples[i]); if (!n) continue;
+    const { functionName, url } = n.callFrame;
+    if (!url && /^\((root|program|garbage collector|idle)\)$/.test(functionName)) continue;
+    if (excludeUrl && url.includes(excludeUrl)) continue;
+    // NUL, not a space: getters fold as "get health" and real paths contain
+    // spaces, both of which a space-separated key would split in the wrong place.
+    const key = `${url}\u0000${functionName}`;
+    selfUs.set(key, (selfUs.get(key) ?? 0) + (deltas[i] ?? 0));
+  }
+  return [...selfUs.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([k, us]) => {
+    const [url, fn] = k.split('\u0000');
+    return { file: url.replace(/^file:\/\//, ''), fn: fn || 'anonymous', selfMs: Math.round(us / 1000) };
+  });
+}
+
+/** Wraps an inspector Session (real or injected) in start/take/stop. `take()`
+ *  stops the sampler, folds the profile, and immediately restarts it so the
+ *  window is continuous. Never throws into the host — callers treat a
+ *  rejected/absent profiler the same as attribution being off. */
+export async function createProfiler(opts = {}) {
+  const session = opts.session ?? new (await import('node:inspector')).Session();
+  const post = (m, p) => new Promise((res, rej) => session.post(m, p ?? {}, (e, r) => (e ? rej(e) : res(r))));
+  let running = false;
+  return {
+    async start() {
+      if (running) return;
+      session.connect?.();
+      await post('Profiler.enable');
+      await post('Profiler.setSamplingInterval', { interval: opts.intervalUs ?? 1000 });
+      await post('Profiler.start');
+      running = true;
+    },
+    async take() {
+      if (!running) return [];
+      const { profile } = await post('Profiler.stop');
+      await post('Profiler.start');
+      return foldProfile(profile, '/sloptimize/src/node/');
+    },
+    async stop() {
+      if (!running) return;
+      running = false;
+      try { await post('Profiler.stop'); await post('Profiler.disable'); } catch { /* already gone */ }
+    },
+  };
+}

package/src/recorder.js

@@ -43,6 +43,8 @@ export function createRecorder(opts = {}) {
   let sessionRecords = 0;
   let droppedSinceLast = 0;
   let lastRecordAt = -Infinity;
+  let lastPhase;   // most recent s.phase seen by frame(), for emit()'s stamping
+  let lastCtx;     // most recent s.ctx seen by frame(), for emit()'s stamping
 
   function sortedNonPaused(field, sinceIdx = 0) {
     const vals = [];
@@ -73,6 +75,8 @@ export function createRecorder(opts = {}) {
   return {
     /** One frame's numbers. Zero-allocation on the steady path. */
     frame(s) {
+      if (s.phase) lastPhase = s.phase;
+      if (s.ctx) lastCtx = s.ctx;
       const idx = head;
       for (const f of FIELDS) lanes[f][idx] = s[f] ?? 0;
       pausedLane[idx] = s.paused ? 1 : 0;
@@ -229,6 +233,19 @@ export function createRecorder(opts = {}) {
       return mark;
     },
 
+    /** Append an externally built incident (errors, host-detected events). Same session cap as hitches. */
+    emit(rec) {
+      if (!rec || typeof rec !== 'object') return false;
+      if (sessionRecords >= MAX_RECORDS_PER_SESSION) { droppedSinceLast++; return false; }
+      sessionRecords++;
+      if (!rec.at) rec.at = new Date().toISOString();
+      if (rec.phase === undefined && lastPhase) rec.phase = lastPhase;
+      if (rec.ctx === undefined && lastCtx) rec.ctx = lastCtx;
+      if (droppedSinceLast > 0) { rec.droppedSinceLast = droppedSinceLast; droppedSinceLast = 0; }
+      records.push(rec);
+      return true;
+    },
+
     /** Hand back accumulated records and clear — the host owns transport. */
     drainRecords() { const r = records; records = []; return r; },
   };