harnery 0.8.0 → 0.10.0

package/src/commands/harness.ts

@@ -0,0 +1,147 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import {
+  type BenchResult,
+  createBuiltinHarnessRegistry,
+  type HarnessBenchReport,
+  runHarnessBench,
+} from "../core/harnesses/index.ts";
+import type { HarnessProfile } from "../core/harnesses/types.ts";
+
+interface FormatOpts {
+  json?: boolean;
+}
+
+interface BenchOpts extends FormatOpts {
+  requireInstalled?: boolean;
+}
+
+const registry = createBuiltinHarnessRegistry();
+
+export function registerHarnessCommand(program: Command, emit: EmitContext): void {
+  const command = program
+    .command("harness")
+    .description("Inspect registered harness capabilities and run their conformance bench.");
+
+  command
+    .command("list")
+    .description("List registered harness adapters and their high-signal capability claims.")
+    .option("--json", "Machine-readable profile catalog")
+    .action((opts: FormatOpts) => {
+      const profiles = registry.list().map((adapter) => adapter.profile);
+      if (opts.json) {
+        emit.config({ format: "json" });
+        emit.data({ harnesses: profiles });
+      } else {
+        emit.text(renderProfileTable(profiles));
+      }
+    });
+
+  command
+    .command("show <id>")
+    .description("Show one harness's complete capability declaration.")
+    .option("--json", "Machine-readable profile")
+    .action((id: string, opts: FormatOpts) => {
+      const adapter = registry.get(id);
+      if (!adapter) {
+        emit.error({
+          code: "unknown_harness",
+          message: `unknown harness ${JSON.stringify(id)} (registered: ${registry.ids().join(", ")})`,
+        });
+        emit.setExitCode(1);
+        return;
+      }
+      if (opts.json) {
+        emit.config({ format: "json" });
+        emit.data(adapter.profile);
+      } else {
+        emit.text(renderProfile(adapter.profile));
+      }
+    });
+
+  command
+    .command("bench [harnesses...]")
+    .description("Run the offline adapter-contract bench (no model calls); drift exits non-zero.")
+    .option("--require-installed", "Also fail when a registered vendor CLI is missing")
+    .option("--json", "Machine-readable conformance report")
+    .action((harnesses: string[], opts: BenchOpts) => {
+      try {
+        const report = runHarnessBench(registry, { harnesses });
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(report);
+        } else {
+          emit.text(renderBenchReport(report));
+        }
+        emit.setExitCode(report.drift || (opts.requireInstalled && report.skipped) ? 1 : 0);
+      } catch (error) {
+        emit.error({ code: "harness_bench_failed", message: (error as Error).message });
+        emit.setExitCode(1);
+      }
+    });
+}
+
+export function renderProfileTable(profiles: readonly HarnessProfile[]): string {
+  const rows = profiles.map((profile) => [
+    profile.id,
+    profile.binary,
+    profile.capabilities.modelSelection.support,
+    profile.capabilities.effortSelection.support,
+    profile.capabilities.sessionId.support,
+    profile.capabilities.cost.support,
+  ]);
+  return renderTable(["HARNESS", "BINARY", "MODEL", "EFFORT", "SESSION", "COST"], rows);
+}
+
+export function renderProfile(profile: HarnessProfile): string {
+  const lines = [
+    `${profile.displayName} (${profile.id})`,
+    `binary: ${profile.binary}`,
+    `integration: ${profile.integrationMode}`,
+    `auth: ${profile.authModel}`,
+    `model family: ${profile.modelFamily}`,
+    `effort values: ${profile.effortValues.join(", ") || "none"}`,
+    profile.verified
+      ? `verified: ${profile.verified.date} (${profile.verified.version})`
+      : "verified: not recorded",
+    "",
+    "capabilities:",
+  ];
+  for (const [dimension, claim] of Object.entries(profile.capabilities)) {
+    lines.push(`  ${dimension.padEnd(18)} ${claim.support}${claim.note ? ` — ${claim.note}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderBenchReport(report: HarnessBenchReport): string {
+  const rows = report.results.map((result) => [
+    result.harness,
+    result.dimension,
+    result.declared,
+    result.observed,
+    result.verdict,
+  ]);
+  const table = renderTable(["HARNESS", "DIMENSION", "DECLARED", "OBSERVED", "VERDICT"], rows);
+  const summary = Object.entries(report.summary)
+    .filter(([, count]) => count > 0)
+    .map(([verdict, count]) => `${verdict}=${count}`)
+    .join(", ");
+  return `${table}\n\nmode: ${report.mode} (no model calls)\n${summary}`;
+}
+
+function renderTable(headers: string[], rows: string[][]): string {
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)),
+  );
+  const line = (cells: string[]) =>
+    cells
+      .map((cell, index) => cell.padEnd(widths[index]))
+      .join("  ")
+      .trimEnd();
+  return [line(headers), line(widths.map((width) => "-".repeat(width))), ...rows.map(line)].join(
+    "\n",
+  );
+}
+
+/** Kept exported so command tests can assert row semantics without model calls. */
+export type { BenchResult };

