agent-yes 1.290.7 → 1.291.0

package/ts/remoteHealth.spec.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import {
+  REMOTE_BACKOFF_BASE_MS,
+  REMOTE_BACKOFF_MAX_MS,
+  noteRemoteResult,
+  pruneRemoteHealth,
+  remoteBackoffMs,
+  shouldSkipRemote,
+} from "./remoteHealth.ts";
+
+describe("remoteHealth.remoteBackoffMs", () => {
+  it("doubles from the base and then holds at the cap", () => {
+    expect(remoteBackoffMs(1)).toBe(REMOTE_BACKOFF_BASE_MS);
+    expect(remoteBackoffMs(2)).toBe(REMOTE_BACKOFF_BASE_MS * 2);
+    expect(remoteBackoffMs(3)).toBe(REMOTE_BACKOFF_BASE_MS * 4);
+    expect(remoteBackoffMs(99)).toBe(REMOTE_BACKOFF_MAX_MS);
+  });
+
+  it("is zero for a host that has not failed — and this GUARDS the clause below", () => {
+    // A streak of 0 must never produce a wait: that is the difference between
+    // "healthy" and "failed once", and getting it wrong skips a live host.
+    expect(remoteBackoffMs(0)).toBe(0);
+    expect(remoteBackoffMs(-1)).toBe(0);
+
+    // This is also the tripwire for `shouldSkipRemote`'s `streak <= 0` clause.
+    // That clause is UNREACHABLE while this holds, which is why no test can
+    // redden it directly — but change the curve so a non-positive streak yields
+    // a non-zero wait and the clause goes LIVE, with nothing behind it, at the
+    // exact moment someone is editing the thing it guards. So the invariant is
+    // pinned HERE, where it is reachable and can fail loudly, instead.
+  });
+
+  it("does not overflow on an absurd streak", () => {
+    // 2 ** 5000 is Infinity; the shift clamp is what keeps this finite.
+    expect(Number.isFinite(remoteBackoffMs(5000))).toBe(true);
+  });
+});
+
+describe("remoteHealth.shouldSkipRemote", () => {
+  const NOW = 1_000_000_000;
+
+  it("never skips a host with no record — the control that matters", () => {
+    // Wrongly skipping makes an agent silently vanish from `ay ls`; wrongly
+    // probing costs one slow list. Those are not symmetric, so the tie goes to
+    // probing, and an unknown host is always probed.
+    expect(shouldSkipRemote(undefined, NOW)).toBe(false);
+    // A cleared host carrying a stale timestamp — what `noteRemoteResult`
+    // produces on success — must also never be skipped. This asserts the
+    // BEHAVIOUR; it does not isolate the `streak <= 0` clause, which is
+    // redundant with `remoteBackoffMs(0) === 0` and cannot be reddened on its
+    // own. Said plainly rather than left looking like coverage it is not.
+    expect(shouldSkipRemote({ streak: 0, lastFailedAt: NOW - 1 }, NOW)).toBe(false);
+    expect(shouldSkipRemote({ streak: -3, lastFailedAt: NOW - 1 }, NOW)).toBe(false);
+  });
+
+  it("skips inside the backoff window and probes again once it elapses", () => {
+    const h = { streak: 1, lastFailedAt: NOW };
+    expect(shouldSkipRemote(h, NOW + REMOTE_BACKOFF_BASE_MS - 1)).toBe(true);
+    expect(shouldSkipRemote(h, NOW + REMOTE_BACKOFF_BASE_MS)).toBe(false);
+  });
+
+  it("probes rather than guesses when the clock has moved backwards", () => {
+    // A backwards clock makes `elapsed` negative, which would otherwise read as
+    // "still inside the window" and skip the host until the clock caught up.
+    expect(shouldSkipRemote({ streak: 3, lastFailedAt: NOW }, NOW - 60_000)).toBe(false);
+  });
+});
+
+describe("remoteHealth.readRemoteHealth validation", () => {
+  it("ignores an entry whose shape it cannot trust", async () => {
+    // The file is derived data in a writable path. A valid-JSON record with a
+    // plausible-looking streak must not be able to hide a live agent, so
+    // anything that is not two finite numbers is dropped rather than trusted.
+    const { mkdtemp, writeFile } = await import("fs/promises");
+    const { tmpdir } = await import("os");
+    const path = (await import("path")).default;
+    const dir = await mkdtemp(path.join(tmpdir(), "ay-health-"));
+    const saved = process.env.AGENT_YES_HOME;
+    process.env.AGENT_YES_HOME = dir;
+    try {
+      await writeFile(
+        path.join(dir, "remote-health.json"),
+        JSON.stringify({
+          good: { streak: 2, lastFailedAt: 123 },
+          missingField: { streak: 2 },
+          wrongType: { streak: "9", lastFailedAt: 1 },
+          notFinite: { streak: Number.POSITIVE_INFINITY, lastFailedAt: 1 },
+          notAnObject: 7,
+        }),
+      );
+      const { readRemoteHealth } = await import("./remoteHealth.ts");
+      expect(await readRemoteHealth()).toEqual({ good: { streak: 2, lastFailedAt: 123 } });
+    } finally {
+      if (saved === undefined) delete process.env.AGENT_YES_HOME;
+      else process.env.AGENT_YES_HOME = saved;
+    }
+  });
+});
+
+describe("remoteHealth.pruneRemoteHealth", () => {
+  it("drops aliases no longer configured, so the file cannot grow forever", () => {
+    const h = {
+      live: { streak: 1, lastFailedAt: 5 },
+      removed: { streak: 9, lastFailedAt: 5 },
+    };
+    expect(pruneRemoteHealth(h, ["live"])).toEqual({ live: { streak: 1, lastFailedAt: 5 } });
+    expect(pruneRemoteHealth(h, [])).toEqual({});
+  });
+});
+
+describe("remoteHealth.noteRemoteResult", () => {
+  const NOW = 1_000_000_000;
+
+  it("clears the streak completely on success", () => {
+    // A host that comes back must return to full speed immediately, not decay
+    // through the backoff it earned while it was down.
+    expect(noteRemoteResult({ streak: 9, lastFailedAt: NOW }, true, NOW + 1)).toEqual({
+      streak: 0,
+      lastFailedAt: 0,
+    });
+  });
+
+  it("extends the streak on failure, from no record and from an existing one", () => {
+    expect(noteRemoteResult(undefined, false, NOW)).toEqual({ streak: 1, lastFailedAt: NOW });
+    expect(noteRemoteResult({ streak: 2, lastFailedAt: 1 }, false, NOW)).toEqual({
+      streak: 3,
+      lastFailedAt: NOW,
+    });
+  });
+});

