codehost 0.16.0 → 0.17.0

package/src/shared/repo.ts

@@ -173,26 +173,66 @@ export interface Resolution {
   peerId: string;
   /** Folder to open via ?folder= (root kind); undefined opens the repo as-is. */
   folder?: string;
+  /** The folder is a checkout the daemon *enumerated* (it exists on disk), not
+   *  an optimistic layout-synthesized path — rank it like an exact match. */
+  exact?: boolean;
+}
+
+/** Machine preference (from history) used to break ties between matches. */
+export interface ResolvePrefs {
+  /** Stable machine id — prefer servers advertising it. */
+  hostId?: string;
+  /** Hostname fallback for pre-hostId daemons/entries. */
+  host?: string;
+}
+
+function prefers(meta: PeerMeta | null | undefined, prefer?: ResolvePrefs): boolean {
+  if (!prefer || !meta) return false;
+  if (prefer.hostId && meta.hostId) return meta.hostId === prefer.hostId;
+  return !!prefer.host && meta.host === prefer.host;
 }
 
 /**
  * Pick the best live server for a repo deep link. Prefers an exact `repo`
  * daemon; otherwise falls back to a `root` daemon that can open the subfolder.
- * Among several roots, prefers the **deepest** (longest cwd) — with a nested
- * setup like /Users/sno and /Users/sno/ws both serving, the layout subfolder
- * exists under the deeper one (observed: /gh/snomiao/codehost belongs to
- * /Users/sno/ws/..., not /Users/sno/...). Returns null if nothing matches.
+ * Ties (several repo daemons, or several roots) break toward the machine in
+ * `prefer` — the one history says served this repo last. Among several roots,
+ * then prefers the **deepest** (longest cwd) — with a nested setup like
+ * /Users/sno and /Users/sno/ws both serving, the layout subfolder exists under
+ * the deeper one (observed: /gh/snomiao/codehost belongs to /Users/sno/ws/...,
+ * not /Users/sno/...). Returns null if nothing matches.
  */