package/src/commands/init.ts

@@ -120,6 +120,17 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
         if (stamp) actions.push(stamp);
       }
 
+      // ── 1c. workflow billing default ───────────────────────────────────────
+      // Every init'd project gets `workflow.subscriptionOnly: true`: workflow
+      // children ride the logged-in (subscription) harness auth, and the pin
+      // makes per-token API billing structurally impossible unless the project
+      // deliberately flips it. A committed `workflow` key of any shape is a
+      // deliberate choice and is never touched.
+      {
+        const stamp = stampWorkflowDefaults(resolve(coordDir, "config.jsonc"), dryRun);
+        if (stamp) actions.push(stamp);
+      }
+
       // ── 2. harness hooks ───────────────────────────────────────────────────
       const settingsPath = resolve(projectRoot, spec.settingsFile);
       const agentHook = relative(projectRoot, resolve(HARNERY_ROOT, "bin", "agent-hook"));
@@ -139,23 +150,23 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
       } else {
         settings = {};
       }
-      const { wired, already, removed } = wireHooks(settings, spec, agentHook, harness);
+      const { wired, already, removed, upgraded } = wireHooks(settings, spec, agentHook, harness);
 
-      if (wired === 0 && removed === 0) {
+      if (wired === 0 && removed === 0 && upgraded === 0) {
         actions.push(
           `· all ${spec.events.length} ${harness} hooks already wired in ${rel(projectRoot, settingsPath)}`,
         );
       } else if (dryRun) {
         actions.push(
-          `+ would wire ${wired} hook(s) and remove ${removed} legacy hook(s) in ` +
-            `${rel(projectRoot, settingsPath)} (${already} already present)`,
+          `+ would wire ${wired} hook(s), upgrade ${upgraded} stale command(s), and remove ` +
+            `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`,
         );
       } else {
         mkdirSync(dirname(settingsPath), { recursive: true });
         writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
         actions.push(
-          `+ wired ${wired} hook(s) and removed ${removed} legacy hook(s) in ` +
-            `${rel(projectRoot, settingsPath)} (${already} already present)`,
+          `+ wired ${wired} hook(s), upgraded ${upgraded} stale command(s), and removed ` +
+            `${removed} legacy hook(s) in ${rel(projectRoot, settingsPath)} (${already} already present)`,
         );
       }
 
@@ -169,11 +180,12 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
 
 /**
  * Merge agent-hook entries into a harness settings object in place, idempotently.
- * Preserves every existing hook; skips events already wired to
- * `agent-hook <subcommand>`. Honors the harness's entry shape (Claude/Codex nest
- * under an inner `hooks` array; Cursor uses a flat `{ command }`) and ensures the
- * root `version` key when the harness requires one. Pure (no fs/git) so it's
- * unit-testable.
+ * Preserves every existing hook; rewrites events already wired to
+ * `agent-hook <subcommand>` when their command string is stale (e.g. an older
+ * harnery wired a bare relative path). Honors the harness's entry shape
+ * (Claude/Codex nest under an inner `hooks` array; Cursor uses a flat
+ * `{ command }`) and ensures the root `version` key when the harness requires
+ * one. Pure (no fs/git) so it's unit-testable.
  *
  * The trailing space in the match (`agent-hook ${subcommand} `) is load-bearing:
  * it keeps `stop` from matching `stop-failure`.
@@ -183,7 +195,7 @@ export function wireHooks(
   spec: HarnessSpec,
   agentHookPath: string,
   harness: HarnessId,
-): { wired: number; already: number; removed: number } {
+): { wired: number; already: number; removed: number; upgraded: number } {
   if (spec.rootVersion !== undefined && settings.version === undefined) {
     settings.version = spec.rootVersion;
   }
@@ -191,6 +203,7 @@ export function wireHooks(
   let wired = 0;
   let already = 0;
   let removed = 0;
+  let upgraded = 0;
   for (const { settingsKey, subcommand } of spec.legacyEvents ?? []) {
     const groups = settings.hooks[settingsKey] ?? [];
     const kept = groups.filter(
@@ -202,11 +215,14 @@ export function wireHooks(
     else settings.hooks[settingsKey] = kept;
   }
   for (const { settingsKey, subcommand } of spec.events) {
-    const command = `bash ${agentHookPath} ${subcommand} --harness ${harness}`;
+    const command = hookCommand(spec, agentHookPath, subcommand, harness);
     const groups = settings.hooks[settingsKey] ?? [];
-    const present = groups.some((g) =>
-      groupCommands(g).some((c) => commandWiresSubcommand(c, subcommand)),
-    );
+    let present = false;
+    for (const group of groups) {
+      upgraded += rewriteStaleCommands(group, subcommand, command, () => {
+        present = true;
+      });
+    }
     if (present) {
       already++;
       continue;
@@ -215,7 +231,62 @@ export function wireHooks(
     settings.hooks[settingsKey] = groups;
     wired++;
   }
-  return { wired, already, removed };
+  return { wired, already, removed, upgraded };
+}
+
+/**
+ * The canonical hook command for one event. When the harness exports a
+ * project-dir env var to hook processes (Claude Code's CLAUDE_PROJECT_DIR),
+ * anchor the agent-hook path on it: hook processes inherit the session
+ * shell's cwd, which follows `cd` away from the project root — a bare
+ * relative path silently fails to spawn from there (no events, no image
+ * capture, no guards). `:-.` keeps the command working on harness versions
+ * that don't set the var. Only the env expansion is quoted so the
+ * `agent-hook <subcommand> ` wiring match stays byte-identical.
+ */
+function hookCommand(
+  spec: HarnessSpec,
+  agentHookPath: string,
+  subcommand: string,
+  harness: HarnessId,
+): string {
+  const anchor = spec.projectDirEnv ? `"\${${spec.projectDirEnv}:-.}"/` : "";
+  return `bash ${anchor}${agentHookPath} ${subcommand} --harness ${harness}`;
+}
+
+/**
+ * Rewrite any harnery-owned command for `subcommand` inside one hook group to
+ * the canonical form, in place. Returns the number of commands rewritten and
+ * calls `onPresent` when the subcommand is wired in this group at all.
+ */
+function rewriteStaleCommands(
+  group: HookGroup,
+  subcommand: string,
+  canonical: string,
+  onPresent: () => void,
+): number {
+  let rewritten = 0;
+  if ("command" in group && typeof group.command === "string") {
+    if (commandWiresSubcommand(group.command, subcommand)) {
+      onPresent();
+      if (group.command !== canonical) {
+        group.command = canonical;
+        rewritten++;
+      }
+    }
+  }
+  if ("hooks" in group && Array.isArray(group.hooks)) {
+    for (const hook of group.hooks) {
+      if (typeof hook.command !== "string") continue;
+      if (!commandWiresSubcommand(hook.command, subcommand)) continue;
+      onPresent();
+      if (hook.command !== canonical) {
+        hook.command = canonical;
+        rewritten++;
+      }
+    }
+  }
+  return rewritten;
 }
 
 /**
@@ -311,6 +382,56 @@ export function stampBinName(configPath: string, binName: string, dryRun: boolea
   return `+ added binName "${binName}" to ${rel(configPath)}`;
 }
 
+/** The commented workflow-billing default block init stamps into config.jsonc. */
+const WORKFLOW_DEFAULT_BLOCK =
+  `  // Workflow children ride the logged-in (subscription) harness auth; this pin\n` +
+  `  // scrubs API-key vars from child envs so runs can never bill per-token rates.\n` +
+  `  // Key-only hosts (CI): set false, or HARNERY_WORKFLOW_SUBSCRIPTION_ONLY=0.\n` +
+  `  "workflow": { "subscriptionOnly": true }`;
+
+/**
+ * Idempotently pin `workflow.subscriptionOnly: true` in `.harnery/config.jsonc`
+ * (see `workflowSubscriptionOnly()` in core/config.ts and the `workflow run`
+ * billing safeguards). Same comment-preserving discipline as `stampBinName`.
+ * A `workflow` key of ANY shape (including `subscriptionOnly: false`) is a
+ * deliberate project choice and is left alone.
+ */
+export function stampWorkflowDefaults(configPath: string, dryRun: boolean): string | null {
+  const rel = (p: string) => relative(dirname(dirname(configPath)), p) || p;
+
+  if (!existsSync(configPath)) {
+    if (dryRun) return `+ would pin workflow.subscriptionOnly in ${rel(configPath)}`;
+    writeFileSync(configPath, `{\n${WORKFLOW_DEFAULT_BLOCK}\n}\n`);
+    return `+ pinned workflow.subscriptionOnly: true in ${rel(configPath)}`;
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: { workflow?: unknown } & Record<string, unknown>;
+  try {
+    parsed = (JSON.parse(stripJsonComments(raw)) as typeof parsed) ?? {};
+  } catch {
+    return `· ${rel(configPath)} isn't valid JSONC; skipped workflow.subscriptionOnly pin`;
+  }
+
+  if ("workflow" in parsed) return null; // deliberate config; never touch
+
+  const at = firstBraceIndex(raw);
+  if (at < 0) return `· ${rel(configPath)} has no object literal; skipped workflow pin`;
+  const keys = Object.keys(parsed);
+  const next =
+    keys.length === 0
+      ? `{\n${WORKFLOW_DEFAULT_BLOCK}\n}\n`
+      : `${raw.slice(0, at + 1)}\n${WORKFLOW_DEFAULT_BLOCK},${raw.slice(at + 1)}`;
+  if (dryRun) return `+ would pin workflow.subscriptionOnly in ${rel(configPath)}`;
+  writeFileSync(configPath, next);
+  return `+ pinned workflow.subscriptionOnly: true in ${rel(configPath)}`;
+}
+
 /** Index of the first structural `{`, skipping leading whitespace + comments. */
 function firstBraceIndex(raw: string): number {
   let i = 0;

package/src/commands/presence.ts

@@ -1,11 +1,19 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
+import { monorepoRoot } from "../core/agents/coord-client.ts";
 import {
   emitCanonical,
   normalizeHarness,
   readHeartbeat,
   resolveOwner,
 } from "../core/agents/index.ts";
+import {
+  fetchPresence,
+  publishPresence,
+  readRemoteMachines,
+  relayDaemonStatus,
+  runRelayDaemon,
+} from "../core/presence/index.ts";
 import {
   ageSeconds,
   applyDetection,
@@ -18,17 +26,24 @@ import {
 } from "../lib/presence.ts";
 
 /**
- * `presence`: mobile/office state for agents (~/.claude/presence).
+ * `presence`: two related surfaces under one name.
+ *
+ *   1. Mobile/office state for agents (~/.claude/presence): get / set /
+ *      clear / detect. The state file path is Claude-Code-specific but the
+ *      logic is generic.
+ *   2. Cross-machine session presence (ADR 0016): publish / fetch / peers —
+ *      the git-refs transport that lets sessions on other machines show up
+ *      in the peer table via `refs/harnery/presence/<machine>` on origin.
  *
  * Uses the injected EmitContext so composed and standalone consumers share
- * one code path. The state file path is Claude-Code-specific (lives under
- * ~/.claude/) but the detect/set/clear logic is generic: any agent harness
- * can adopt the same convention.
+ * one code path.
  */
 export function registerPresenceCommand(program: Command, emit: EmitContext): void {
   const cmd = program
     .command("presence")
-    .description("Mobile/office state for agents (~/.claude/presence)")
+    .description(
+      "Presence: mobile/office state (get/set/clear/detect) + cross-machine session presence (publish/fetch/peers)",
+    )
     .action(() => {
       printStatus(emit);
     });
@@ -83,6 +98,88 @@ export function registerPresenceCommand(program: Command, emit: EmitContext): vo
       });
     });
 
+  // ---- cross-machine session presence (ADR 0016) ----
+
+  cmd
+    .command("publish")
+    .description(
+      "Publish this machine's live sessions to refs/harnery/presence/<machine> on origin. " +
+        "Change-batched with a keepalive; --force pushes regardless. Synchronous (errors report).",
+    )
+    .option("--force", "Push even if unchanged / within throttle windows")
+    .action((opts: { force?: boolean }) => {
+      const root = requireRoot(emit);
+      const r = publishPresence(root, { force: opts.force, sync: true });
+      if (r.status === "error") {
+        emit.error({ code: "publish_failed", message: r.error });
+        process.exit(1);
+      }
+      emit.data(r);
+    });
+
+  cmd
+    .command("fetch")
+    .description(
+      "Fetch peer machines' presence refs from origin (throttled; --force bypasses). Synchronous.",
+    )
+    .option("--force", "Fetch even within the throttle interval")
+    .action((opts: { force?: boolean }) => {
+      const root = requireRoot(emit);
+      const r = fetchPresence(root, { force: opts.force, sync: true });
+      if (r.status === "error") {
+        emit.error({ code: "fetch_failed", message: r.error });
+        process.exit(1);
+      }
+      emit.data(r);
+    });
+
+  cmd
+    .command("relay-daemon")
+    .description(
+      "Run the relay client daemon in the foreground (normally spawned detached by the hooks " +
+        "when presence.relay is configured; holds the WebSocket, publishes on heartbeat change, " +
+        "caches peers' blobs for the renderers, exits when the machine goes idle).",
+    )
+    .action(async () => {
+      const root = requireRoot(emit);
+      process.exit(await runRelayDaemon(root));
+    });
+
+  cmd
+    .command("peers")
+    .description(
+      "Show sessions on other machines (merged from presence refs + the relay daemon's cache)",
+    )
+    .option("--json", "JSON output")
+    .option("--stale", "Include machines past the stale window")
+    .action((opts: { json?: boolean; stale?: boolean }) => {
+      const root = requireRoot(emit);
+      const machines = readRemoteMachines(root, { includeStale: opts.stale });
+      const daemon = relayDaemonStatus(root);
+      if (opts.json) emit.config({ format: "json" });
+      if (opts.json || !process.stdout.isTTY) {
+        emit.data({ machines, relay_daemon: daemon });
+        return;
+      }
+      emit.text(
+        daemon.running
+          ? `relay daemon: running (pid ${daemon.pid}, ${daemon.url})\n`
+          : "relay daemon: not running (git-refs transport only)\n",
+      );
+      if (machines.length === 0) {
+        emit.text("no remote sessions known (try `presence fetch --force`)\n");
+        return;
+      }
+      for (const m of machines) {
+        emit.text(`${m.machine}  (published ${formatAge(m.age_secs)} ago)\n`);
+        for (const a of m.agents) {
+          const task = a.task ? `  "${a.task.slice(0, 70)}"` : "";
+          const files = a.files_touched?.length ? `  [${a.files_touched.length} files]` : "";
+          emit.text(`  agent-${a.name ?? a.instance_id.slice(0, 8)}${task}${files}\n`);
+        }
+      }
+    });
+
   cmd
     .command("detect")
     .description(
@@ -111,6 +208,15 @@ export function registerPresenceCommand(program: Command, emit: EmitContext): vo
     });
 }
 