package/ts/remoteHealth.ts

@@ -0,0 +1,149 @@
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { homedir } from "os";
+import path from "path";
+
+/**
+ * Backoff for remotes that are not answering.
+ *
+ * `ay ls` gathers every configured remote on every invocation. A host that has
+ * gone away costs a full `CONNECT_TIMEOUT_MS` (25s for a WebRTC spec) and
+ * returns nothing, and `Promise.allSettled` waits for all of them — so two dead
+ * entries in `remotes.yaml` made every `ay ls` on this fleet take 27s instead of
+ * 5s. Measured, then confirmed by removing only those two from a COPY of the
+ * config: 27.40s → 5.49s.
+ *
+ * Deleting the remote is the wrong remedy: those machines can come back, and a
+ * config someone must REMEMBER to re-add is a worse failure than a slow list.
+ * So the entry stays, and we stop paying for it every time.
+ *
+ * WHY EXPONENTIAL AND NOT φ: the operator's φ-backoff rule (golden ratio, no
+ * 2x) is a symval/symval convention — its AGENTS.md, its helpers. agent-yes is a
+ * general tool in snomiao/ and that rule does not reach it. This repo already
+ * has one backoff shape, `ts/autoRetry.ts` (base × 2ⁿ, capped, mirrored in
+ * rs/src/context.rs), and one repo with two backoff shapes is its own defect.
+ * So this mirrors autoRetry deliberately rather than importing a foreign
+ * convention or inventing a third.
+ */
+
+/** First skip window after a host fails. Short: a blip should barely register. */
+export const REMOTE_BACKOFF_BASE_MS = 60_000;
+/** Cap, mirroring autoRetry's shape: 1m, 2m, 4m, … 32m, then hold. */
+export const REMOTE_BACKOFF_MAX_MS = 32 * 60_000;
+
+/** One host's consecutive-failure state. Empty for a host that has never failed. */
+export interface RemoteHealth {
+  /** Consecutive failures. Reset to 0 by any success. */
+  streak: number;
+  /** When the most recent failure was recorded. */
+  lastFailedAt: number;
+}
+
+/**
+ * How long to skip a host after `streak` consecutive failures — doubling, then
+ * capped, exactly as `autoRetryBackoffMs` does.
+ */
+export function remoteBackoffMs(streak: number): number {
+  if (streak <= 0) return 0;
+  const shift = Math.min(streak - 1, 20); // guard: 2**n on an absurd streak
+  return Math.min(REMOTE_BACKOFF_BASE_MS * 2 ** shift, REMOTE_BACKOFF_MAX_MS);
+}
+
+/**
+ * Whether a host should be SKIPPED right now.
+ *
+ * Fails OPEN in every ambiguous case — no record, a zero/negative streak, a
+ * clock that has gone backwards. The cost of wrongly skipping is an agent that
+ * silently vanishes from `ay ls`; the cost of wrongly probing is one slow list.
+ * Those are not symmetric, so the tie goes to probing.
+ */
+export function shouldSkipRemote(health: RemoteHealth | undefined, now: number): boolean {
+  // The `streak <= 0` half is REDUNDANT today — `remoteBackoffMs` already
+  // returns 0 for a non-positive streak, so the comparison below is false
+  // anyway. Verified: no input distinguishes this function with and without it,
+  // which is why no test covers that clause and none pretends to. Kept because
+  // it states the invariant at the point a reader needs it, and it stops a
+  // future change to the backoff curve from silently making "healthy" skippable.
+  // The tripwire for that lives in the spec, on `remoteBackoffMs(0) === 0` —
+  // reachable, so it can actually fail — and says there that it guards this.
+  if (!health || health.streak <= 0) return false;
+  const elapsed = now - health.lastFailedAt;
+  if (elapsed < 0) return false; // clock moved backwards — probe rather than guess
+  return elapsed < remoteBackoffMs(health.streak);
+}
+
+/** Record an outcome. Success clears the streak entirely; failure extends it. */
+export function noteRemoteResult(
+  health: RemoteHealth | undefined,
+  ok: boolean,
+  now: number,
+): RemoteHealth {
+  if (ok) return { streak: 0, lastFailedAt: 0 };
+  return { streak: (health?.streak ?? 0) + 1, lastFailedAt: now };
+}
+
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+
+/**
+ * Health lives beside `remotes.yaml` in the state dir, NOT inside it: that file
+ * is the operator's config and this is derived, disposable data. Deleting it
+ * costs one slow `ay ls` and nothing else.
+ */
+function healthPath(): string {
+  const dir = process.env.AGENT_YES_HOME ?? path.join(homedir(), ".agent-yes");
+  return path.join(dir, "remote-health.json");
+}
+
+/** Read the per-alias health map. Any error yields {} — probe rather than skip. */
+export async function readRemoteHealth(): Promise<Record<string, RemoteHealth>> {
+  try {
+    const raw = await readFile(healthPath(), "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    // Validate each entry rather than trusting the file. This is derived data in
+    // a writable path: a hand-edited or half-migrated record with a plausible
+    // streak would otherwise skip a healthy host, and the whole point of the
+    // fail-open design is that no bad input can hide a live agent.
+    const out: Record<string, RemoteHealth> = {};
+    for (const [alias, v] of Object.entries(parsed as Record<string, unknown>)) {
+      if (!v || typeof v !== "object") continue;
+      const { streak, lastFailedAt } = v as Partial<RemoteHealth>;
+      if (typeof streak !== "number" || !Number.isFinite(streak)) continue;
+      if (typeof lastFailedAt !== "number" || !Number.isFinite(lastFailedAt)) continue;
+      out[alias] = { streak, lastFailedAt };
+    }
+    return out;
+  } catch {
+    return {}; // missing, unreadable, or corrupt — fail open
+  }
+}
+
+/**
+ * Best-effort write. A health file we cannot persist must never break `ay ls`.
+ *
+ * Written to a temp file and renamed, so a concurrent reader sees either the old
+ * file or the new one and never a truncated one. Two `ay ls` processes finishing
+ * together still last-writer-wins — that is acceptable here because the loser's
+ * data is one probe's worth of a self-correcting counter, and because reading a
+ * torn file already fails open to "probe".
+ */
+export async function writeRemoteHealth(health: Record<string, RemoteHealth>): Promise<void> {
+  const dest = healthPath();
+  await mkdir(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.${process.pid}.tmp`;
+  await writeFile(tmp, JSON.stringify(health, null, 2));
+  await rename(tmp, dest);
+}
+
+/**
+ * Drop entries for aliases that are no longer configured, so the file cannot
+ * grow without bound as remotes come and go. Called with the live alias set.
+ */
+export function pruneRemoteHealth(
+  health: Record<string, RemoteHealth>,
+  aliases: Iterable<string>,
+): Record<string, RemoteHealth> {
+  const live = new Set(aliases);
+  return Object.fromEntries(Object.entries(health).filter(([alias]) => live.has(alias)));
+}

package/ts/restartKillGuard.bun.spec.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "bun:test";
+import { pidOwnershipVerdict } from "./senderAncestry.ts";
+
+// The verdict cmdRestart consults before SIGKILL. What matters here is not the
+// arithmetic — that is ageMatchesRegistration's, tested with the send path —
+// but that "cannot establish" stays a THIRD answer. Collapsing it into
+// "reused" would read as caution and act as removal: win32 has no process
+// table reader, so every force-kill there would refuse forever.
+describe("restart must not SIGKILL a recycled pid", () => {
+  const now = 1_000_000_000;
+  const hourOld = now - 3600_000;
+
+  it("ours: the process is as old as the row that registered it", () => {
+    expect(pidOwnershipVerdict(3600, hourOld, now)).toBe("ours");
+  });
+
+  it("reused: the process is younger than the row, so it cannot be the agent", () => {
+    // Shape of the live case: a row surviving a reboot whose pid had been
+    // handed to an unrelated system process. Nothing in the code was declining
+    // to kill it — EPERM was, and only because the owner differed. A same-user
+    // recycled pid would have been killed.
+    expect(pidOwnershipVerdict(60, now - 89 * 86400_000, now)).toBe("reused");
+  });
+
+  it("unknown when there is no process table — NOT reused", () => {
+    // What `table?.get(pid)?.ageSecs` yields on win32, where readAncestryTable
+    // returns null by design, and on a transient ps failure.
+    expect(pidOwnershipVerdict(undefined, hourOld, now)).toBe("unknown");
+  });
+
+  it("unknown when the row carries no registration time — NOT reused", () => {
+    expect(pidOwnershipVerdict(3600, undefined, now)).toBe("unknown");
+  });
+
+  it("does not read ordinary registration lag as reuse", () => {
+    // A process is a moment older than the row recording it; if that read as
+    // reuse, restart would stop force-killing healthy agents.
+    expect(pidOwnershipVerdict(3595, hourOld, now)).toBe("ours");
+  });
+});

package/ts/restartKillGuard.spec.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { pidOwnershipVerdict } from "./senderAncestry.ts";
+
+// The verdict cmdRestart consults before SIGKILL. What matters here is not the
+// arithmetic — that is ageMatchesRegistration's, tested with the send path —
+// but that "cannot establish" stays a THIRD answer. Collapsing it into
+// "reused" would read as caution and act as removal: win32 has no process
+// table reader, so every force-kill there would refuse forever.
+describe("restart must not SIGKILL a recycled pid", () => {
+  const now = 1_000_000_000;
+  const hourOld = now - 3600_000;
+
+  it("ours: the process is as old as the row that registered it", () => {
+    expect(pidOwnershipVerdict(3600, hourOld, now)).toBe("ours");
+  });
+
+  it("reused: the process is younger than the row, so it cannot be the agent", () => {
+    // Shape of the live case: a row surviving a reboot whose pid had been
+    // handed to an unrelated system process. Nothing in the code was declining
+    // to kill it — EPERM was, and only because the owner differed. A same-user
+    // recycled pid would have been killed.
+    expect(pidOwnershipVerdict(60, now - 89 * 86400_000, now)).toBe("reused");
+  });
+
+  it("unknown when there is no process table — NOT reused", () => {
+    // What `table?.get(pid)?.ageSecs` yields on win32, where readAncestryTable
+    // returns null by design, and on a transient ps failure.
+    expect(pidOwnershipVerdict(undefined, hourOld, now)).toBe("unknown");
+  });
+
+  it("unknown when the row carries no registration time — NOT reused", () => {
+    expect(pidOwnershipVerdict(3600, undefined, now)).toBe("unknown");
+  });
+
+  it("does not read ordinary registration lag as reuse", () => {
+    // A process is a moment older than the row recording it; if that read as
+    // reuse, restart would stop force-killing healthy agents.
+    expect(pidOwnershipVerdict(3595, hourOld, now)).toBe("ours");
+  });
+});

package/ts/senderAncestry.ts

@@ -43,14 +43,28 @@ export type SenderVia =
   /** No env, but an ancestor process is a registered agent. Not forgeable from
    * inside a message: a process cannot choose its own ancestors. */
   | "ancestry"
-  /** `AGENT_YES_PID` named a registered agent that is NOT among this process's
-   * ancestors, or ancestry could not be read to check. The attribution is the
-   * caller's own claim and nothing corroborates it. Any process can export that
-   * variable, so this is the one attributed value a receiver should not trust
-   * on its own. Kept attributed rather than discarded: a stale env on an honest
-   * lane lands here too, and dropping it would be the starvation this exists to
-   * end. */
+  /** The claimed lane is NOT this process's ancestor, and the process is running
+   * OUTSIDE that lane's working tree. Another tree is claiming this identity.
+   *
+   * The discriminator is the working directory, not "is some other registered
+   * lane my ancestor" — that earlier rule was measured backwards on real
+   * traffic: it fired on a lane's own nested processes (same tree, benign) and
+   * stayed silent on two documents a different worktree sent under this lane's
+   * name. A lane's own detached helper runs inside the lane's tree; a different
+   * lane's process does not. */
   | "env-uncorroborated"
+  /** The claim could not be corroborated, and nothing contradicts it either: the
+   * process is running inside the claimed lane's own tree (so it is plausibly
+   * that lane's detached helper), or the ancestry could not be read at all.
+   *
+   * This is NOT evidence of anything. A detached helper, a process re-parented
+   * to init, an `ay send` from a background job, or an unreadable process table
+   * all land here, and every one of them is honest. Distinguishing it from a
+   * real contradiction is the whole point: the first live firing of the loud
+   * marker was a legitimate long-lived lane, and a warning that fires on honest
+   * traffic is one people learn to skip — which destroys the signal for the
+   * case it was built for. Unknown has to stay expressible AS unknown. */
+  | "env-unverified"
   /** Nothing identified the caller; only its observable facts are recorded. */
   | "observed";
 
@@ -197,6 +211,30 @@ export async function findAgentAncestor<T>(
  * Exposed so a caller can do the ancestry walk AND the pid-reuse age check off
  * a single `ps`, instead of paying for the spawn twice.
  */
+export type PidOwnership = "ours" | "reused" | "unknown";
+
+/**
+ * Whether the process holding a pid is still the agent that registered it.
+ *
+ * Three-way on purpose, and the third value is the point. "Cannot establish"
+ * is not "established that it is not ours": win32 has no process table reader
+ * here at all, so folding unknown into reused would not guard a destructive
+ * action on that platform — it would delete the action from it, permanently,
+ * to protect a case that has never occurred. Callers refuse on evidence
+ * ("reused") and keep their prior behaviour on "unknown".
+ */
+export function pidOwnershipVerdict(
+  ageSecs: number | undefined,
+  startedAt: number | undefined,
+  now = Date.now(),
+  toleranceSecs = 60,
+): PidOwnership {
+  if (ageSecs === undefined || startedAt === undefined) return "unknown";
+  return ageMatchesRegistration(ageSecs, startedAt, now, toleranceSecs)
+    ? "ours"
+    : "reused";
+}
+
 export async function readAncestryTable(
   read: () => Promise<Map<number, ProcRow>> = readProcessTable,
 ): Promise<Map<number, ProcRow> | null> {

package/ts/serve.ts

@@ -77,6 +77,7 @@ import { SUPPORTED_CLIS } from "./SUPPORTED_CLIS.ts";
 import { getInstalledPackage } from "./versionChecker.ts";
 import { negotiateSize, sanitizeCap, type SizeCap } from "./sizeNego.ts";
 import { listStrayServeProcesses } from "./strayServe.ts";
+import { isWebrtcSpec, toWebrtcUrl } from "./webrtcLink.ts";
 import {
   getProvisionHook,
   getProvisionRoot,
@@ -1160,19 +1161,17 @@ async function warnStrayServeProcesses(): Promise<void> {
   );
 }
 
-// An explicit webrtc:// URL passed to --webrtc/--share in the daemon's serve args,
-// or undefined for a bare flag (which mints a persisted room instead). Mirrors how
-// cmdServe resolves argv.webrtc/argv.share, but over the raw arg list install holds
-// (oxmgr splits the command on whitespace → `--webrtc url`; pm2/`=` → `--webrtc=url`).
+// An explicit room URL passed to --webrtc/--share in the daemon's serve args,
+// normalized to the internal webrtc:// form — or undefined for a bare flag (which
+// mints a persisted room instead). Mirrors how cmdServe resolves argv.webrtc/argv.share,
+// but over the raw arg list install holds (oxmgr splits the command on whitespace →
+// `--webrtc url`; pm2/`=` → `--webrtc=url`).
 function explicitWebrtcUrl(args: string[]): string | undefined {
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!;
     for (const flag of ["--webrtc", "--share"]) {
-      if (a === flag && args[i + 1]?.startsWith("webrtc://")) return args[i + 1];
-      if (a.startsWith(`${flag}=`)) {
-        const v = a.slice(flag.length + 1);
-        if (v.startsWith("webrtc://")) return v;
-      }
+      const v = a === flag ? args[i + 1] : a.startsWith(`${flag}=`) ? a.slice(flag.length + 1) : "";
+      if (v && isWebrtcSpec(v)) return toWebrtcUrl(v) ?? undefined;
     }
   }
   return undefined;
@@ -1630,7 +1629,8 @@ export async function cmdServe(rest: string[]): Promise<number> {
         `Modes (default: --http):\n` +
         `  --http            HTTP API + web console on --port; no WebRTC\n` +
         `  --webrtc [URL]    Share over WebRTC (bare flag mints a room+link on\n` +
-        `                    agent-yes.com, or pass webrtc://room:token@host).\n` +
+        `                    agent-yes.com, or pass a room link to join that room:\n` +
+        `                    https://agent-yes.com/room/#room=<id>&s=e1.<secret>).\n` +
         `                    Alone it needs NO port — combine with --http for both.\n` +
         `                    The minted room persists in ~/.agent-yes/.share-room\n` +
         `                    (stable link across restarts; delete the file to rotate).\n` +
@@ -1706,7 +1706,7 @@ export async function cmdServe(rest: string[]): Promise<number> {
     .option("webrtc", {
       type: "string",
       description:
-        "Share over WebRTC: bare flag mints a room+link, or pass webrtc://room:token@host. Needs no port unless combined with --http",
+        "Share over WebRTC: bare flag mints a room+link, or pass a https://…/room/#… link to join that room. Needs no port unless combined with --http",
     })
     .option("share", {
       type: "string",
@@ -1749,6 +1749,26 @@ export async function cmdServe(rest: string[]): Promise<number> {
 
   const wantWebrtc = argv.webrtc !== undefined || argv.share !== undefined;
   const wantHttp = argv.http === true || argv.share !== undefined || argv.webrtc === undefined;
+  // Resolve --webrtc/--share's value to the internal webrtc:// form up front, so a
+  // bad link fails before any port is bound or lock taken. A value that LOOKS like
+  // a room link but doesn't parse must fail LOUDLY: the old check gated on the
+  // `webrtc://` scheme alone, so every https://…/room/#… link — the shape actually
+  // printed to operators — fell through to the mint-a-fresh-room path. `--webrtc
+  // <someone else's link>` then served its OWN room while the operator believed it
+  // had joined theirs. Empty string = the bare flag, which mints by design.
+  const webrtcArg = (argv.webrtc ?? argv.share) as string | undefined;
+  let explicitRoomUrl: string | undefined;
+  if (typeof webrtcArg === "string" && webrtcArg !== "") {
+    explicitRoomUrl = (isWebrtcSpec(webrtcArg) && toWebrtcUrl(webrtcArg)) || undefined;
+    if (!explicitRoomUrl) {
+      process.stderr.write(
+        `ay serve: --webrtc: not a room link: ${webrtcArg}\n` +
+          `  want  https://agent-yes.com/room/#room=<id>&s=e1.<secret>\n` +
+          `  or a bare --webrtc to mint a room of your own\n`,
+      );
+      return 1;
+    }
+  }
   const fixedPort = typeof argv.port === "number";
   const usePortless = wantHttp && !fixedPort;
   if (argv.local === true && fixedPort) {
@@ -5062,9 +5082,8 @@ export async function cmdServe(rest: string[]): Promise<number> {
   // webrtc:// value joins an explicit one.
   let closeShare: (() => void) | undefined; // closes WebRTC peers on shutdown
   if (wantWebrtc) {
-    const webrtcVal = (argv.webrtc ?? argv.share) as string | undefined;
-    const explicitUrl =
-      typeof webrtcVal === "string" && webrtcVal.startsWith("webrtc://") ? webrtcVal : undefined;
+    // Validated (and normalized to webrtc://) up front, alongside wantWebrtc.
+    const explicitUrl = explicitRoomUrl;
     try {
       const { startShare, loadOrCreateShareRoom } = await import("./share.ts");
       const linkFile = path.join(
@@ -5073,7 +5092,7 @@ export async function cmdServe(rest: string[]): Promise<number> {
       );
       // Announce the link — reused for the initial share and for any auto-rotation
       // (when the signaling server rejects a stale persisted room).
-      const announce = async (room: string, link: string, rotated: boolean) => {
+      const announce = async (room: string, link: string, joinLink: string, rotated: boolean) => {
         const lead = rotated
           ? "the room was rejected by signaling (stale generation) — rotated to a fresh link"
           : "shared over WebRTC — open this link (the token is eaten from the URL on open)";
@@ -5081,7 +5100,12 @@ export async function cmdServe(rest: string[]): Promise<number> {
           const persistNote = explicitUrl
             ? "\n"
             : `  (persistent room — same link across restarts; delete ~/.agent-yes/.share-room to rotate)\n\n`;
-          process.stdout.write(`${wantHttp ? "\n" : ""}${lead}:\n  ${link}\n` + persistNote);
+          process.stdout.write(
+            `${wantHttp ? "\n" : ""}${lead}:\n  ${link}\n` +
+              `\nto attach ANOTHER machine to this room, open this there (or paste it into\n` +
+              `\`ay serve --webrtc\`) — one machine per link:\n  ${joinLink}\n` +
+              persistNote,
+          );
           // Offer to open the console (default yes) on the FIRST share only —
           // an auto-rotation shouldn't pop a fresh tab from under the operator.
           if (!rotated) {
@@ -5092,7 +5116,7 @@ export async function cmdServe(rest: string[]): Promise<number> {
           // Non-TTY (daemon/journal/CI): the link embeds the room secret S, so never
           // write it to a log stream. Stash it in a 0600 file and point there instead.
           try {
-            await writeFile(linkFile, link + "\n", { mode: 0o600 });
+            await writeFile(linkFile, `${link}\n${joinLink}\n`, { mode: 0o600 });
           } catch {
             /* best effort */
           }
@@ -5106,14 +5130,16 @@ export async function cmdServe(rest: string[]): Promise<number> {
       // saved like the serve token), so the link is stable across restarts.
       // Only the persisted path may auto-rotate (onRotate set); an explicit URL
       // is the operator's choice and must not be silently changed.
-      const { room, link, close } = await startShare({
+      const { room, link, joinLink, close } = await startShare({
         url: explicitUrl ?? (await loadOrCreateShareRoom()),
         localFetch: apiFetch,
         apiToken: token,
-        onRotate: explicitUrl ? undefined : (info) => announce(info.room, info.link, true),
+        onRotate: explicitUrl
+          ? undefined
+          : (info) => announce(info.room, info.link, info.joinLink, true),
       });
       closeShare = close;
-      await announce(room, link, false);
+      await announce(room, link, joinLink, false);
     } catch (e) {
       process.stderr.write(`ay serve --webrtc failed: ${(e as Error).message}\n`);
       if (!wantHttp) {

package/ts/share.bun.spec.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "bun:test";
-import { shareLinkFromRoomUrl } from "./share.ts";
+import { formatRoomLink, shareLinkFromRoomUrl } from "./share.ts";
+import { parseWebrtcLink, toWebrtcUrl } from "./webrtcLink.ts";
 import { MARKER } from "../lab/ui/e2e.js";
 
 const S = "a".repeat(64); // a valid 64-hex room secret
@@ -31,6 +32,27 @@ describe("shareLinkFromRoomUrl", () => {
   });
 
   it("rejects a malformed room url", () => {
-    expect(() => shareLinkFromRoomUrl("not-a-webrtc-url")).toThrow(/webrtc:\/\//);
+    // The message must name the shape operators actually hold (the /room/ link),
+    // not the internal webrtc:// form they are never shown.
+    expect(() => shareLinkFromRoomUrl("not-a-webrtc-url")).toThrow(/\/room\/#room=/);
+  });
+});
+
+// The /room/ link is BOTH what an operator opens in a browser and what they
+// paste into `ay serve --webrtc`. So whatever formatRoomLink prints must survive
+// the CLI's own parser — if these two ever drift, the printed link stops working
+// in the tool that printed it, which no other test would catch.
+describe("formatRoomLink \u2194 the CLI parser", () => {
+  it("prints a link toWebrtcUrl normalizes back to the same room", () => {
+    const link = formatRoomLink("r1a2b3c", S, "s.agent-yes.com");
+    expect(link).toBe(`https://agent-yes.com/room/#room=r1a2b3c&s=${MARKER}${S}`);
+    expect(toWebrtcUrl(link)).toBe(`webrtc://r1a2b3c:${MARKER}${S}@s.agent-yes.com`);
+    expect(parseWebrtcLink(link)).toEqual({ room: "r1a2b3c", s: S, host: "s.agent-yes.com" });
+  });
+
+  it("carries a non-prod signaling host as sig= and round-trips it too", () => {
+    const link = formatRoomLink("r1a2b3c", S, "localhost:7778");
+    expect(link).toContain("sig=localhost%3A7778");
+    expect(parseWebrtcLink(link)).toMatchObject({ room: "r1a2b3c", host: "localhost:7778" });
   });
 });

package/ts/share.spec.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
-import { shareLinkFromRoomUrl } from "./share.ts";
+import { formatRoomLink, shareLinkFromRoomUrl } from "./share.ts";
+import { parseWebrtcLink, toWebrtcUrl } from "./webrtcLink.ts";
 import { MARKER } from "../lab/ui/e2e.js";
 
 const S = "a".repeat(64); // a valid 64-hex room secret
@@ -31,6 +32,27 @@ describe("shareLinkFromRoomUrl", () => {
   });
 
   it("rejects a malformed room url", () => {
-    expect(() => shareLinkFromRoomUrl("not-a-webrtc-url")).toThrow(/webrtc:\/\//);
+    // The message must name the shape operators actually hold (the /room/ link),
+    // not the internal webrtc:// form they are never shown.
+    expect(() => shareLinkFromRoomUrl("not-a-webrtc-url")).toThrow(/\/room\/#room=/);
+  });
+});
+
+// The /room/ link is BOTH what an operator opens in a browser and what they
+// paste into `ay serve --webrtc`. So whatever formatRoomLink prints must survive
+// the CLI's own parser — if these two ever drift, the printed link stops working
+// in the tool that printed it, which no other test would catch.
+describe("formatRoomLink \u2194 the CLI parser", () => {
+  it("prints a link toWebrtcUrl normalizes back to the same room", () => {
+    const link = formatRoomLink("r1a2b3c", S, "s.agent-yes.com");
+    expect(link).toBe(`https://agent-yes.com/room/#room=r1a2b3c&s=${MARKER}${S}`);
+    expect(toWebrtcUrl(link)).toBe(`webrtc://r1a2b3c:${MARKER}${S}@s.agent-yes.com`);
+    expect(parseWebrtcLink(link)).toEqual({ room: "r1a2b3c", s: S, host: "s.agent-yes.com" });
+  });
+
+  it("carries a non-prod signaling host as sig= and round-trips it too", () => {
+    const link = formatRoomLink("r1a2b3c", S, "localhost:7778");
+    expect(link).toContain("sig=localhost%3A7778");
+    expect(parseWebrtcLink(link)).toMatchObject({ room: "r1a2b3c", host: "localhost:7778" });
   });
 });