agent-yes 1.204.0 → 1.206.0

package/ts/serve.ts

@@ -38,7 +38,9 @@ import {
 } from "./subcommands.ts";
 import { TYPING_BADGE } from "./badges.ts";
 import { isTerminalReply } from "./terminalReply.ts";
+import { parseStatusText } from "./statusText.ts";
 import { ensureNodeRuntime, liveEnv } from "./nodeRuntime.ts";
+import { acquireWebrtcHostLock, type ServeLockOwner } from "./serveLock.ts";
 import { type MailParty, recordInbox } from "./messageLog.ts";
 import { updateGlobalPidStatus } from "./globalPidIndex.ts";
 import { spawnRejectionReason } from "./spawnGate.ts";
@@ -57,7 +59,56 @@ import {
   resolveSpawnCwd,
 } from "./workspaceConfig.ts";
 
-const DEFAULT_PORT = 7432;
+const DEFAULT_PORT = 0;
+const PORTLESS_APP_NAME = "agent-yes";
+const PORTLESS_CHILD_ENV = "AGENT_YES_PORTLESS_CHILD";
+
+export function portlessConsoleUrl(token?: string): string {
+  return portlessConsoleUrlForOrigin(
+    process.env.PORTLESS_URL?.replace(/\/$/, "") || `https://${PORTLESS_APP_NAME}.localhost`,
+    token,
+  );
+}
+
+function portlessConsoleUrlForOrigin(origin: string, token?: string): string {
+  const fragment = token ? `/#k=${encodeURIComponent(token)}` : "/";
+  return `${origin}${fragment}`;
+}
+
+async function resolvedPortlessConsoleUrl(token?: string): Promise<string> {
+  if (process.env.PORTLESS_URL) return portlessConsoleUrl(token);
+  try {
+    const port = Number(
+      (await readFile(path.join(homedir(), ".portless", "proxy.port"), "utf-8")).trim(),
+    );
+    if (Number.isInteger(port) && port > 0)
+      return portlessConsoleUrlForOrigin(
+        `https://${PORTLESS_APP_NAME}.localhost${port === 443 ? "" : `:${port}`}`,
+        token,
+      );
+  } catch {
+    /* Portless has not created state yet. */
+  }
+  return portlessConsoleUrl(token);
+}
+
+async function runWithPortless(rest: string[]): Promise<number> {
+  const portless = Bun.which("portless");
+  if (!portless) {
+    process.stderr.write(
+      "ay serve: Portless is required for local HTTPS. Install it with: npm install -g portless\n",
+    );
+    return 1;
+  }
+  const script = process.argv[1];
+  const self =
+    script && /\.[cm]?[jt]s$/.test(script) ? [process.execPath, script] : [process.execPath];
+  const proc = Bun.spawn([portless, PORTLESS_APP_NAME, ...self, "serve", ...rest], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: { ...liveEnv(), [PORTLESS_CHILD_ENV]: "1" },
+  });
+  return (await proc.exited) ?? 1;
+}
 
 /**
  * Normalize a user-supplied GitHub-ish source into the standard
@@ -703,9 +754,28 @@ async function readDaemonServeArgs(mgr: DaemonManager): Promise<string[] | null>
   }
 }
 
-function portFromArgs(args: string[]): number {
+function portFromArgs(args: string[]): number | null {
   const m = /--port[=\s](\d+)/.exec(args.join(" "));
-  return m ? Number(m[1]) : DEFAULT_PORT;
+  return m ? Number(m[1]) : null;
+}
+
+function argsUsePortless(args: string[]): boolean {
+  const wantsHttp =
+    args.some((a) => a.startsWith("--http") || a.startsWith("--share")) ||
+    !args.some((a) => a.startsWith("--webrtc"));
+  return wantsHttp && portFromArgs(args) === null;
+}
+
+async function portlessAppPort(): Promise<number | null> {
+  try {
+    const routes = JSON.parse(
+      await readFile(path.join(homedir(), ".portless", "routes.json"), "utf-8"),
+    ) as { hostname?: string; port?: number }[];
+    const route = routes.find((r) => r.hostname === `${PORTLESS_APP_NAME}.localhost`);
+    return typeof route?.port === "number" ? route.port : null;
+  } catch {
+    return null;
+  }
 }
 
 async function warnStrayServeProcesses(): Promise<void> {
@@ -740,7 +810,8 @@ function explicitWebrtcUrl(args: string[]): string | undefined {
 // Ask the live daemon its version over the local HTTP API. null if it's not
 // listening (webrtc-only) or too old to expose /api/version — both of which we
 // treat as "outdated" so a re-install rolls it forward.
-async function fetchDaemonVersion(port: number, token: string): Promise<string | null> {
+async function fetchDaemonVersion(port: number | null, token: string): Promise<string | null> {
+  if (port === null) return null;
   try {
     const r = await fetch(`http://127.0.0.1:${port}/api/version`, {
       headers: { Authorization: `Bearer ${token}` },
@@ -888,7 +959,8 @@ async function cmdServeDaemon(sub: string, args: string[]): Promise<number> {
       // share link for a WebRTC bridge that isn't actually running. A bare re-run
       // passes no args, so effArgs === priorArgs and this stays a no-op as before.
       const sameConfig = JSON.stringify(effArgs) === JSON.stringify(priorArgs);
-      const runningVer = await fetchDaemonVersion(portFromArgs(effArgs), token);
+      const daemonPort = argsUsePortless(effArgs) ? await portlessAppPort() : portFromArgs(effArgs);
+      const runningVer = await fetchDaemonVersion(daemonPort, token);
       if (runningVer === current && sameConfig) {
         await ensureBootAutostart(mgr);
         process.stdout.write(`'${DAEMON_NAME}' already running v${current} (up to date)\n`);
@@ -981,7 +1053,8 @@ async function cmdServeDaemon(sub: string, args: string[]): Promise<number> {
     const code = await proc.exited;
     if (code === 0) {
       const onBoot = await ensureBootAutostart(mgr);
-      const port = portFromArgs(effArgs);
+      const port = argsUsePortless(effArgs) ? await portlessAppPort() : portFromArgs(effArgs);
+      const localUrl = argsUsePortless(effArgs) ? await resolvedPortlessConsoleUrl(token) : null;
       // Mirror cmdServe's mode resolution: webrtc-only daemons open no HTTP port.
       const httpish =
         effArgs.some((a) => a.startsWith("--http") || a.startsWith("--share")) ||
@@ -1019,8 +1092,12 @@ async function cmdServeDaemon(sub: string, args: string[]): Promise<number> {
         );
       process.stdout.write(`token: ${token}\n\n`);
       if (httpish) {
-        process.stdout.write(`  ay ls   ${token}@<host>:${port}\n`);
-        process.stdout.write(`  ay remote add <alias> http://${token}@<host>:${port}\n`);
+        if (argsUsePortless(effArgs)) {
+          process.stdout.write(`  web console: ${localUrl}\n`);
+        } else if (port !== null) {
+          process.stdout.write(`  ay ls   ${token}@<host>:${port}\n`);
+          process.stdout.write(`  ay remote add <alias> http://${token}@<host>:${port}\n`);
+        }
       }
       process.stdout.write(`  ay serve logs                # view server logs\n`);
       process.stdout.write(`  ay serve uninstall           # remove daemon\n`);
@@ -1053,7 +1130,9 @@ async function cmdServeStatus(args: string[]): Promise<number> {
   const daemonArgs = mgr ? await readDaemonServeArgs(mgr) : null;
   const installed = daemonArgs !== null;
   const a = daemonArgs ?? [];
-  const port = portFromArgs(a);
+  const local = argsUsePortless(a);
+  const port = local ? await portlessAppPort() : portFromArgs(a);
+  const localUrl = local ? await resolvedPortlessConsoleUrl(token ?? undefined) : null;
   // Mirror cmdServe/install mode resolution: webrtc when --webrtc/--share; http
   // when --http/--share OR no --webrtc at all (http is the implicit default).
   const webrtcish = a.some((x) => x.startsWith("--webrtc") || x.startsWith("--share"));
@@ -1075,6 +1154,7 @@ async function cmdServeStatus(args: string[]): Promise<number> {
           installed,
           mode,
           port: httpish ? port : null,
+          localUrl: httpish ? localUrl : null,
           reachable: runningVersion !== null,
           runningVersion,
           currentVersion: current,
@@ -1095,25 +1175,32 @@ async function cmdServeStatus(args: string[]): Promise<number> {
   w(`manager:      ${mgr ? mgr.id : "none — install pm2 or oxmgr to daemonize"}`);
   if (installed) {
     w(`installed:    yes (via ${mgr!.id})`);
-    w(`mode:         ${mode}${httpish ? `  (port ${port})` : ""}`);
+    w(`mode:         ${mode}${httpish ? (local ? `  (${localUrl})` : `  (port ${port})`) : ""}`);
     if (a.length) w(`args:         ${a.join(" ")}`);
   } else {
     w(`installed:    no — start a daemon with:  ay serve install [--share]`);
   }
   if (runningVersion !== null) {
     const tag = runningVersion === current ? "up to date" : `outdated (current v${current})`;
-    w(`http api:     reachable on 127.0.0.1:${port} — v${runningVersion} (${tag})`);
+    w(
+      `http api:     reachable ${local ? `via ${localUrl}` : `on 127.0.0.1:${port}`} — v${runningVersion} (${tag})`,
+    );
   } else if (mode === "webrtc") {
     w(`http api:     none (webrtc-only)`);
   } else {
-    w(`http api:     not reachable on 127.0.0.1:${port} (not running)`);
+    w(
+      `http api:     not reachable ${local ? `via ${localUrl}` : `on 127.0.0.1:${port}`} (not running)`,
+    );
   }
   w(`token:        ${token ?? "(none yet — created on first serve)"}`);
   if (shareLink) w(`share link:   ${shareLink}`);
   if (token && httpish) {
     w();
-    w(`connect:  ay ls   ${token}@<host>:${port}`);
-    w(`          ay remote add <alias> http://${token}@<host>:${port}`);
+    if (local) w(`console:  ${localUrl}`);
+    else if (port !== null) {
+      w(`connect:  ay ls   ${token}@<host>:${port}`);
+      w(`          ay remote add <alias> http://${token}@<host>:${port}`);
+    }
   }
   return 0;
 }
@@ -1137,11 +1224,13 @@ export async function cmdServe(rest: string[]): Promise<number> {
         `                    (stable link across restarts; delete the file to rotate).\n` +
         `  --share [URL]     Legacy alias for --http --webrtc\n\n` +
         `Options:\n` +
-        `  --port N          Port to listen on (default: ${DEFAULT_PORT})\n` +
+        `  --port N          Bypass Portless and listen on a fixed HTTP port\n` +
         `  --host HOST       Interface to bind (default: 127.0.0.1; use 0.0.0.0 to expose)\n` +
         `  --token TOKEN     Auth token (auto-generated and saved if omitted)\n` +
         `  -d, --daemon      Install these flags as a background daemon (pm2/oxmgr)\n` +
         `                    (same as: ay serve install <flags>)\n` +
+        `  --local           Explicitly use Portless (the default for HTTP mode)\n` +
+        `                    ${portlessConsoleUrl()}\n` +
         `  --allow-spawn     Deprecated no-op — the console can always spawn agents\n` +
         `  --tls-cert FILE   TLS certificate PEM\n` +
         `  --tls-key  FILE   TLS private key PEM\n\n` +
@@ -1151,8 +1240,8 @@ export async function cmdServe(rest: string[]): Promise<number> {
         `  ay serve uninstall  remove daemon\n` +
         `  ay serve logs       view daemon logs\n\n` +
         `Once running, connect from another machine:\n` +
-        `  ay ls   <token>@<host>:${DEFAULT_PORT}\n` +
-        `  ay remote add <alias> http://<token>@<host>:${DEFAULT_PORT}\n`,
+        `  ay ls   <token>@<host>:<port>\n` +
+        `  ay remote add <alias> http://<token>@<host>:<port>\n`,
     );
     return 0;
   }
@@ -1188,7 +1277,7 @@ export async function cmdServe(rest: string[]): Promise<number> {
 
   const y = yargs(rest)
     .usage("Usage: ay serve [options]")
-    .option("port", { type: "number", default: DEFAULT_PORT, description: "Port to listen on" })
+    .option("port", { type: "number", description: "Bypass Portless and listen on a fixed port" })
     .option("host", {
       type: "string",
       default: "127.0.0.1",
@@ -1216,11 +1305,22 @@ export async function cmdServe(rest: string[]): Promise<number> {
       default: false,
       description: "Install as a background daemon (same as: ay serve install <flags>)",
     })
+    .option("local", {
+      type: "boolean",
+      default: false,
+      description: `Use Portless at ${portlessConsoleUrl()} (default for HTTP mode)`,
+    })
     .option("allow-spawn", {
       type: "boolean",
       default: false,
       description: "Deprecated no-op — the console can always spawn agents",
     })
+    .option("takeover", {
+      type: "boolean",
+      default: false,
+      description:
+        "If another ay serve already hosts this home's WebRTC room, stop it and take the room",
+    })
     .help(false)
     .version(false)
     .exitProcess(false);
@@ -1234,6 +1334,18 @@ export async function cmdServe(rest: string[]): Promise<number> {
     return cmdServeDaemon("install", fwd);
   }
 
+  const wantWebrtc = argv.webrtc !== undefined || argv.share !== undefined;
+  const wantHttp = argv.http === true || argv.share !== undefined || argv.webrtc === undefined;
+  const fixedPort = typeof argv.port === "number";
+  const usePortless = wantHttp && !fixedPort;
+  if (argv.local === true && fixedPort) {
+    process.stderr.write("ay serve: --local and --port cannot be used together\n");
+    return 1;
+  }
+  if (usePortless && process.env[PORTLESS_CHILD_ENV] !== "1" && process.env.PORTLESS !== "0") {
+    return runWithPortless(rest);
+  }
+
   // `ay serve` takes only flags (plus the install/uninstall/logs subcommands
   // handled above). A bare word like `ay serve share` is silently dropped into
   // argv._ by yargs and would otherwise start in the wrong mode — most often
@@ -1254,7 +1366,7 @@ export async function cmdServe(rest: string[]): Promise<number> {
   // top-level agents regardless of the spawn path.
   delete process.env.AGENT_YES_PID;
 
-  const port = (argv.port as number) ?? DEFAULT_PORT;
+  const port = (argv.port as number | undefined) ?? (Number(process.env.PORT) || DEFAULT_PORT);
   const host = (argv.host as string) ?? "127.0.0.1";
   const tokenFlag = typeof argv.token === "string" ? argv.token : undefined;
   const certPath = typeof argv["tls-cert"] === "string" ? argv["tls-cert"] : undefined;
@@ -1270,8 +1382,31 @@ export async function cmdServe(rest: string[]): Promise<number> {
   // Modes: --http (HTTP listener + web console), --webrtc (port-free WebRTC
   // share), or both. Bare `ay serve` stays HTTP-only; --share keeps its old
   // meaning (HTTP + WebRTC) for existing invocations.
-  const wantWebrtc = argv.webrtc !== undefined || argv.share !== undefined;
-  const wantHttp = argv.http === true || argv.share !== undefined || argv.webrtc === undefined;
+
+  // Singleton WebRTC host per ~/.agent-yes: a second host joining the SAME
+  // persisted room (~/.agent-yes/.share-room) fights the first over every
+  // viewer connection — seen live as an unloadable share link plus the managed
+  // daemon crash-looping under the health watchdog while an orphaned manual
+  // `ay serve --webrtc` held the room. Fail fast with a pointer to the owner
+  // instead of contending. HTTP-only serves skip this (port collisions already
+  // fail naturally with EADDRINUSE). AGENT_YES_NO_SERVE_LOCK=1 opts out for
+  // exotic multi-room setups (explicit webrtc:// URLs to different rooms).
+  let releaseHostLock: (() => Promise<void>) | null = null;
+  if (wantWebrtc && process.env.AGENT_YES_NO_SERVE_LOCK !== "1") {
+    const lock = await acquireWebrtcHostLock({ takeover: argv.takeover === true });
+    if (!lock.ok) {
+      const o: ServeLockOwner | null = lock.owner;
+      const since = o ? new Date(o.started_at).toLocaleString() : "unknown";
+      process.stderr.write(
+        `ay serve: another instance${o ? ` (pid ${o.pid}, started ${since})` : ""} already hosts this home's WebRTC room\n` +
+          `  ay serve status              # inspect it\n` +
+          `  ay serve --webrtc --takeover # stop it and take the room\n` +
+          `  AGENT_YES_NO_SERVE_LOCK=1    # opt out (multi-room setups only)\n`,
+      );
+      return 1;
+    }
+    releaseHostLock = lock.release;
+  }
 
   if (wantHttp && host !== "127.0.0.1" && host !== "localhost") {
     process.stderr.write(
@@ -1404,6 +1539,28 @@ export async function cmdServe(rest: string[]): Promise<number> {
     }
   };
 
+  // Per-agent live status description from the rendered screen. Claude Code
+  // paints a spinner/status line while working; surfacing it lets the left panel
+  // show "what it's doing" without opening the terminal.
+  const statusTextCache = new Map<
+    string,
+    { size: number; mtimeMs: number; statusText: string | null }
+  >();
+  const logStatusText = async (logFile: string | null | undefined): Promise<string | null> => {
+    if (!logFile) return null;
+    try {
+      const { size, mtimeMs } = await stat(logFile);
+      const hit = statusTextCache.get(logFile);
+      if (hit && hit.size === size && hit.mtimeMs === mtimeMs) return hit.statusText;
+      const lines = await renderLogTailLines(logFile, 40);
+      const statusText = lines ? parseStatusText(lines) : null;
+      statusTextCache.set(logFile, { size, mtimeMs, statusText });
+      return statusText;
+    } catch {
+      return null;
+    }
+  };
+
   // Per-agent "waiting on you" detection: the agent is parked on an interactive
   // menu it did NOT auto-resolve (config `needsInput` patterns). Same source and
   // classifier as `ay ls` / `ay status`, so the console's dot matches the CLI's
@@ -1670,6 +1827,7 @@ export async function cmdServe(rest: string[]): Promise<number> {
       // WHAT the agent is waiting on. Null otherwise.
       question,
       title: await logTitle(r.log_file),
+      status_text: status === "exited" ? null : await logStatusText(r.log_file),
       git: status === "exited" ? null : await gitStatus(r.cwd),
       // Task progress from the rendered todo block (null when none detected → no
       // badge). Skipped for exited agents — their screen is no longer live.
@@ -3177,17 +3335,20 @@ export async function cmdServe(rest: string[]): Promise<number> {
     // server is null only when we degraded to WebRTC-only above (port wedged);
     // skip the HTTP connection banner since nothing is listening on the port.
     if (server) {
+      const listenPort = server.port;
       const uiHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
-      process.stdout.write(`ay serve  ${scheme}://${host}:${port}\n`);
+      process.stdout.write(`ay serve  ${scheme}://${host}:${listenPort}\n`);
       process.stdout.write(`token:    ${token}\n\n`);
       process.stdout.write(`web console (token in the # is eaten on open):\n`);
-      process.stdout.write(`  ${scheme}://${uiHost}:${port}/#k=${token}\n\n`);
+      process.stdout.write(
+        `  ${usePortless ? portlessConsoleUrl(token) : `${scheme}://${uiHost}:${listenPort}/#k=${token}`}\n\n`,
+      );
       process.stdout.write(`connect from another machine:\n`);
-      process.stdout.write(`  ay ls   ${token}@<host>:${port}\n`);
-      process.stdout.write(`  ay tail ${token}@<host>:${port}:<keyword>\n`);
-      process.stdout.write(`  ay send ${token}@<host>:${port}:<keyword> "message"\n\n`);
+      process.stdout.write(`  ay ls   ${token}@<host>:${listenPort}\n`);
+      process.stdout.write(`  ay tail ${token}@<host>:${listenPort}:<keyword>\n`);
+      process.stdout.write(`  ay send ${token}@<host>:${listenPort}:<keyword> "message"\n\n`);
       process.stdout.write(`save as alias:\n`);
-      process.stdout.write(`  ay remote add <alias> ${scheme}://${token}@<host>:${port}\n\n`);
+      process.stdout.write(`  ay remote add <alias> ${scheme}://${token}@<host>:${listenPort}\n\n`);
       if (!useHttps) {
         process.stdout.write(
           `for HTTPS: ay serve --tls-cert cert.pem --tls-key key.pem\n` +
@@ -3257,7 +3418,12 @@ export async function cmdServe(rest: string[]): Promise<number> {
       await announce(room, link, false);
     } catch (e) {
       process.stderr.write(`ay serve --webrtc failed: ${(e as Error).message}\n`);
-      if (!wantHttp) return 1; // nothing else is running
+      if (!wantHttp) {
+        // Release promptly so the manager's instant respawn doesn't have to
+        // wait out the stale window to reclaim the host lock.
+        await releaseHostLock?.().catch(() => {});
+        return 1; // nothing else is running
+      }
     }
   }
 
@@ -3289,7 +3455,12 @@ export async function cmdServe(rest: string[]): Promise<number> {
     // Close any scoped single-agent share rooms so viewers get an immediate drop.
     void import("./agentShare.ts").then((m) => m.revokeAllShares()).catch(() => {});
     server?.stop();
-    resolve();
+    // Gate exit on the lock release: resolve() ends cmdServe and the process,
+    // and an un-awaited rm would race that exit — leaving a lock the next host
+    // (a manager's instant respawn) must wait a full stale window to steal.
+    void Promise.resolve(releaseHostLock?.())
+      .catch(() => {})
+      .then(resolve);
   };
   await new Promise<void>((resolve) => {
     process.on("SIGINT", () => shutdown(resolve));

package/ts/serveLock.spec.ts

@@ -0,0 +1,219 @@
+import { mkdtemp, readFile, rm } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  acquireWebrtcHostLock,
+  isOwnerStale,
+  SERVE_LOCK_STALE_MS,
+  type ServeLockOwner,
+} from "./serveLock.ts";
+
+// Guards the single-WebRTC-host invariant: two `ay serve --webrtc` in one home
+// fight over the persisted room (live outage: orphan host + crash-looping
+// managed daemon + unloadable share link). The loser must fail FAST with the
+// owner's identity, and a dead/stale owner must never wedge the next start.
+describe("acquireWebrtcHostLock", () => {
+  let home: string;
+  let savedHome: string | undefined;
+  const releases: Array<() => Promise<void>> = [];
+
+  beforeEach(async () => {
+    home = await mkdtemp(path.join(tmpdir(), "ay-serve-lock-"));
+    savedHome = process.env.AGENT_YES_HOME;
+    process.env.AGENT_YES_HOME = home;
+  });
+
+  afterEach(async () => {
+    for (const r of releases.splice(0)) await r().catch(() => {});
+    if (savedHome === undefined) delete process.env.AGENT_YES_HOME;
+    else process.env.AGENT_YES_HOME = savedHome;
+    await rm(home, { recursive: true, force: true });
+  });
+
+  it("acquires, stamps an owner, and a second acquire fails fast with that owner", async () => {
+    const first = await acquireWebrtcHostLock({ graceMs: 0 });
+    expect(first.ok).toBe(true);
+    if (first.ok) releases.push(first.release);
+
+    const owner = JSON.parse(
+      await readFile(path.join(home, "webrtc-host.lock", "owner.json"), "utf-8"),
+    ) as ServeLockOwner;
+    expect(owner.pid).toBe(process.pid);
+
+    const second = await acquireWebrtcHostLock({ graceMs: 0 });
+    expect(second.ok).toBe(false);
+    if (!second.ok) expect(second.owner?.pid).toBe(process.pid);
+  });
+
+  it("release frees the lock for the next acquire", async () => {
+    const first = await acquireWebrtcHostLock({ graceMs: 0 });
+    expect(first.ok).toBe(true);
+    if (first.ok) await first.release();
+
+    const second = await acquireWebrtcHostLock({ graceMs: 0 });
+    expect(second.ok).toBe(true);
+    if (second.ok) releases.push(second.release);
+  });
+
+  it("steals a stale lock whose heartbeat went quiet (SIGKILLed host)", async () => {
+    // Forge an owner: alive pid but ancient beat — a host whose interval died.
+    const lockDir = path.join(home, "webrtc-host.lock");
+    const { mkdir, writeFile } = await import("fs/promises");
+    await mkdir(lockDir, { recursive: true });
+    await writeFile(
+      path.join(lockDir, "owner.json"),
+      JSON.stringify({
+        pid: process.pid,
+        started_at: Date.now() - 60_000,
+        beat_at: Date.now() - SERVE_LOCK_STALE_MS - 1_000,
+      }),
+    );
+    const got = await acquireWebrtcHostLock({ graceMs: 0 });
+    expect(got.ok).toBe(true);
+    if (got.ok) releases.push(got.release);
+  });
+
+  it("steals a lock whose owner pid is dead", async () => {
+    // A freshly-exited child pid is reliably dead. Spawn the current runtime
+    // (bun or node — both take -e) so this also runs on Windows, via
+    // node:child_process (not Bun.spawn) for the node vitest matrix.
+    const { spawnSync } = await import("node:child_process");
+    const deadPid = spawnSync(process.execPath, ["-e", "0"]).pid!;
+
+    const lockDir = path.join(home, "webrtc-host.lock");
+    const { mkdir, writeFile } = await import("fs/promises");
+    await mkdir(lockDir, { recursive: true });
+    await writeFile(
+      path.join(lockDir, "owner.json"),
+      JSON.stringify({ pid: deadPid, started_at: Date.now(), beat_at: Date.now() }),
+    );
+    const got = await acquireWebrtcHostLock({ graceMs: 0 });
+    expect(got.ok).toBe(true);
+    if (got.ok) releases.push(got.release);
+  });
+});
+
+describe("isOwnerStale", () => {
+  const now = 1_000_000;
+  const owner = (beatAgo: number): ServeLockOwner => ({
+    pid: 4242,
+    started_at: now - 60_000,
+    beat_at: now - beatAgo,
+  });
+
+  it("absent/torn owner is stale (mkdir won but the write died)", () => {
+    expect(isOwnerStale(null, now, () => true)).toBe(true);
+  });
+
+  it("dead pid is stale regardless of heartbeat", () => {
+    expect(isOwnerStale(owner(0), now, () => false)).toBe(true);
+  });
+
+  it("live pid with a fresh beat is NOT stale", () => {
+    expect(isOwnerStale(owner(SERVE_LOCK_STALE_MS - 1), now, () => true)).toBe(false);
+  });
+
+  it("live pid with a quiet heartbeat past the window is stale", () => {
+    expect(isOwnerStale(owner(SERVE_LOCK_STALE_MS + 1), now, () => true)).toBe(true);
+  });
+});
+
+// Coverage for the held-lock lifecycle: heartbeat refresh, thief detection,
+// live-owner takeover, and the bounded grace wait.
+describe("acquireWebrtcHostLock — held-lock lifecycle", () => {
+  let home: string;
+  let savedHome: string | undefined;
+  const releases: Array<() => Promise<void>> = [];
+
+  beforeEach(async () => {
+    home = await mkdtemp(path.join(tmpdir(), "ay-serve-lock2-"));
+    savedHome = process.env.AGENT_YES_HOME;
+    process.env.AGENT_YES_HOME = home;
+  });
+
+  afterEach(async () => {
+    for (const r of releases.splice(0)) await r().catch(() => {});
+    if (savedHome === undefined) delete process.env.AGENT_YES_HOME;
+    else process.env.AGENT_YES_HOME = savedHome;
+    await rm(home, { recursive: true, force: true });
+  });
+
+  const ownerFile = () => path.join(home, "webrtc-host.lock", "owner.json");
+  const readOwnerFile = async () => JSON.parse(await readFile(ownerFile(), "utf-8")) as ServeLockOwner;
+
+  it("heartbeats refresh beat_at while held", async () => {
+    const got = await acquireWebrtcHostLock({ graceMs: 0, beatMs: 40 });
+    expect(got.ok).toBe(true);
+    if (got.ok) releases.push(got.release);
+    const before = (await readOwnerFile()).beat_at;
+    await new Promise((r) => setTimeout(r, 150));
+    const after = (await readOwnerFile()).beat_at;
+    expect(after).toBeGreaterThan(before);
+  });
+
+  it("heartbeat stops itself once a thief owns the file (never clobbers the thief)", async () => {
+    const got = await acquireWebrtcHostLock({ graceMs: 0, beatMs: 40 });
+    expect(got.ok).toBe(true);
+    if (got.ok) releases.push(got.release);
+    const { writeFile: wf } = await import("fs/promises");
+    const thief: ServeLockOwner = { pid: process.pid + 1, started_at: Date.now(), beat_at: 42 };
+    await wf(ownerFile(), JSON.stringify(thief));
+    await new Promise((r) => setTimeout(r, 150));
+    expect((await readOwnerFile()).pid).toBe(thief.pid); // our beat backed off
+    expect((await readOwnerFile()).beat_at).toBe(42);
+  });
+
+  it("takeover stops a live owner and takes the room", async () => {
+    const { spawn } = await import("node:child_process");
+    // Long-lived victim via the current runtime — /bin/sh doesn't exist on win32.
+    const victim = spawn(process.execPath, ["-e", "setTimeout(() => {}, 30000)"], {
+      stdio: "ignore",
+    });
+    const victimPid = victim.pid!;
+    const { mkdir: mkd, writeFile: wf } = await import("fs/promises");
+    await mkd(path.join(home, "webrtc-host.lock"), { recursive: true });
+    await wf(
+      ownerFile(),
+      JSON.stringify({ pid: victimPid, started_at: Date.now(), beat_at: Date.now() }),
+    );
+
+    const got = await acquireWebrtcHostLock({ takeover: true, graceMs: 0, takeoverWaitMs: 100 });
+    expect(got.ok).toBe(true);
+    if (got.ok) releases.push(got.release);
+    expect((await readOwnerFile()).pid).toBe(process.pid);
+    // The victim was killed (SIGTERM or the escalation SIGKILL).
+    await new Promise((r) => setTimeout(r, 100));
+    expect(victim.exitCode !== null || victim.signalCode !== null).toBe(true);
+  });
+
+  it.skipIf(process.platform === "win32")(
+    "escalates to SIGKILL when the owner ignores SIGTERM",
+    async () => {
+    const { spawn } = await import("node:child_process");
+    const stubborn = spawn("/bin/sh", ["-c", "trap '' TERM; sleep 30"], { stdio: "ignore" });
+    const pid = stubborn.pid!;
+    await new Promise((r) => setTimeout(r, 100)); // let the trap install
+    const { mkdir: mkd, writeFile: wf } = await import("fs/promises");
+    await mkd(path.join(home, "webrtc-host.lock"), { recursive: true });
+    await wf(ownerFile(), JSON.stringify({ pid, started_at: Date.now(), beat_at: Date.now() }));
+
+    const got = await acquireWebrtcHostLock({ takeover: true, graceMs: 0, takeoverWaitMs: 200 });
+    expect(got.ok).toBe(true);
+    if (got.ok) releases.push(got.release);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(stubborn.signalCode).toBe("SIGKILL");
+    },
+  );
+
+  it("waits out the grace window against a live owner, then reports it", async () => {
+    const holder = await acquireWebrtcHostLock({ graceMs: 0 });
+    expect(holder.ok).toBe(true);
+    if (holder.ok) releases.push(holder.release);
+    const t0 = Date.now();
+    const got = await acquireWebrtcHostLock({ graceMs: 300 });
+    expect(got.ok).toBe(false);
+    if (!got.ok) expect(got.owner?.pid).toBe(process.pid);
+    expect(Date.now() - t0).toBeGreaterThanOrEqual(250); // actually waited a beat
+  });
+});