+function requireRoot(emit: EmitContext): string {
+  const root = monorepoRoot();
+  if (!root) {
+    emit.error({ code: "not_in_repo", message: "coord root not found (no .harnery/ upward)" });
+    process.exit(1);
+  }
+  return root;
+}
+
 function printStatus(emit: EmitContext): void {
   const r = readPresence();
   emit.data({

package/src/commands/relay.ts

@@ -0,0 +1,160 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import { MAX_FRAME_BYTES } from "../core/presence/relay-protocol.ts";
+
+/**
+ * `relay serve`: the Bun self-host of the presence relay (ADR 0016 phase 2).
+ * Same wire protocol as the Cloudflare Durable Objects host in relay/worker/ —
+ * one in-memory room per opaque room id, warm-join cache, fan-out, rate
+ * limits. For teams who'd rather run their own box than use the public
+ * relay.harnery.com; point clients at it via `.harnery/config.jsonc` →
+ * `{ "presence": { "relay": "ws://host:port" } }`.
+ *
+ * Bun-only (Bun.serve WebSockets), like `harn tunnel` — fails fast with a
+ * clear message on a Bun-free host.
+ */
+
+const MAX_SOCKETS_PER_ROOM = 64;
+const RATE_BURST = 10;
+const RATE_REFILL_MS = 2000;
+const CACHE_TTL_MS = 15 * 60 * 1000;
+const ROOM_ID_RE = /^[0-9a-f]{32}$/;
+
+interface RoomState {
+  sockets: Set<unknown>;
+  cache: Map<string, { raw: string; at: number }>;
+}
+
+interface SocketData {
+  roomId: string;
+  bucketTokens: number;
+  bucketAt: number;
+}
+
+/** Start the relay server. Exported for in-process integration tests. */
+export function startRelayServer(port: number): { port: number; stop: () => void } {
+  if (typeof Bun === "undefined" || typeof Bun.serve !== "function") {
+    throw new Error("relay serve requires Bun (Bun.serve WebSockets)");
+  }
+  const rooms = new Map<string, RoomState>();
+
+  const roomOf = (roomId: string): RoomState => {
+    let r = rooms.get(roomId);
+    if (!r) {
+      r = { sockets: new Set(), cache: new Map() };
+      rooms.set(roomId, r);
+    }
+    return r;
+  };
+
+  const server = Bun.serve<SocketData>({
+    port,
+    fetch(req, srv) {
+      const url = new URL(req.url);
+      if (url.pathname === "/" || url.pathname === "/healthz") {
+        return Response.json({ ok: true, service: "harnery-presence-relay", v: 1 });
+      }
+      const m = /^\/v1\/room\/([0-9a-f]{32})$/.exec(url.pathname);
+      if (!m || !ROOM_ID_RE.test(m[1]!)) return new Response("not found", { status: 404 });
+      const room = roomOf(m[1]!);
+      if (room.sockets.size >= MAX_SOCKETS_PER_ROOM) {
+        return new Response("room full", { status: 429 });
+      }
+      const ok = srv.upgrade(req, {
+        data: { roomId: m[1]!, bucketTokens: RATE_BURST, bucketAt: Date.now() },
+      });
+      return ok ? undefined : new Response("expected websocket", { status: 426 });
+    },
+    websocket: {
+      open(ws) {
+        const room = roomOf(ws.data.roomId);
+        room.sockets.add(ws);
+        const now = Date.now();
+        for (const [sender, entry] of room.cache) {
+          if (now - entry.at > CACHE_TTL_MS) {
+            room.cache.delete(sender);
+            continue;
+          }
+          ws.send(entry.raw);
+        }
+        ws.send(JSON.stringify({ t: "hello", peers: room.sockets.size }));
+      },
+      message(ws, message) {
+        if (typeof message !== "string" || message.length > MAX_FRAME_BYTES) return;
+        // Rate limit (token bucket per socket).
+        const d = ws.data;
+        const now = Date.now();
+        const refill = Math.floor((now - d.bucketAt) / RATE_REFILL_MS);
+        if (refill > 0) {
+          d.bucketTokens = Math.min(RATE_BURST, d.bucketTokens + refill);
+          d.bucketAt = now;
+        }
+        if (d.bucketTokens <= 0) return;
+        d.bucketTokens -= 1;
+
+        let frame: { t?: unknown; sender?: unknown };
+        try {
+          frame = JSON.parse(message) as typeof frame;
+        } catch {
+          return;
+        }
+        if (
+          frame.t !== "pub" ||
+          typeof frame.sender !== "string" ||
+          !/^[0-9a-f]+$/.test(frame.sender) ||
+          frame.sender.length > 64
+        ) {
+          return;
+        }
+        const room = roomOf(d.roomId);
+        room.cache.set(frame.sender, { raw: message, at: now });
+        for (const peer of room.sockets) {
+          if (peer === ws) continue;
+          try {
+            (peer as { send(m: string): void }).send(message);
+          } catch {
+            /* dead socket */
+          }
+        }
+      },
+      close(ws) {
+        const room = rooms.get(ws.data.roomId);
+        if (!room) return;
+        room.sockets.delete(ws);
+        if (room.sockets.size === 0 && room.cache.size === 0) rooms.delete(ws.data.roomId);
+      },
+    },
+  });
+
+  return {
+    port: server.port ?? port,
+    stop: () => server.stop(true),
+  };
+}
+
+export function registerRelayCommand(program: Command, emit: EmitContext): void {
+  const cmd = program
+    .command("relay")
+    .description("Self-host the presence relay (see also relay/worker/ for the Cloudflare host)");
+
+  cmd
+    .command("serve")
+    .description(
+      "Run the presence relay on this machine (Bun-only; same protocol as relay/worker/)",
+    )
+    .option("--port <n>", "Port to listen on", "8787")
+    .action((opts: { port: string }) => {
+      let server: { port: number; stop: () => void };
+      try {
+        server = startRelayServer(Number.parseInt(opts.port, 10));
+      } catch (e) {
+        emit.error({
+          code: "relay_serve_failed",
+          message: e instanceof Error ? e.message : String(e),
+        });
+        process.exit(1);
+      }
+      emit.log(`presence relay listening on :${server.port} (ws path: /v1/room/<room-id>)`, "info");
+      // Foreground service: run until interrupted.
+    });
+}