-export function resolveRepoTarget(servers: PeerInfo[], target: RepoTarget): Resolution | null {
+export function resolveRepoTarget(
+  servers: PeerInfo[],
+  target: RepoTarget,
+  prefer?: ResolvePrefs,
+): Resolution | null {
   const key = repoKey(target);
-  const repoMatch = servers.find(
+  const repoMatches = servers.filter(
     (s) => s.meta?.kind !== "root" && s.meta?.repo === key && branchOk(s.meta, target),
   );
+  const repoMatch = repoMatches.find((s) => prefers(s.meta, prefer)) ?? repoMatches[0];
   if (repoMatch) return { peerId: repoMatch.peerId };
 
-  const root = servers
+  const roots = servers
     .filter((s) => s.meta?.kind === "root")
-    .sort((a, b) => (b.meta?.cwd.length ?? 0) - (a.meta?.cwd.length ?? 0))[0];
+    .sort(
+      (a, b) =>
+        Number(prefers(b.meta, prefer)) - Number(prefers(a.meta, prefer)) ||
+        (b.meta?.cwd.length ?? 0) - (a.meta?.cwd.length ?? 0),
+    );
+
+  // A root that *enumerated* a matching checkout knows it exists on disk —
+  // rank it exact, ahead of any synthesized fallback.
+  const wantBranch = target.branch || DEFAULT_BRANCH;
+  for (const s of roots) {
+    const ws = s.meta?.workspaces?.find(
+      (w) => w.repo === key && (!w.branch || w.branch === wantBranch),
+    );
+    if (ws) return { peerId: s.peerId, folder: ws.path, exact: true };
+  }
+
+  const root = roots[0];
   if (root && root.meta) {
     const folder = `${trimSlash(root.meta.cwd)}/${fillLayout(root.meta.layout || DEFAULT_LAYOUT, target)}`;
     return { peerId: root.peerId, folder };
@@ -204,13 +244,20 @@ export function resolveRepoTarget(servers: PeerInfo[], target: RepoTarget): Reso
  *  to `target.host` when the link carries one (a bare path is ambiguous across
  *  machines). Compares with leading + trailing slashes stripped: `parseDeepLink`
  *  forces a leading "/" on the path, but a served cwd may lack one (e.g. an
- *  `expose` server's `localhost:<port>`), so a trailing-only trim never matches. */
+ *  `expose` server's `localhost:<port>`), so a trailing-only trim never matches.
+ *  A root daemon whose *advertised workspaces* include the path matches too —
+ *  that's how directories registered with the host daemon resolve. */
 export function resolveDevTarget(servers: PeerInfo[], target: DevTarget): Resolution | null {
   const want = stripEnds(target.path);
-  const hit = servers.find(
-    (s) => s.meta && stripEnds(s.meta.cwd) === want && (!target.host || s.meta.host === target.host),
-  );
-  return hit ? { peerId: hit.peerId } : null;
+  const hostOk = (meta: PeerMeta) => !target.host || meta.host === target.host;
+  const hit = servers.find((s) => s.meta && stripEnds(s.meta.cwd) === want && hostOk(s.meta));
+  if (hit) return { peerId: hit.peerId };
+  for (const s of servers) {
+    if (!s.meta || !hostOk(s.meta)) continue;
+    const ws = s.meta.workspaces?.find((w) => stripEnds(w.path) === want);
+    if (ws) return { peerId: s.peerId, folder: ws.path, exact: true };
+  }
+  return null;
 }
 
 /** A candidate room (its token) plus how the deep link resolved within it. */
@@ -221,14 +268,15 @@ export interface RoomMatch {
 
 /**
  * Rank matches found while searching multiple rooms for a token-less deep link.
- * An *exact* match (a server that genuinely serves this repo/folder — no
- * synthesized `folder`) beats a *root fallback* (a root daemon that would open
- * the repo as a subfolder, which `resolveRepoTarget` returns for ANY repo link).
- * Without this preference, first-responder-wins could pick an unrelated room
- * that merely has a root server. Returns null when there are no matches.
+ * An *exact* match (a server that genuinely serves this repo/folder — a repo
+ * daemon, or a root whose enumerated checkout matched) beats a *root fallback*
+ * (a root daemon that would open the repo as a synthesized subfolder, which
+ * `resolveRepoTarget` returns for ANY repo link). Without this preference,
+ * first-responder-wins could pick an unrelated room that merely has a root
+ * server. Returns null when there are no matches.
  */
 export function pickRoomMatch(matches: RoomMatch[]): RoomMatch | null {
-  return matches.find((m) => !m.resolution.folder) ?? matches[0] ?? null;
+  return matches.find((m) => !m.resolution.folder || m.resolution.exact) ?? matches[0] ?? null;
 }
 
 function branchOk(meta: PeerMeta, target: RepoTarget): boolean {

package/src/shared/signaling-client.ts

@@ -161,6 +161,16 @@ export class SignalingClient {
     this.ws?.send(JSON.stringify(msg));
   }
 
+  /** Replace the advertised metadata: a live socket pushes it to the room now,
+   *  and every future (re)connect's `hello` carries it. */
+  updateMeta(meta: PeerMeta): void {
+    this.opts.meta = meta;
+    if (this.ws?.readyState === 1 /* OPEN */) {
+      const msg: ClientMessage = { type: "meta", meta };
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
   close(): void {
     this.closed = true;
     this.stopHeartbeat();

package/src/shared/signaling.ts

@@ -4,6 +4,34 @@
 
 export type Role = "server" | "viewer";
 
+/** One live agent CLI session on the daemon's machine (sourced from agent-yes's
+ *  registry) — advertised so clients can see which agents run where. Interact
+ *  with it over the tunnel's `/__codehost/agent-yes/*` proxy. */
+export interface AgentInfo {
+  pid: number;
+  /** CLI the agent runs, e.g. "claude", "codex". */
+  tool: string;
+  /** Prompt/note snippet for display. */
+  title?: string;
+  /** Working directory (?folder= form) — ties an agent to a workspace. */
+  cwd: string;
+  state: "active" | "idle";
+  /** Unix ms when the agent started. */
+  startedAt?: number;
+}
+
+/** One checkout a root daemon found on disk under its layout — advertised so
+ *  clients can list and exactly match real workspaces instead of synthesizing
+ *  optimistic paths. */
+export interface WorkspaceInfo {
+  /** ?folder= form path of the checkout (see toPosixPath). */
+  path: string;
+  /** Host-agnostic repo identity, e.g. "github.com/owner/repo". */
+  repo?: string;
+  /** Branch from the layout path, e.g. "main". */
+  branch?: string;
+}
+
 /** Metadata a `codehost serve`/`dev` daemon advertises about itself. */
 export interface PeerMeta {
   /** Human label, defaults to hostname. */
@@ -12,6 +40,13 @@ export interface PeerMeta {
   cwd: string;
   /** Hostname of the machine running the daemon. */
   host: string;
+  /**
+   * Stable machine identity (UUID persisted in ~/.codehost/config.json). All
+   * daemons on one machine share it, unlike the per-process peerId, so clients
+   * can group peers by host and keep history across daemon restarts. Absent on
+   * older daemons — fall back to `host`.
+   */
+  hostId?: string;
   /**
    * "repo": serves a single folder (`codehost dev`), git-identified when possible.
    * "root": serves a workspace root (`codehost serve`) whose repos live under it.
@@ -28,6 +63,17 @@ export interface PeerMeta {
    * `cwd + "/" + fill(layout, target)`.
    */
   layout?: string;
+  /**
+   * root kind: the checkouts that actually exist under `cwd` (enumerated on
+   * start, after each provision, and on a slow rescan). Capped server-side;
+   * absent on older daemons and on repo/expose kinds.
+   */
+  workspaces?: WorkspaceInfo[];
+  /**
+   * Live agent CLI sessions on this machine (from the agent-yes plugin).
+   * Advertised by root daemons; capped server-side.
+   */
+  agents?: AgentInfo[];
 }
 
 export interface PeerInfo {
@@ -61,7 +107,15 @@ export interface PingMessage {
   type: "ping";
 }
 
-export type ClientMessage = HelloMessage | SignalMessage | PingMessage;
+/** Replace this peer's advertised metadata mid-session (e.g. a provision
+ *  created a new workspace) — the room re-broadcasts the peer list. Older
+ *  workers ignore it; the meta still lands via `hello` on the next reconnect. */
+export interface MetaMessage {
+  type: "meta";
+  meta: PeerMeta;
+}
+
+export type ClientMessage = HelloMessage | SignalMessage | PingMessage | MetaMessage;
 
 // ---- Server -> Client ----
 

package/src/web/discovery.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from "react";
-import type { PeerInfo } from "../shared/signaling";
+import type { AgentInfo, PeerInfo, WorkspaceInfo } from "../shared/signaling";
 import { TOKEN_REQUIREMENTS, validateToken } from "../shared/token";
 import { SignalingClient } from "../shared/signaling-client";
 import type { RtcSignal } from "../shared/rtc";
@@ -11,6 +11,7 @@ import {
   DEFAULT_BRANCH,
   type DeepLink,
   type RepoTarget,
+  type ResolvePrefs,
   type RoomMatch,
   gitUrlToPath,
   parseDeepLink,
@@ -91,7 +92,7 @@ function findRoomForDeepLink(dl: DeepLink, tokens: string[], timeoutMs = 6000):
           const res =
             dl.type === "repo" ? resolveRepoTarget(servers, dl.target) : resolveDevTarget(servers, dl.target);
           if (!res) return;
-          if (!res.folder) finish(tok); // exact match — take it now
+          if (!res.folder || res.exact) finish(tok); // exact match — take it now
           else if (!fallbacks.some((f) => f.token === tok)) fallbacks.push({ token: tok, resolution: res });
         },
       });
@@ -545,6 +546,14 @@ export function Discovery() {
     setTimeout(() => setCopied(false), 1500);
   }
 
+  // The machine history says served this repo last — break resolution ties
+  // toward it (stable hostId when recorded, hostname for older entries).
+  function preferFor(dl: DeepLink): ResolvePrefs | undefined {
+    if (dl?.type !== "repo") return undefined;
+    const h = historyFor(repoKey(dl.target));
+    return h ? { hostId: h.hostId, host: h.host } : undefined;
+  }
+
   // Deep-link auto-connect: when servers arrive, pick the best match (exact repo
   // daemon, else a root daemon's subfolder) across all rooms and open it once.
   function tryAutoConnect() {
@@ -552,7 +561,8 @@ export function Discovery() {
     const dl = deepLinkRef.current;
     if (dl) {
       const peers = allServers.map((x) => x.server);
-      const res = dl.type === "repo" ? resolveRepoTarget(peers, dl.target) : resolveDevTarget(peers, dl.target);
+      const res =
+        dl.type === "repo" ? resolveRepoTarget(peers, dl.target, preferFor(dl)) : resolveDevTarget(peers, dl.target);
       if (!res) return;
       const match = allServers.find((x) => x.server.peerId === res.peerId);
       if (!match) return;
@@ -576,7 +586,7 @@ export function Discovery() {
   function recordConnect(server: PeerInfo, room: string, folder?: string) {
     const base = {
       token: room,
-      peerId: server.peerId,
+      hostId: server.meta?.hostId,
       kind: server.meta?.kind,
       name: server.meta?.name,
       host: server.meta?.host,
@@ -607,7 +617,8 @@ export function Discovery() {
   function findServerForDeepLink(dl: DeepLink): (RoomedServer & { folder?: string }) | null {
     if (!dl) return null;
     const peers = allServersRef.current.map((x) => x.server);
-    const res = dl.type === "repo" ? resolveRepoTarget(peers, dl.target) : resolveDevTarget(peers, dl.target);
+    const res =
+      dl.type === "repo" ? resolveRepoTarget(peers, dl.target, preferFor(dl)) : resolveDevTarget(peers, dl.target);
     if (!res) return null;
     const match = allServersRef.current.find((x) => x.server.peerId === res.peerId);
     return match ? { ...match, folder: res.folder } : null;
@@ -630,6 +641,19 @@ export function Discovery() {
     void connectTo(target.server, target.room, target.folder, true, dl.type === "repo" ? dl.target : undefined);
   }
 
+  // Open an enumerated checkout via its deep link, reusing the URL-driven
+  // resolution (provisioning, history, machine preference) instead of dialing
+  // the card's peer directly.
+  function openWorkspace(server: PeerInfo, w: WorkspaceInfo) {
+    const path = w.repo
+      ? shareableDeepLink({ repo: w.repo, branch: w.branch })
+      : shareableDeepLink({ folder: w.path, host: server.meta?.host });
+    if (!path) return;
+    history.pushState(null, "", path);
+    setResolving(deepLinkLabel(parseDeepLink(path)));
+    syncToUrl();
+  }
+
   function disconnect() {
     // Mirror Cmd+Left: if connecting pushed a history entry, pop it — the
     // browser restores the previous URL and our popstate handler tears down.
@@ -664,6 +688,23 @@ export function Discovery() {
   }));
   const query = [...activeTags, filter].join(" ");
   const filtered = tagged.filter((t) => matchQuery({ name: t.name, tags: t.tags }, query));
+  // Group workspaces by machine: the stable hostId when the daemon advertises
+  // one, else the hostname string (older daemons), else the peer stands alone.
+  // Agents are machine-level (advertised by the host's root daemon) — collect
+  // them per group, deduped by pid across peers.
+  const hostGroups: { key: string; label: string; items: typeof filtered; agents: AgentInfo[] }[] = [];
+  for (const t of filtered) {
+    const key = t.server.meta?.hostId ?? t.server.meta?.host ?? t.server.peerId;
+    let group = hostGroups.find((g) => g.key === key);
+    if (!group) {
+      group = { key, label: t.server.meta?.host ?? t.name, items: [], agents: [] };
+      hostGroups.push(group);
+    }
+    group.items.push(t);
+    for (const a of t.server.meta?.agents ?? []) {
+      if (!group.agents.some((x) => x.pid === a.pid)) group.agents.push(a);
+    }
+  }
   const toggleTag = (t: string) =>
     setActiveTags((a) => (a.includes(t) ? a.filter((x) => x !== t) : [...a, t]));
   const addTag = (t: string) => setActiveTags((a) => (a.includes(t) ? a : [...a, t]));
@@ -905,42 +946,85 @@ export function Discovery() {
               )}
             </>
           )}
-          <ul style={styles.list}>
-            {filtered.map(({ server: s, room, name, tags }) => {
-              const isActive = s.peerId === activePeerId;
-              return (
-                <li key={s.peerId} style={styles.card}>
-                  <div style={styles.cardMain}>
-                    <div style={styles.cardName}>{name}</div>
-                    <div style={styles.tagRow}>
-                      {tags.map((tag) => (
-                        <button key={tag} style={styles.tag} onClick={() => addTag(tag)} title={`filter by ${tag}`}>
-                          {tag}
-                        </button>
-                      ))}
-                    </div>
-                    <div style={styles.idLine}>peer {s.peerId.slice(0, 8)}</div>
-                    {isActive && (
-                      <div style={styles.echo}>
-                        {connState === "connecting" && "negotiating WebRTC…"}
-                        {connState === "failed" && "connection failed"}
-                      </div>
-                    )}
+          <div>
+            {hostGroups.map((g) => (
+              <section key={g.key}>
+                <div style={styles.hostHead}>
+                  <span style={styles.hostName}>{g.label}</span>
+                  <span style={styles.count}>
+                    {g.items.length} workspace{g.items.length === 1 ? "" : "s"}
+                    {g.agents.length > 0 && ` · ${g.agents.length} agent${g.agents.length === 1 ? "" : "s"}`}
+                  </span>
+                </div>
+                {g.agents.length > 0 && (
+                  <div style={styles.agentRow}>
+                    {g.agents.map((a) => (
+                      <span
+                        key={a.pid}
+                        style={styles.agentChip}
+                        title={`${a.cwd}${a.title ? `\n${a.title}` : ""}`}
+                      >
+                        <span style={{ color: a.state === "active" ? "#4ec9b0" : "#777" }}>●</span> {a.tool}{" "}
+                        {a.pid}
+                      </span>
+                    ))}
                   </div>
-                  <button
-                    style={styles.connectBtn}
-                    onClick={() => connectTo(s, room)}
-                    disabled={isActive && connState === "connecting"}
-                  >
-                    {isActive && connState === "connecting" ? "…" : "Connect"}
-                  </button>
-                </li>
-              );
-            })}
+                )}
+                <ul style={styles.list}>
+                  {g.items.map(({ server: s, room, name, tags }) => {
+                    const isActive = s.peerId === activePeerId;
+                    return (
+                      <li key={s.peerId} style={styles.card}>
+                        <div style={styles.cardMain}>
+                          <div style={styles.cardName}>{name}</div>
+                          <div style={styles.tagRow}>
+                            {tags.map((tag) => (
+                              <button key={tag} style={styles.tag} onClick={() => addTag(tag)} title={`filter by ${tag}`}>
+                                {tag}
+                              </button>
+                            ))}
+                          </div>
+                          {(s.meta?.workspaces?.length ?? 0) > 0 && (
+                            <div style={styles.wsRow}>
+                              {s.meta!.workspaces!.map((w) => (
+                                <button
+                                  key={w.path}
+                                  style={styles.wsLink}
+                                  onClick={() => openWorkspace(s, w)}
+                                  title={w.path}
+                                >
+                                  {w.repo
+                                    ? `${w.repo.split("/").slice(1).join("/")}${w.branch ? ` @${w.branch}` : ""}`
+                                    : w.path}
+                                </button>
+                              ))}
+                            </div>
+                          )}
+                          <div style={styles.idLine}>peer {s.peerId.slice(0, 8)}</div>
+                          {isActive && (
+                            <div style={styles.echo}>
+                              {connState === "connecting" && "negotiating WebRTC…"}
+                              {connState === "failed" && "connection failed"}
+                            </div>
+                          )}
+                        </div>
+                        <button
+                          style={styles.connectBtn}
+                          onClick={() => connectTo(s, room)}
+                          disabled={isActive && connState === "connecting"}
+                        >
+                          {isActive && connState === "connecting" ? "…" : "Connect"}
+                        </button>
+                      </li>
+                    );
+                  })}
+                </ul>
+              </section>
+            ))}
             {serverCount > 0 && filtered.length === 0 && (
               <p style={styles.dim}>No workspace matches your filter.</p>
             )}
-          </ul>
+          </div>
         </main>
       </div>
     </>
@@ -985,8 +1069,20 @@ const styles: Record<string, React.CSSProperties> = {
     border: "1px solid #3d3d3d", background: "transparent", color: "#9aa4af", cursor: "pointer",
   },
   idLine: { fontFamily: "monospace", fontSize: 11, color: "#666", marginTop: 6 },
+  wsRow: { display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 3, marginTop: 8 },
+  wsLink: {
+    fontFamily: "monospace", fontSize: 12, padding: "2px 0", border: "none", background: "transparent",
+    color: "#75beff", cursor: "pointer", textAlign: "left",
+  },
   code: { background: "#252525", padding: "2px 6px", borderRadius: 4, fontFamily: "monospace", fontSize: 12 },
-  list: { listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 8 },
+  list: { listStyle: "none", margin: "0 0 14px", padding: 0, display: "flex", flexDirection: "column", gap: 8 },
+  hostHead: { display: "flex", alignItems: "baseline", gap: 10, margin: "0 0 8px" },
+  hostName: { fontSize: 13, fontWeight: 600, color: "#dcdcaa", fontFamily: "monospace" },
+  agentRow: { display: "flex", flexWrap: "wrap", gap: 6, margin: "0 0 8px" },
+  agentChip: {
+    fontFamily: "monospace", fontSize: 11.5, padding: "2px 8px", borderRadius: 999,
+    border: "1px solid #3d3d3d", color: "#9aa4af",
+  },
   card: { display: "flex", alignItems: "center", gap: 12, background: "#252525", border: "1px solid #3d3d3d", borderRadius: 8, padding: "12px 14px" },
   cardMain: { flex: 1, minWidth: 0 },
   cardName: { fontSize: 14, fontWeight: 600, color: "#fff" },

package/src/web/history.ts

@@ -7,11 +7,14 @@ const HISTORY_KEY = "codehost.history";
 
 export interface HistoryEntry {
   token: string;
-  peerId?: string;
+  /** Stable machine id of the server that opened it — unlike a peerId it
+   *  survives daemon restarts, so reconnect prefers the same machine. */
+  hostId?: string;
   kind?: "repo" | "root";
   /** For root-kind opens, the ?folder= path used. */
   folder?: string;
   name?: string;
+  /** Hostname — display + match fallback for pre-hostId daemons/entries. */
   host?: string;
   lastConnected: number;
 }

package/src/web/room-client.ts

@@ -0,0 +1,114 @@
+import { SignalingClient } from "../shared/signaling-client";
+import type { PeerInfo } from "../shared/signaling";
+import type { RtcSignal } from "../shared/rtc";
+import { RtcClient } from "./rtc-client";
+import { TunnelClient } from "./tunnel-client";
+
+// Embeddable codehost room client for OTHER sites (agent-yes.com first): join a
+// room as a viewer, watch the peer list (hosts advertise workspaces + agents in
+// PeerMeta), and speak HTTP to any server peer over a lazily-dialed WebRTC
+// tunnel. No Service Worker, no React, no cross-tab broker — one module that
+// `bun build --target browser` bundles standalone (see scripts.build:lib).
+
+export type { AgentInfo, PeerInfo, PeerMeta, WorkspaceInfo } from "../shared/signaling";
+
+export const DEFAULT_SIGNAL_URL = "wss://signal.codehost.dev";
+
+export interface RoomOptions {
+  /** Room token (bearer secret — same one `codehost serve -t` uses). */
+  token: string;
+  /** Signaling server (default wss://signal.codehost.dev). */
+  signalUrl?: string;
+  /** Live server-peer list, fired on every room membership/meta change. */
+  onPeers?: (peers: PeerInfo[]) => void;
+  /** Signaling socket state. */
+  onStatus?: (open: boolean) => void;
+}
+
+export class CodehostRoom {
+  /** Server peers currently in the room (viewers filtered out). */
+  peers: PeerInfo[] = [];
+  private signaling: SignalingClient;
+  private rtcs = new Map<string, RtcClient>();
+  private tunnels = new Map<string, Promise<TunnelClient>>();
+  private closed = false;
+
+  constructor(opts: RoomOptions) {
+    this.signaling = new SignalingClient({
+      url: opts.signalUrl ?? DEFAULT_SIGNAL_URL,
+      token: opts.token,
+      role: "viewer",
+      onOpen: () => opts.onStatus?.(true),
+      onClose: () => opts.onStatus?.(false),
+      onPeers: (peers) => {
+        this.peers = peers.filter((p) => p.role === "server");
+        opts.onPeers?.(this.peers);
+      },
+      onSignal: (from, data) => void this.rtcs.get(from)?.handleSignal(data),
+    });
+    this.signaling.connect();
+  }
+
+  /** HTTP over the peer's tunnel (dialed on first use, reused after). The
+   *  response streams — long-lived SSE bodies work. */
+  async fetch(
+    peerId: string,
+    method: string,
+    path: string,
+    init: { headers?: Record<string, string>; body?: Uint8Array | string } = {},
+  ): Promise<Response> {
+    const tunnel = await this.dial(peerId);
+    const body = typeof init.body === "string" ? new TextEncoder().encode(init.body) : init.body;
+    return tunnel.fetch(method, path, init.headers ?? {}, body);
+  }
+
+  private dial(peerId: string): Promise<TunnelClient> {
+    const existing = this.tunnels.get(peerId);
+    if (existing) return existing;
+    const drop = () => {
+      this.tunnels.delete(peerId);
+      this.rtcs.get(peerId)?.close();
+      this.rtcs.delete(peerId);
+    };
+    const dialing = new Promise<TunnelClient>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        drop();
+        reject(new Error("dial timed out"));
+      }, 15000);
+      const rtc = new RtcClient({
+        sendSignal: (data: RtcSignal) => this.signaling.sendSignal(peerId, data),
+        onOpen: (channel) => {
+          clearTimeout(timer);
+          resolve(new TunnelClient(channel));
+        },
+        onClose: drop,
+        onState: (state) => {
+          if (state === "failed" || state === "disconnected") drop();
+        },
+      });
+      this.rtcs.set(peerId, rtc);
+      rtc.start().catch((err) => {
+        clearTimeout(timer);
+        drop();
+        reject(err);
+      });
+    });
+    this.tunnels.set(peerId, dialing);
+    dialing.catch(() => this.tunnels.delete(peerId));
+    return dialing;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const rtc of this.rtcs.values()) rtc.close();
+    this.rtcs.clear();
+    this.tunnels.clear();
+    this.signaling.close();
+  }
+}
+
+/** Join a codehost room as a viewer. */
+export function joinRoom(opts: RoomOptions): CodehostRoom {
+  return new CodehostRoom(opts);
+}

package/worker/room.ts

@@ -71,6 +71,15 @@ export class Room implements DurableObject {
       return;
     }
 
+    if (msg.type === "meta") {
+      const att = this.touch(ws);
+      if (!att) return; // never said hello
+      att.meta = msg.meta ?? null;
+      ws.serializeAttachment(att);
+      this.broadcastPeers();
+      return;
+    }
+
     if (msg.type === "signal") {
       const att = this.touch(ws);
       if (!att) return;