agent-yes 1.290.7 → 1.291.0

package/ts/share.ts

@@ -147,7 +147,7 @@ export interface ShareOpts {
    *  generation/token), startShare mints a fresh room, persists it, and calls
    *  this so the caller can refresh its stored link. Leave unset for explicit
    *  webrtc:// URLs, which must NOT be silently rotated. */
-  onRotate?: (info: { room: string; link: string }) => void | Promise<void>;
+  onRotate?: (info: { room: string; link: string; joinLink: string }) => void | Promise<void>;
 }
 
 // The room+token persist like the serve token, so the share link (and any
@@ -183,7 +183,13 @@ export async function loadOrCreateShareRoom(sighost = DEFAULT_SIGHOST): Promise<
 
 function parseShareUrl(s: string): { room: string; token: string; host: string } {
   const m = /^webrtc:\/\/([^:@/]+):([^@/]+)@(.+)$/.exec(s);
-  if (!m) throw new Error(`bad --share url: ${s} (want webrtc://room:token@host)`);
+  // Callers normalize any user-facing spelling (https://…/room/#…) to this
+  // internal form via toWebrtcUrl, so reaching here means a caller bug — point at
+  // the shape operators actually hold rather than at the internal one.
+  if (!m)
+    throw new Error(
+      `bad room url: ${s} (want a https://agent-yes.com/room/#room=<id>&s=e1.<secret> link)`,
+    );
   return { room: m[1]!, token: m[2]!, host: m[3]! };
 }
 
@@ -200,6 +206,27 @@ function formatShareLink(room: string, S: string, host: string): string {
   return `${ui}/#${room}:${MARKER}${S}${suffix}`;
 }
 
+// The /room/ link for a room — the one you hand to ANOTHER machine to attach it
+// to this room. Opened in a browser it's a guide page (which renders the install
+// one-liner client-side from this very fragment, so the secret never reaches a
+// server); passed to `ay serve --webrtc` it joins.
+//
+// The fragment is key=value (URLSearchParams) rather than the positional form
+// /w/ uses: the fragment namespace is shared with #k=, #ch= and #launch=, and a
+// positional grammar can only be told apart from those by a blocklist someone
+// has to remember to update (see parseRoomHash in lab/ui/rtc.js). Bare `k=v&…`
+// — no leading "?" — matches OAuth 2.0's implicit-grant fragment (RFC 6749
+// §4.2.2), the same trick for the same reason: a credential the server must
+// never see.
+export function formatRoomLink(room: string, S: string, host: string): string {
+  const prod = host === DEFAULT_SIGHOST;
+  const ui = prod ? "https://agent-yes.com/room" : "http://localhost:7778/room";
+  // Values must be URL-safe: `s` is hex and `room` is [A-Za-z0-9_-], but encode
+  // anyway — URLSearchParams decodes on the way out and reads "+" as a space.
+  const q = `room=${encodeURIComponent(room)}&s=${encodeURIComponent(MARKER + S)}`;
+  return `${ui}/#${q}${prod ? "" : `&sig=${encodeURIComponent(host)}`}`;
+}
+
 // Derive the shareable console link from a persisted/explicit webrtc://room:token@host
 // URL WITHOUT starting a bridge, so `ay serve install` can print the same link the
 // background daemon will serve. Throws on a legacy (unencrypted) room, mirroring
@@ -307,7 +334,7 @@ export async function importRTC(): Promise<any> {
  *  process exits, reconnecting signaling on drop. Returns the shareable link. */
 export async function startShare(
   opts: ShareOpts,
-): Promise<{ room: string; link: string; close: () => void }> {
+): Promise<{ room: string; link: string; joinLink: string; close: () => void }> {
   const minted = !opts.url;
   const sighost = opts.sighost ?? DEFAULT_SIGHOST;
   const initial = opts.url
@@ -337,8 +364,12 @@ export async function startShare(
 
   const wsScheme = host.startsWith("localhost") || host.startsWith("127.") ? "ws" : "wss";
   const mkLink = () => formatShareLink(room, S, host);
+  // The /room/ link — handed to ANOTHER machine to attach it to this room,
+  // where the console link above is for a human to watch it.
+  const mkJoinLink = () => formatRoomLink(room, S, host);
   let authToken = await deriveAuthToken(S, room, host);
   let link = mkLink();
+  let joinLink = mkJoinLink();
 
   const RTCPeerConnection = await importRTC();
 
@@ -356,6 +387,7 @@ export async function startShare(
     S = parseSecret(token).s;
     authToken = await deriveAuthToken(S, room, host);
     link = mkLink();
+    joinLink = mkJoinLink();
     // close() may have run during the await above — don't persist/announce or let
     // the caller reconnect a room for a share that's shutting down.
     if (closed) return false;
@@ -365,7 +397,7 @@ export async function startShare(
     } catch {
       /* best effort — in-memory rotation still lets new browsers join */
     }
-    await opts.onRotate({ room, link });
+    await opts.onRotate({ room, link, joinLink });
     return true;
   };
 
@@ -885,5 +917,5 @@ export async function startShare(
     }
     for (const peerId of [...peers.keys()]) closePeer(peerId);
   };
-  return { room, link, close };
+  return { room, link, joinLink, close };
 }

package/ts/subcommands.ts

@@ -12,7 +12,8 @@
  */
 
 import { randomBytes } from "crypto";
-import { closeSync, constants as fsConstants, openSync } from "fs";
+import { closeSync, constants as fsConstants, openSync, realpathSync } from "fs";
+import { execFileSync } from "node:child_process";
 import { appendFile, mkdir, open, readFile, stat, writeFile } from "fs/promises";
 import ms from "ms";
 import { homedir } from "os";
@@ -72,11 +73,20 @@ import { framePaste as frameAsPaste, shouldFramePaste } from "./bracketedPaste.t
 import {
   ageMatchesRegistration,
   findAgentAncestor,
+  pidOwnershipVerdict,
   readAncestryTable,
   type SenderVia,
 } from "./senderAncestry.ts";
 import yargs from "yargs";
 import { type ResolvedRemote, readRemotes, resolveRemoteSpec } from "./remotes.ts";
+import {
+  noteRemoteResult,
+  pruneRemoteHealth,
+  readRemoteHealth,
+  remoteBackoffMs,
+  shouldSkipRemote,
+  writeRemoteHealth,
+} from "./remoteHealth.ts";
 import { isWebrtcSpec } from "./webrtcLink.ts";
 import { withIpcLock } from "./ipcLock.ts";
 
@@ -289,6 +299,35 @@ function observedSender(): ObservedSender {
   };
 }
 
+/**
+ * The repository a directory belongs to, as git itself defines it: the common
+ * dir, which every linked worktree of one repository shares and no separate
+ * clone does. Null when the path is not in a repository or git cannot answer.
+ *
+ * Synchronous and cached: it is consulted at most twice per send, and only on
+ * the path where the cheaper directory check already failed.
+ */
+const _commonDirCache = new Map<string, string | null>();
+function gitCommonDir(dir: string): string | null {
+  const hit = _commonDirCache.get(dir);
+  if (hit !== undefined) return hit;
+  let out: string | null = null;
+  try {
+    out =
+      execFileSync("git", ["-C", dir, "rev-parse", "--path-format=absolute", "--git-common-dir"], {
+        encoding: "utf8",
+        timeout: 5000,
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+        .trim()
+        .replace(/\/+$/, "") || null;
+  } catch {
+    out = null;
+  }
+  _commonDirCache.set(dir, out);
+  return out;
+}
+
 async function resolveSender(): Promise<GlobalPidRecord | null> {
   return (await resolveSenderVia()).agent;
 }
@@ -355,12 +394,78 @@ async function computeSenderVia(): Promise<{ agent: GlobalPidRecord | null; via:
     // The honest path is unchanged in OUTCOME: the wrapper that injects
     // AGENT_YES_PID is an ancestor of the `ay send` it spawns, so a normal lane
     // corroborates and renders exactly as before.
-    const corroborated = inherited?.pid === declared.pid;
-    // A disagreement is REPORTED, never silently resolved. Attributing to the
-    // ancestor instead would break an honest lane whose tree we misread; giving
-    // it a plain "env" would launder a claim into a fact. So the claim stands
-    // and the receiver is told it stands alone.
-    return { agent: declared, via: corroborated ? "env" : "env-uncorroborated" };
+    // The claimed lane is our ancestor: claim and kernel agree.
+    if (inherited?.pid === declared.pid) return { agent: declared, via: "env" };
+
+    // It is not. That alone does not say which of two very different things is
+    // happening, and the earlier rule — "is some OTHER registered lane my
+    // ancestor" — picked the wrong discriminator. Measured on real traffic it
+    // was inverted: it fired on a lane's own nested processes (same tree,
+    // benign) and stayed silent while a different worktree sent two documents
+    // under this lane's name.
+    //
+    // The working directory separates them. A lane's own detached helper runs
+    // inside that lane's tree; a process in a DIFFERENT tree claiming the lane
+    // is the case the marker exists for. cwd is observed, not asserted — the
+    // body cannot set it.
+    // BOTH sides are realpath'd first. macOS resolves /tmp -> /private/tmp and
+    // /var -> /private/var, so a lane registered under a symlinked path would
+    // otherwise never appear to contain its own processes and every honest send
+    // from it would be accused. Caught by a same-tree test that went loud.
+    // Best-effort: an unreadable path falls back to the raw string rather than
+    // failing the send.
+    const real = (p2: string): string => {
+      try {
+        return realpathSync(p2).replace(/\/+$/, "");
+      } catch {
+        return p2.replace(/\/+$/, "");
+      }
+    };
+    const here = real(process.cwd());
+    const claimedRoot = declared.cwd ? real(declared.cwd) : "";
+    const insideClaimedTree =
+      Boolean(claimedRoot) && (here === claimedRoot || here.startsWith(claimedRoot + path.sep));
+    // "Inside the tree" is not the same as "belongs to that lane". A lane
+    // routinely works in a LINKED WORKTREE that is a sibling directory, not a
+    // child — `~/ws/org/_wt/feature-x` alongside `~/ws/org/repo/tree/dev`. A
+    // bare `ay send` from a shell there inherits AGENT_YES_PID honestly and
+    // would be accused on a path check alone.
+    //
+    // git already answers this exactly: linked worktrees of one repository
+    // share a git common dir, while a separate clone has its own. Measured on
+    // the fleet that reported it — the sibling worktree resolved to the lane's
+    // own `.git`, and the worktree that had been misattributing resolved to a
+    // different one. So the same probe separates the honest case from the case
+    // this marker exists for, which a "same parent directory" heuristic would
+    // not: both live under the same ancestor.
+    //
+    // Only consulted when the path check already failed, so the honest common
+    // path pays nothing.
+    // CONTAINMENT, not equality. A lane's submodule worktrees have a common dir
+    // NESTED inside the lane's own:
+    //
+    //   lane                  …/tree/dev/.git
+    //   its submodule wt      …/tree/dev/.git/modules/lib/desktop   <- descendant
+    //   a separate clone      …/tree/billings/.git                  <- neither
+    //
+    // Equality would mark the first case LOUD — the same false positive one
+    // layer down, reported from the fleet that runs that shape. Checked in both
+    // directions because the mirror layout (a lane registered in the submodule
+    // worktree, sending from the parent tree) is equally legitimate and would
+    // otherwise wait to be discovered by firing. A separate clone is under
+    // neither, so detection is unchanged.
+    const sameRepo = () => {
+      if (!claimedRoot) return false;
+      const a = gitCommonDir(here);
+      const b = gitCommonDir(claimedRoot);
+      if (a === null || b === null) return false;
+      return a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep);
+    };
+    if (!insideClaimedTree && !sameRepo()) return { agent: declared, via: "env-uncorroborated" };
+
+    // Inside the claimed lane's own tree, or nothing to compare against:
+    // unverifiable, not suspicious, and must not be dressed as it.
+    return { agent: declared, via: "env-unverified" };
   }
   // A set-but-unresolvable AGENT_YES_PID (stale env, aged-out record) is not a
   // reason to stop: the process tree can still say who this is.
@@ -687,10 +792,16 @@ export function envelopeAttribution(via: SenderVia): string {
       // Derived from the process tree because the wrapper's env was absent.
       return " via process-tree";
     case "env-uncorroborated":
-      // The caller's own claim, and nothing corroborates it: any process can
-      // export another lane's pid (#461). Loud, because a receiver that acts on
-      // a message weighted by its sender must not be handed this as a fact.
+      // The claim and the process tree name DIFFERENT lanes. Loud, because this
+      // is the case a receiver acting on sender weight must not be handed as a
+      // fact — and loud only here, so it keeps meaning something.
       return " UNCORROBORATED-SENDER";
+    case "env-unverified":
+      // Nothing to disagree with. Silent in the envelope: the receiver gains
+      // nothing actionable from "we could not check", and a marker on honest
+      // traffic is how the loud one stops being read. It is still recorded in
+      // from_via for anyone who wants to weigh it.
+      return "";
     default:
       return "";
   }
@@ -1006,14 +1117,28 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
       }
       case "gc": {
         const { gcOldBinaryDirs } = await import("./rustBinary.ts");
-        const res = gcOldBinaryDirs();
-        if (res.removed.length === 0) {
+        const { gcLogs } = await import("./globalPidIndex.ts");
+        const bins = gcOldBinaryDirs();
+        // Logs are the bigger leak of the two: binary dirs are ~20-30 MiB per
+        // release, while a single long-lived session's raw log can pass 500.
+        const logs = await gcLogs();
+
+        if (bins.removed.length === 0) {
           process.stdout.write("no old agent-yes binary cache dirs to remove\n");
         } else {
-          for (const v of res.removed) process.stdout.write(`removed ${v}\n`);
-          const mib = (res.freedBytes / 1024 / 1024).toFixed(1);
+          for (const v of bins.removed) process.stdout.write(`removed ${v}\n`);
+          const mib = (bins.freedBytes / 1024 / 1024).toFixed(1);
+          process.stdout.write(
+            `freed ${mib} MiB (${bins.freedBytes} bytes) across ${bins.removed.length} version dir(s)\n`,
+          );
+        }
+
+        if (logs.removed.length === 0) {
+          process.stdout.write("no stale session logs to remove\n");
+        } else {
+          const mib = (logs.freedBytes / 1024 / 1024).toFixed(1);
           process.stdout.write(
-            `freed ${mib} MiB (${res.freedBytes} bytes) across ${res.removed.length} version dir(s)\n`,
+            `freed ${mib} MiB (${logs.freedBytes} bytes) across ${logs.removed.length} session log file(s)\n`,
           );
         }
         return 0;
@@ -1155,7 +1280,7 @@ export async function cmdHelp(managerCommands = true): Promise<number> {
       `  ay result <keyword> [--wait]        pull an agent's structured result envelope\n` +
       `  ay result set '<json>'              (inside an agent) deposit your result envelope\n` +
       `  ay reap                             kill process groups leaked by dead agents\n` +
-      `  ay gc                               remove old-version binary cache dirs and report freed space\n` +
+      `  ay gc                               reclaim old-version binary cache dirs + stale session logs\n` +
       `  ay dsh-legacy [args...]              launch the DeepSeek Harness terminal client (dsh-tui)\n` +
       wsLines +
       `\n` +
@@ -1790,6 +1915,14 @@ async function fetchRemoteRecordsRaw(
   url: string,
   token: string,
   opts: { all: boolean; active: boolean; keyword?: string },
+  /**
+   * Set true when the host ANSWERED, false when it did not. A healthy host with
+   * no agents — or one where `--keyword` matched nothing — returns [] exactly
+   * like a dead one, so row count cannot stand in for reachability: using it
+   * would mark a live-but-empty host failed and hide it for up to 32 minutes,
+   * which is the failure this whole change exists to avoid.
+   */
+  onReachable?: (ok: boolean) => void,
 ): Promise<any[]> {
   const params = new URLSearchParams();
   if (opts.all) params.set("all", "1");
@@ -1810,9 +1943,13 @@ async function fetchRemoteRecordsRaw(
       headers: { Authorization: `Bearer ${bearer}` },
       signal: AbortSignal.timeout(8000),
     });
+    // A 4xx/5xx still means the host is THERE and talking; only a throw (DNS,
+    // refused connection, connect timeout, aborted bridge) means unreachable.
+    onReachable?.(true);
     if (!res.ok) return [];
     return (await res.json()) as any[];
   } catch {
+    onReachable?.(false);
     return [];
   } finally {
     bridge?.close();
@@ -1833,16 +1970,47 @@ async function runAllRemotesLs(opts: {
     cwdScope: null,
   };
 
+  // A remote that is not answering costs a full connect timeout (25s for a
+  // WebRTC spec) and returns nothing, and this gathers them together — so two
+  // dead entries made every `ay ls` here take 27s instead of 5s. Skip a host
+  // that has been failing, on a doubling backoff, and keep LISTING it as
+  // unreachable so the config stays honest and the operator can see it is being
+  // skipped rather than silently dropped. See ts/remoteHealth.ts.
+  const health = await readRemoteHealth();
+  const healthNow = Date.now();
+  const skipped = new Set(
+    [...remotes.keys()].filter((alias) => shouldSkipRemote(health[alias], healthNow)),
+  );
+  const probed = [...remotes.entries()].filter(([alias]) => !skipped.has(alias));
+
   const [localResult, ...remoteResults] = await Promise.allSettled([
     listRecords(opts.keyword, localOpts).then((recs) => ({
       host: "local",
       records: recs as any[],
     })),
-    ...Array.from(remotes.entries()).map(([alias, cfg]) =>
-      fetchRemoteRecordsRaw(cfg.url, cfg.token, opts).then((records) => ({ host: alias, records })),
-    ),
+    ...probed.map(([alias, cfg]) => {
+      let reachable = false;
+      return fetchRemoteRecordsRaw(cfg.url, cfg.token, opts, (ok) => {
+        reachable = ok;
+      }).then((records) => ({ host: alias, records, ok: reachable }));
+    }),
   ]);
 
+  // Record what we learned, then persist once. A host that answered clears its
+  // streak; one that did not extends it. Best-effort: a health file we cannot
+  // write must never break `ay ls`.
+  {
+    // Prune first, so an alias removed from remotes.yaml stops being carried
+    // forever. `remotes` is the live configured set.
+    const next = pruneRemoteHealth({ ...health }, remotes.keys());
+    for (const [i, [alias]] of probed.entries()) {
+      const res = remoteResults[i];
+      const ok = res?.status === "fulfilled" && (res.value as any).ok === true;
+      next[alias] = noteRemoteResult(health[alias], ok, healthNow);
+    }
+    await writeRemoteHealth(next).catch(() => {});
+  }
+
   // Group by host in a stable order (local first, then each remote alias in
   // config order), so the aggregated table reads top-down per machine.
   const byHost: { host: string; records: any[] }[] = [];
@@ -1882,6 +2050,28 @@ async function runAllRemotesLs(opts: {
     );
     byHost.push({ host: "local", records: enriched });
   }
+  // A skipped host is REPORTED, not dropped. Silently omitting it would make a
+  // machine that can come back disappear from the fleet view with nothing to
+  // notice — the same failure as deleting it from the config, which is why we
+  // did not do that. One line to stderr per skipped host, so `--json` and any
+  // parser downstream stay unaffected.
+  for (const alias of skipped) {
+    const h = health[alias];
+    // Time REMAINING, not the window length: a host with one second left would
+    // otherwise report "retrying in up to 32m", which is true of the window and
+    // false of the wait, and the operator is reading this to decide whether to
+    // wait or force a probe.
+    const leftMs = Math.max(
+      0,
+      remoteBackoffMs(h?.streak ?? 1) - (healthNow - (h?.lastFailedAt ?? healthNow)),
+    );
+    const left =
+      leftMs >= 60_000 ? `${Math.round(leftMs / 60_000)}m` : `${Math.ceil(leftMs / 1000)}s`;
+    process.stderr.write(
+      `${alias}: unreachable — skipped after ${h?.streak ?? 0} failed attempt(s), ` +
+        `retrying in ${left} (ay ls ${alias} to force a probe now)\n`,
+    );
+  }
   for (const res of remoteResults) {
     if (res.status === "fulfilled")
       byHost.push({ host: res.value.host, records: res.value.records });
@@ -5415,6 +5605,36 @@ async function cmdRestart(rest: string[]): Promise<number> {
     let exited = await waitForExit(record.pid, 30_000);
     if (!exited) {
       // Wouldn't go gracefully — SIGKILL the pid (the reaper sweeps its pgid).
+      //
+      // But ONLY if the process at that number is still plausibly the agent we
+      // registered. pids are reused: a row can outlive its agent and name
+      // whatever now holds the number. This host carried a row 89 days old,
+      // surviving a reboot, whose pid was macOS `login` running as root.
+      //
+      // Nothing in this code was declining to kill that. The OS was, with
+      // EPERM, and only because the owner differed — a same-user recycled pid
+      // would have been killed. Deciding is the code's job, not the kernel's.
+      //
+      // Same age test the send path uses (#460): a process that started AFTER
+      // its registration cannot be the thing that registered.
+      //
+      // Refuse on EVIDENCE, not on ignorance. "Could not establish" is a third
+      // answer, not a quiet synonym for "reused": win32 has no process table
+      // reader, so treating unknown as reused would not guard this kill, it
+      // would delete restart's force-kill from that platform entirely. Where
+      // we cannot tell, behaviour is exactly what it was before this guard.
+      const table = await readAncestryTable();
+      const owns = pidOwnershipVerdict(table?.get(record.pid)?.ageSecs, record.started_at);
+      if (owns === "reused") {
+        process.stderr.write(
+          `pid ${record.pid} is alive but is NOT the agent that registered it — ` +
+            `its process is younger than the registration, so the number was reused. ` +
+            `Refusing to kill it.\n` +
+            `  check with: ps -p ${record.pid} -o pid=,user=,comm=\n` +
+            `  retire the stale row instead: ay stop ${record.pid}\n`,
+        );
+        return 1;
+      }
       try {
         process.kill(record.pid, "SIGKILL");
       } catch {

package/ts/terminal/browser.ts

@@ -233,6 +233,10 @@ export class AyTerminal {
     // Interactive input (opt-in): forward keystrokes to the agent's stdin as raw
     // bytes (code:"none" — the terminal itself sends \r). Fails closed to a mirror
     // on a 403 (a read-only token), like the rgui embed's attachStdin/onDenied.
+    //
+    // `raw: true` marks this a terminal wire, not a message (#453). Without it
+    // every keystroke and SGR mouse report becomes an inbox row, and the inbox
+    // is capacity-capped — a mouse scrolled over the pane evicts real messages.
     if (!this.readOnly) {
       this.term.onData((data: string) => {
         if (!this.writable) return;
@@ -240,7 +244,7 @@ export class AyTerminal {
           .fetch(this.url("/api/send"), {
             method: "POST",
             headers: { "content-type": "application/json" },
-            body: JSON.stringify({ keyword: this.pid, msg: data, code: "none" }),
+            body: JSON.stringify({ keyword: this.pid, msg: data, code: "none", raw: true }),
           })
           .then((r: any) => {
             if (r.status === 403 || r.status === 401) this.revokeWrite();

package/ts/webrtcLink.bun.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { DEFAULT_SIGHOST, isWebrtcSpec, parseWebrtcLink } from "./webrtcLink.ts";
+import { DEFAULT_SIGHOST, isWebrtcSpec, parseWebrtcLink, toWebrtcUrl } from "./webrtcLink.ts";
 
 // A representative v2 share secret (e1.<64 hex>); parseSecret keeps the hex `s`.
 const SECRET = "e1.982610a3034f065bfe9700037b306a6afeb7dc48567064058e6c4bbc09e502c2";
@@ -42,4 +42,48 @@ describe("parseWebrtcLink", () => {
     expect(parseWebrtcLink("just-an-alias")).toBeNull();
     expect(parseWebrtcLink("https://agent-yes.com/w/#noColonHere")).toBeNull();
   });
+
+  it("parses the key=value /room/ fragment", () => {
+    const r = parseWebrtcLink(`https://agent-yes.com/room/#room=r223104&s=${SECRET}`);
+    expect(r).toMatchObject({ room: "r223104", host: DEFAULT_SIGHOST });
+  });
+
+  it("honors sig= and tolerates a leading ? in the key=value form", () => {
+    expect(
+      parseWebrtcLink(`https://agent-yes.com/room/#?room=r1&s=${SECRET}&sig=sig.example.com`),
+    ).toMatchObject({ room: "r1", host: "sig.example.com" });
+  });
+
+  it("returns null when the key=value form is missing room or s", () => {
+    expect(parseWebrtcLink(`https://agent-yes.com/room/#room=r1`)).toBeNull();
+    expect(parseWebrtcLink(`https://agent-yes.com/room/#s=${SECRET}`)).toBeNull();
+  });
+
+  // The fragment namespace is shared with #k=, #ch= and #launch= (see
+  // parseRoomHash in lab/ui/rtc.js); a foreign key set must not be read as a room.
+  it("does not mistake another feature's hash for a room", () => {
+    expect(parseWebrtcLink("https://agent-yes.com/w/#k=deadbeef")).toBeNull();
+    expect(parseWebrtcLink("https://agent-yes.com/w/#launch=claude")).toBeNull();
+  });
+});
+
+describe("toWebrtcUrl", () => {
+  it("normalizes every accepted spelling to the internal webrtc:// form", () => {
+    const want = `webrtc://r1:${SECRET}@${DEFAULT_SIGHOST}`;
+    expect(toWebrtcUrl(`https://agent-yes.com/room/#room=r1&s=${SECRET}`)).toBe(want);
+    expect(toWebrtcUrl(`https://agent-yes.com/w/#r1:${SECRET}`)).toBe(want);
+    expect(toWebrtcUrl(want)).toBe(want);
+  });
+
+  // parseSecret strips the "e1." marker; rebuilding from the parsed `s` would
+  // hand a legacy markerless room a marker it never had, changing the token the
+  // signaling DO pinned the room to.
+  it("round-trips a legacy markerless token unchanged", () => {
+    const legacy = `webrtc://r1:plaintexttoken@${DEFAULT_SIGHOST}`;
+    expect(toWebrtcUrl(legacy)).toBe(legacy);
+  });
+
+  it("returns null for a non-link", () => {
+    expect(toWebrtcUrl("just-an-alias")).toBeNull();
+  });
 });

package/ts/webrtcLink.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { DEFAULT_SIGHOST, isWebrtcSpec, parseWebrtcLink } from "./webrtcLink.ts";
+import { DEFAULT_SIGHOST, isWebrtcSpec, parseWebrtcLink, toWebrtcUrl } from "./webrtcLink.ts";
 
 // A representative v2 share secret (e1.<64 hex>); parseSecret keeps the hex `s`.
 const SECRET = "e1.982610a3034f065bfe9700037b306a6afeb7dc48567064058e6c4bbc09e502c2";
@@ -42,4 +42,48 @@ describe("parseWebrtcLink", () => {
     expect(parseWebrtcLink("just-an-alias")).toBeNull();
     expect(parseWebrtcLink("https://agent-yes.com/w/#noColonHere")).toBeNull();
   });
+
+  it("parses the key=value /room/ fragment", () => {
+    const r = parseWebrtcLink(`https://agent-yes.com/room/#room=r223104&s=${SECRET}`);
+    expect(r).toMatchObject({ room: "r223104", host: DEFAULT_SIGHOST });
+  });
+
+  it("honors sig= and tolerates a leading ? in the key=value form", () => {
+    expect(
+      parseWebrtcLink(`https://agent-yes.com/room/#?room=r1&s=${SECRET}&sig=sig.example.com`),
+    ).toMatchObject({ room: "r1", host: "sig.example.com" });
+  });
+
+  it("returns null when the key=value form is missing room or s", () => {
+    expect(parseWebrtcLink(`https://agent-yes.com/room/#room=r1`)).toBeNull();
+    expect(parseWebrtcLink(`https://agent-yes.com/room/#s=${SECRET}`)).toBeNull();
+  });
+
+  // The fragment namespace is shared with #k=, #ch= and #launch= (see
+  // parseRoomHash in lab/ui/rtc.js); a foreign key set must not be read as a room.
+  it("does not mistake another feature's hash for a room", () => {
+    expect(parseWebrtcLink("https://agent-yes.com/w/#k=deadbeef")).toBeNull();
+    expect(parseWebrtcLink("https://agent-yes.com/w/#launch=claude")).toBeNull();
+  });
+});
+
+describe("toWebrtcUrl", () => {
+  it("normalizes every accepted spelling to the internal webrtc:// form", () => {
+    const want = `webrtc://r1:${SECRET}@${DEFAULT_SIGHOST}`;
+    expect(toWebrtcUrl(`https://agent-yes.com/room/#room=r1&s=${SECRET}`)).toBe(want);
+    expect(toWebrtcUrl(`https://agent-yes.com/w/#r1:${SECRET}`)).toBe(want);
+    expect(toWebrtcUrl(want)).toBe(want);
+  });
+
+  // parseSecret strips the "e1." marker; rebuilding from the parsed `s` would
+  // hand a legacy markerless room a marker it never had, changing the token the
+  // signaling DO pinned the room to.
+  it("round-trips a legacy markerless token unchanged", () => {
+    const legacy = `webrtc://r1:plaintexttoken@${DEFAULT_SIGHOST}`;
+    expect(toWebrtcUrl(legacy)).toBe(legacy);
+  });
+
+  it("returns null for a non-link", () => {
+    expect(toWebrtcUrl("just-an-alias")).toBeNull();
+  });
 });