agent-yes 1.122.2 → 1.123.0

package/ts/serve.ts

@@ -1,5 +1,5 @@
-import { mkdir, open, readFile, writeFile } from "fs/promises";
-import { watch } from "node:fs";
+import { mkdir, open, readFile, stat, writeFile } from "fs/promises";
+import { renameSync, watch, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createHash, randomBytes, timingSafeEqual } from "crypto";
 import { homedir, hostname, userInfo } from "os";
@@ -7,6 +7,7 @@ import path from "path";
 import yargs from "yargs";
 import {
   controlCodeFromName,
+  extractTaskCounts,
   listRecords,
   readNotes,
   renderRawLog,
@@ -15,6 +16,8 @@ import {
   writeToIpc,
   type CommonOpts,
 } from "./subcommands.ts";
+import { updateGlobalPidStatus } from "./globalPidIndex.ts";
+import { pgidForWrapper } from "./reaper.ts";
 import { SUPPORTED_CLIS } from "./SUPPORTED_CLIS.ts";
 import { getInstalledPackage } from "./versionChecker.ts";
 
@@ -28,6 +31,19 @@ function tokenPath(): string {
   return path.join(agentYesHome(), ".serve-token");
 }
 
+// Liveness heartbeat for the WebRTC daemon. The native WebRTC stack
+// (node-datachannel) has been observed to freeze the entire JS event loop after
+// long uptime — main thread stuck in a pthread rendezvous — so signaling stays
+// connected but the host answers nobody, and NO in-process timer (self-heal,
+// idle-restart) can recover it because JS has stopped running. The serve loop
+// stamps this file every HEARTBEAT_WRITE_MS; `ay serve healthcheck` reports the
+// daemon unhealthy once it goes stale, and oxmgr's --health-cmd restarts it.
+function heartbeatPath(): string {
+  return path.join(agentYesHome(), ".serve-heartbeat");
+}
+const HEARTBEAT_WRITE_MS = 5_000;
+const HEARTBEAT_STALE_MS = 15_000; // event loop is wedged if no stamp this long (3 missed)
+
 async function loadOrCreateToken(tokenFlag?: string): Promise<string> {
   if (tokenFlag) return tokenFlag;
   try {
@@ -320,9 +336,42 @@ async function cmdServeDaemon(sub: string, args: string[]): Promise<number> {
     // args after `--`. Both auto-restart on crash by default (pm2) / via the
     // explicit flag (oxmgr).
     const serveArgv = ayServeArgv(effArgs);
+    // WebRTC daemons get an oxmgr health watchdog: the native WebRTC stack can
+    // freeze the JS event loop (host answers nobody, no in-process timer can
+    // recover it), so an EXTERNAL probe of the serve heartbeat is the only thing
+    // that can detect+restart it. 15s stale + 3 misses at 10s ≈ 45s to auto-recover.
+    const webrtcDaemon = effArgs.some((a) => a.startsWith("--webrtc") || a.startsWith("--share"));
+    const oxmgrHealth =
+      webrtcDaemon && mgr.id === "oxmgr"
+        ? [
+            "--health-cmd",
+            ayServeArgv(["healthcheck"]).join(" "),
+            "--health-interval",
+            "10",
+            "--health-timeout",
+            "5",
+            "--health-max-failures",
+            "3",
+          ]
+        : [];
     const startArgv =
       mgr.id === "oxmgr"
-        ? [mgr.bin, "start", serveArgv.join(" "), "--name", DAEMON_NAME, "--restart", "always"]
+        ? [
+            mgr.bin,
+            "start",
+            serveArgv.join(" "),
+            "--name",
+            DAEMON_NAME,
+            "--restart",
+            "always",
+            // Persistent daemon: oxmgr's default lifetime cap of 10 restarts would
+            // eventually stop respawning it (updates, reboots, the health-watchdog
+            // recovering a frozen WebRTC stack). Raise it far out of the way; the
+            // crash-restart-limit still guards against a tight crash loop.
+            "--max-restarts",
+            "1000000",
+            ...oxmgrHealth,
+          ]
         : [
             mgr.bin,
             "start",
@@ -528,6 +577,28 @@ export async function cmdServe(rest: string[]): Promise<number> {
   // Daemon subcommands
   const sub = rest[0];
   if (sub === "status") return cmdServeStatus(rest.slice(1));
+  if (sub === "healthcheck") {
+    // oxmgr --health-cmd liveness probe. Exit non-zero only when the heartbeat is
+    // demonstrably stale (event loop wedged), so the manager restarts us. A
+    // missing/just-started/unparseable heartbeat is treated as healthy to avoid
+    // flapping a daemon that simply hasn't stamped yet.
+    try {
+      const raw = (await readFile(heartbeatPath(), "utf-8")).trim();
+      const ts = Number(raw);
+      // Only declare unhealthy on a VALID, genuinely-old stamp. Empty/partial/NaN
+      // (Number("") === 0!) is treated as healthy so a torn read or a not-yet-
+      // written file can't trigger a false restart. (Writes are atomic via
+      // temp+rename, so a torn read shouldn't happen — this is belt-and-braces.)
+      const age = Date.now() - ts;
+      if (raw.length > 0 && Number.isFinite(ts) && ts > 0 && age > HEARTBEAT_STALE_MS) {
+        process.stderr.write(`unhealthy: serve heartbeat stale by ${age}ms\n`);
+        return 1;
+      }
+    } catch {
+      /* no heartbeat yet — treat as healthy */
+    }
+    return 0;
+  }
   if (sub === "install" || sub === "uninstall" || sub === "logs") {
     return cmdServeDaemon(sub, rest.slice(1));
   }
@@ -655,11 +726,40 @@ export async function cmdServe(rest: string[]): Promise<number> {
     }
   };
 
-  // Per-cwd git snapshot for the list: branch + dirty/changed count + ahead/behind
-  // vs upstream, all from a single `git status --porcelain --branch`. Cached per
-  // cwd with a short TTL so the 1s subscribe tick (and /api/ls polls) spawn at most
-  // one git per repo every few seconds — agents sharing a cwd share the result.
-  // Non-git dirs, errors, and timeouts cache as null.
+  // Per-agent task progress ({done,total}) parsed from the agent's rendered TUI
+  // screen (the durable raw log). Cached per (size, mtime) exactly like logTitle:
+  // re-parse only when the log grew, so the 1s tick stays cheap even though each
+  // parse renders a log window through xterm. Works for every CLI — the source is
+  // the drawn todo block, not a CLI-specific session file. See extractTaskCounts.
+  const taskCache = new Map<
+    string,
+    { size: number; mtimeMs: number; tasks: { done: number; total: number } | null }
+  >();
+  const logTasks = async (
+    logFile: string | null | undefined,
+  ): Promise<{ done: number; total: number } | null> => {
+    if (!logFile) return null;
+    try {
+      const { size, mtimeMs } = await stat(logFile);
+      const hit = taskCache.get(logFile);
+      if (hit && hit.size === size && hit.mtimeMs === mtimeMs) return hit.tasks;
+      const tasks = await extractTaskCounts(logFile);
+      taskCache.set(logFile, { size, mtimeMs, tasks });
+      return tasks;
+    } catch {
+      return null;
+    }
+  };
+
+  // Per-repo git snapshot for the list (branch + dirty/changed + ahead/behind, from
+  // one `git status --porcelain --branch`). WATCHER-INVALIDATED, not polled: a read
+  // returns the cached snapshot instantly and NEVER spawns `git status` on the
+  // request path. A per-repo-root fs watcher recomputes (debounced) only when the
+  // repo actually changes, so an idle fleet costs ~0 git processes. The old design
+  // forked one `git status` per agent every poll tick — with dozens of agents that
+  // concurrent fan-out pinned host load (high load-average, low CPU: fork + I/O,
+  // not compute). Modeled on VSCode's git extension: watch + debounce, no interval
+  // poll (just a slow safety recompute for events a watcher might miss).
   interface GitInfo {
     branch: string | null;
     dirty: boolean;
@@ -667,16 +767,11 @@ export async function cmdServe(rest: string[]): Promise<number> {
     ahead: number;
     behind: number;
   }
-  const GIT_TTL_MS = 5000;
-  const gitCache = new Map<string, { at: number; val: GitInfo | null }>();
-  const gitStatus = async (cwd: string | null | undefined): Promise<GitInfo | null> => {
-    if (!cwd) return null;
-    const now = Date.now();
-    const hit = gitCache.get(cwd);
-    if (hit && now - hit.at < GIT_TTL_MS) return hit.val;
-    let val: GitInfo | null = null;
+  const GIT_DEBOUNCE_MS = 800; // coalesce a burst of edits into one recompute
+  const GIT_SAFETY_MS = 60_000; // backstop recompute for any missed watch event
+  const runGit = async (args: string[], cwd: string): Promise<string | null> => {
     try {
-      const proc = Bun.spawn(["git", "status", "--porcelain", "--branch"], {
+      const proc = Bun.spawn(["git", ...args], {
         cwd,
         stdout: "pipe",
         stderr: "ignore",
@@ -684,23 +779,89 @@ export async function cmdServe(rest: string[]): Promise<number> {
       });
       const out = await new Response(proc.stdout).text();
       await proc.exited;
-      if (proc.exitCode === 0) {
-        const lines = out.split("\n");
-        // Branch header, e.g. "## main...origin/main [ahead 1, behind 2]",
-        // "## main" (no upstream), "## HEAD (no branch)", or "## No commits yet on x".
-        const h = /^## (.+)$/.exec(lines[0] ?? "")?.[1] ?? "";
-        const unborn = /^No commits yet on (.+)$/.exec(h);
-        const branch = unborn ? unborn[1]! : /^(.+?)(?:\.\.\.|\s|$)/.exec(h)?.[1] || null;
-        const ahead = Number(/\bahead (\d+)/.exec(h)?.[1] ?? 0);
-        const behind = Number(/\bbehind (\d+)/.exec(h)?.[1] ?? 0);
-        const changed = lines.slice(1).filter((l) => l.trim().length > 0).length;
-        val = { branch, dirty: changed > 0, changed, ahead, behind };
+      return proc.exitCode === 0 ? out : null;
+    } catch {
+      return null; // git missing, not a repo, or timed out
+    }
+  };
+  const parseGitStatus = (out: string): GitInfo => {
+    const lines = out.split("\n");
+    // Branch header, e.g. "## main...origin/main [ahead 1, behind 2]", "## main"
+    // (no upstream), "## HEAD (no branch)", or "## No commits yet on x".
+    const h = /^## (.+)$/.exec(lines[0] ?? "")?.[1] ?? "";
+    const unborn = /^No commits yet on (.+)$/.exec(h);
+    const branch = unborn ? unborn[1]! : /^(.+?)(?:\.\.\.|\s|$)/.exec(h)?.[1] || null;
+    const ahead = Number(/\bahead (\d+)/.exec(h)?.[1] ?? 0);
+    const behind = Number(/\bbehind (\d+)/.exec(h)?.[1] ?? 0);
+    const changed = lines.slice(1).filter((l) => l.trim().length > 0).length;
+    return { branch, dirty: changed > 0, changed, ahead, behind };
+  };
+  // cwd -> repo root ("" = resolved, not a repo). Resolved once per cwd via a cheap
+  // `git rev-parse --show-toplevel` (no tree scan) and cached, so many agents in the
+  // same repo (or its submodules/subdirs) share one watcher + snapshot.
+  const rootOfCwd = new Map<string, string>();
+  const resolveRoot = async (cwd: string): Promise<string> => {
+    const cached = rootOfCwd.get(cwd);
+    if (cached !== undefined) return cached;
+    const root = ((await runGit(["rev-parse", "--show-toplevel"], cwd)) ?? "").trim();
+    rootOfCwd.set(cwd, root);
+    return root;
+  };
+  interface RepoWatch {
+    val: GitInfo | null;
+    busy: boolean;
+    timer: ReturnType<typeof setTimeout> | null;
+  }
+  const repoWatch = new Map<string, RepoWatch>();
+  const recompute = (root: string, rw: RepoWatch) => {
+    if (rw.timer) return; // a recompute is already queued (debounce + throttle)
+    rw.timer = setTimeout(async () => {
+      rw.timer = null;
+      if (rw.busy) return void recompute(root, rw); // re-arm if one is in flight
+      rw.busy = true;
+      try {
+        const out = await runGit(["status", "--porcelain", "--branch"], root);
+        if (out != null) rw.val = parseGitStatus(out);
+      } finally {
+        rw.busy = false;
       }
+    }, GIT_DEBOUNCE_MS);
+  };
+  const ensureRepoWatch = (root: string): RepoWatch => {
+    const existing = repoWatch.get(root);
+    if (existing) return existing;
+    const rw: RepoWatch = { val: null, busy: false, timer: null };
+    repoWatch.set(root, rw);
+    recompute(root, rw); // initial snapshot
+    // Ignore high-churn paths that never change `git status` output: our own log
+    // dir (.agent-yes, written on every PTY byte — would re-trigger forever),
+    // gitignored deps (node_modules), and git's own lock files.
+    const onChange = (file: string) => {
+      if (file.includes(".agent-yes") || file.includes("node_modules") || file.endsWith(".lock"))
+        return;
+      recompute(root, rw);
+    };
+    try {
+      // macOS/Windows: one recursive watcher (FSEvents/ReadDirectoryChanges) covers
+      // the working tree (dirty) AND .git (branch/ahead-behind) cheaply.
+      watch(root, { recursive: true }, (_e, f) => onChange(String(f ?? "")));
     } catch {
-      val = null; // git missing, not a repo, or timed out
+      // Recursive watch unsupported (some Linux/Bun builds): watch .git only —
+      // catches commit/branch/stage instantly; dirty count rides the safety tick.
+      try {
+        watch(path.join(root, ".git"), (_e, f) => onChange(".git/" + String(f ?? "")));
+      } catch {
+        /* no watcher available — rely solely on the safety recompute */
+      }
     }
-    gitCache.set(cwd, { at: now, val });
-    return val;
+    setInterval(() => recompute(root, rw), GIT_SAFETY_MS);
+    return rw;
+  };
+  const gitStatus = async (cwd: string | null | undefined): Promise<GitInfo | null> => {
+    if (!cwd) return null;
+    const root = await resolveRoot(cwd);
+    if (!root) return null; // not a git repo
+    return ensureRepoWatch(root).val; // cached — the request path never spawns `git status`
   };
 
   // One agent record decorated for the console: the latest OSC title + a git
@@ -709,6 +870,9 @@ export async function cmdServe(rest: string[]): Promise<number> {
     ...r,
     title: await logTitle(r.log_file),
     git: r.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.
+    tasks: r.status === "exited" ? null : await logTasks(r.log_file),
   });
 
   // The whole API as a plain handler: served over HTTP by Bun.serve (--http)
@@ -1056,6 +1220,59 @@ export async function cmdServe(rest: string[]): Promise<number> {
       }
     }
 
+    // POST /api/kill  body {keyword}  — force-kill a stuck agent. The console can
+    // already send keystrokes (Ctrl+C, /exit) via /api/send; this is the escalation
+    // for an agent too wedged to respond to those: a real SIGKILL of its process
+    // GROUP (wrapper + CLI + children), via the pgid the reaper recorded. The >1
+    // guards are critical — process.kill(-1)/kill(0) would signal far too much.
+    if (req.method === "POST" && p === "/api/kill") {
+      let body: { keyword?: string };
+      try {
+        body = (await req.json()) as typeof body;
+      } catch {
+        return new Response("invalid JSON body", { status: 400 });
+      }
+      const keyword = body.keyword;
+      if (!keyword || typeof keyword !== "string")
+        return new Response("missing keyword", { status: 400 });
+      if (process.platform === "win32")
+        return new Response("force-kill unsupported on a Windows serve", { status: 501 });
+      try {
+        const record = await resolveOne(keyword, defaultOpts({ all: true }));
+        const killed: string[] = [];
+        const sig = (target: number, label: string) => {
+          if (!target || target <= 1) return;
+          try {
+            process.kill(target, "SIGKILL");
+            killed.push(label);
+          } catch {
+            /* ESRCH: already gone */
+          }
+        };
+        // Whole process group first (kills children too), then the pids directly in
+        // case they aren't group leaders.
+        const pgid = await pgidForWrapper(record.wrapper_pid ?? 0);
+        if (pgid && pgid > 1) {
+          try {
+            process.kill(-pgid, "SIGKILL");
+            killed.push(`group ${pgid}`);
+          } catch {
+            /* group already gone */
+          }
+        }
+        sig(record.pid, `pid ${record.pid}`);
+        if (record.wrapper_pid && record.wrapper_pid !== record.pid)
+          sig(record.wrapper_pid, `wrapper ${record.wrapper_pid}`);
+        await updateGlobalPidStatus(record.pid, {
+          status: "exited",
+          exit_reason: "force-killed via console",
+        }).catch(() => {});
+        return Response.json({ ok: true, pid: record.pid, killed });
+      } catch (e) {
+        return new Response((e as Error).message, { status: 404 });
+      }
+    }
+
     // POST /api/resize/:keyword  body {cols, rows} — drive the agent's PTY size.
     // Mirrors `ay attach`: write ~/.agent-yes/winsize/<pid> then SIGWINCH; the
     // agent's resize listener picks it up and reflows its TUI to that width.
@@ -1266,19 +1483,37 @@ export async function cmdServe(rest: string[]): Promise<number> {
     }
   }
 
+  // Liveness heartbeat (WebRTC daemons only — that's where the native stack can
+  // freeze the loop). If the event loop wedges, this interval stops firing, the
+  // file goes stale, and oxmgr's --health-cmd (ay serve healthcheck) restarts us.
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+  if (wantWebrtc) {
+    const stamp = () => {
+      try {
+        // Atomic: write a temp file then rename over the target, so a concurrent
+        // `ay serve healthcheck` reader never sees a truncated/partial timestamp.
+        const tmp = `${heartbeatPath()}.tmp`;
+        writeFileSync(tmp, String(Date.now()));
+        renameSync(tmp, heartbeatPath());
+      } catch {
+        /* best effort */
+      }
+    };
+    stamp();
+    heartbeat = setInterval(stamp, HEARTBEAT_WRITE_MS);
+  }
+
   process.stdout.write(`(Ctrl-C to stop)\n`);
 
+  const shutdown = (resolve: () => void) => {
+    if (heartbeat) clearInterval(heartbeat);
+    closeShare?.();
+    server?.stop();
+    resolve();
+  };
   await new Promise<void>((resolve) => {
-    process.on("SIGINT", () => {
-      closeShare?.();
-      server?.stop();
-      resolve();
-    });
-    process.on("SIGTERM", () => {
-      closeShare?.();
-      server?.stop();
-      resolve();
-    });
+    process.on("SIGINT", () => shutdown(resolve));
+    process.on("SIGTERM", () => shutdown(resolve));
   });
 
   return 0;

package/ts/share.ts

@@ -37,6 +37,35 @@ const HOST_HEARTBEAT_MS = 20000; // keepalive ping to the rendezvous + silent-dr
 // heartbeat never trips. Re-running the hello on a timer forces the DO to
 // re-register us, self-healing that state. Cheap: one reconnect per few minutes.
 const SIG_REFRESH_MS = 4 * 60_000;
+// If building a peer connection fails this many times in a row, the native
+// WebRTC stack (node-datachannel) is wedged — observed after long daemon uptime:
+// signaling stays connected and peer-joins arrive, but every createOffer fails,
+// so the host silently answers nobody and the room looks "offline". Reconnecting
+// the socket can't clear it; only a fresh process can. Exit so the service
+// manager restarts us with a clean stack (a fresh process provably works).
+const MAX_PEER_SETUP_FAILURES = 3;
+// Serialize peer setup. The recurring live freeze is an upstream libdatachannel
+// 0.24.2 deadlock tripped by a RECONNECT STORM — several browser tabs/devices all
+// reconnecting at once (e.g. right after the daemon restarts) fire many concurrent
+// real-DTLS handshakes, which wedges the native stack. Process peer-joins one at a
+// time with a small gap so a burst is staggered instead of simultaneous.
+const PEER_JOIN_GAP_MS = 300;
+// Abandon a peer setup that doesn't settle in time (a wedged native createOffer
+// would otherwise stall the whole serial queue) — counts as a setup failure so
+// the self-heal can fire. And cap the queue so a pathological storm can't grow it
+// unboundedly; dropped joins simply retry via the browser's reconnect.
+const STARTPEER_TIMEOUT_MS = 10_000;
+const MAX_PEER_JOIN_QUEUE = 50;
+// Proactively recycle the process to PREVENT the node-datachannel freeze rather
+// than just recover from it. The wedge has been observed at ~60-90min uptime, so
+// restarting well before that keeps the native stack fresh and the freeze rare.
+// Two thresholds (relies on the daemon's `--restart always` policy):
+//   - IDLE: when there are no active peers, refresh early during a quiet moment.
+//   - HARD: a ceiling that fires even mid-session (closing peers gracefully so
+//     browsers reconnect in ~1s) — a ~1s blip every ~45min beats a ~90s freeze.
+const IDLE_RESTART_UPTIME_MS = 25 * 60_000;
+const HARD_RESTART_UPTIME_MS = 45 * 60_000;
+const IDLE_RESTART_CHECK_MS = 60_000;
 
 type IceServer = { urls: string | string[]; username?: string; credential?: string };
 const STUN: IceServer[] = [{ urls: "stun:stun.l.google.com:19302" }];
@@ -191,6 +220,14 @@ async function ensureAddon(ndDir: string): Promise<void> {
   }
 }
 
+// NOTE on the node-datachannel freeze: holding libdatachannel's global init alive
+// via preload() was tried here — it prevents a *loopback* churn freeze (rapid
+// create/close, reproduced at ~1400 cycles) but did NOT fix the live freeze, which
+// is a separate upstream libdatachannel 0.24.2 deadlock triggered by real browser
+// DTLS connections (esp. reconnection storms across multiple tabs). preload() is
+// unproven under that live load, so it's not used; the proactive recycle + oxmgr
+// health watchdog remain the mitigation until node-datachannel ships libdatachannel
+// >0.24.2 (cf upstream #1538/#1548).
 async function importRTC(): Promise<any> {
   // Ensure the native addon is on disk before the first import — a failed
   // dynamic import is cached by Bun, so post-import healing can't recover it.
@@ -243,7 +280,8 @@ export async function startShare(
   let S = firstS;
 
   const wsScheme = host.startsWith("localhost") || host.startsWith("127.") ? "ws" : "wss";
-  const ui = host === "s.agent-yes.com" ? "https://agent-yes.com" : "http://localhost:7778";
+  // The console web-app is served under /w/ (landing page lives at /).
+  const ui = host === "s.agent-yes.com" ? "https://agent-yes.com/w" : "http://localhost:7778/w";
   const suffix = host === "s.agent-yes.com" ? "" : "@" + host;
   const mkLink = () => `${ui}/#${room}:${MARKER}${S}${suffix}`;
   let authToken = await deriveAuthToken(S, room, host);
@@ -299,6 +337,61 @@ export async function startShare(
   const peers = new Map<string, Peer>();
   let closed = false; // set by close(); stops signaling reconnect + new peers
   let currentWs: WebSocket | undefined; // the live rendezvous socket, for close()
+  let peerSetupFailures = 0; // consecutive startPeer() throws — see MAX_PEER_SETUP_FAILURES
+
+  // Serial peer-join queue (see PEER_JOIN_GAP_MS): drain one at a time so a
+  // reconnect storm can't fire many concurrent DTLS handshakes and wedge the
+  // native stack. startPeer() awaits its async steps, yielding the event loop
+  // between peers, so this staggers setup without blocking the loop / heartbeat.
+  const peerJoinQueue: string[] = [];
+  let drainingPeerJoins = false;
+  const drainPeerJoins = async () => {
+    if (drainingPeerJoins) return;
+    drainingPeerJoins = true;
+    try {
+      while (!closed && peerJoinQueue.length) {
+        const peerId = peerJoinQueue.shift()!;
+        const ws = currentWs; // send offer/candidates on the live socket
+        if (!ws) continue;
+        try {
+          // Bound it: a wedged native createOffer must not stall the queue forever.
+          let timer: ReturnType<typeof setTimeout>;
+          const setup = startPeer(ws, peerId);
+          // If it times out, startPeer keeps running (native calls can't be
+          // cancelled) and may settle later — swallow that so it isn't an
+          // unhandled rejection; startPeer itself no-ops a late offer (peer guard).
+          setup.catch(() => {});
+          await Promise.race([
+            setup,
+            new Promise((_, reject) => {
+              timer = setTimeout(
+                () => reject(new Error("startPeer timeout")),
+                STARTPEER_TIMEOUT_MS,
+              );
+            }),
+          ]).finally(() => clearTimeout(timer!));
+          peerSetupFailures = 0; // a delivered offer proves the WebRTC stack works
+        } catch (err) {
+          // Don't swallow this: a failed createOffer is why a long-up host goes
+          // silently "offline". Surface it, and if it keeps failing, self-heal.
+          peerSetupFailures++;
+          process.stderr.write(
+            `[share] peer setup failed (${peerSetupFailures}/${MAX_PEER_SETUP_FAILURES}): ${(err as Error)?.message ?? err}\n`,
+          );
+          closePeer(peerId);
+          if (peerSetupFailures >= MAX_PEER_SETUP_FAILURES) {
+            process.stderr.write(
+              "[share] WebRTC stack wedged after repeated peer-setup failures — exiting so the service manager restarts with a fresh stack\n",
+            );
+            process.exit(1);
+          }
+        }
+        if (peerJoinQueue.length) await new Promise((r) => setTimeout(r, PEER_JOIN_GAP_MS));
+      }
+    } finally {
+      drainingPeerJoins = false;
+    }
+  };
 
   const connectSignaling = (onReady: () => void) => {
     if (closed) return; // a reconnect timer queued before close() must not revive it
@@ -355,8 +448,20 @@ export async function startShare(
       lastRecv = Date.now();
       const m = JSON.parse(ev.data as string);
       if (m.type === "pong") return; // heartbeat ack — liveness already recorded
-      if (m.type === "peer-join") startPeer(ws, m.peer).catch(() => {});
-      else if (m.type === "answer") {
+      if (m.type === "peer-join") {
+        // Serialized in drainPeerJoins() to avoid a storm. Skip dupes (already
+        // queued or already an active peer) and cap the queue so a pathological
+        // burst can't grow it unboundedly — dropped joins retry via the browser.
+        const pid = String(m.peer);
+        if (
+          !peers.has(pid) &&
+          !peerJoinQueue.includes(pid) &&
+          peerJoinQueue.length < MAX_PEER_JOIN_QUEUE
+        ) {
+          peerJoinQueue.push(pid);
+          drainPeerJoins();
+        }
+      } else if (m.type === "answer") {
         const peer = peers.get(m.from);
         if (!peer) return;
         try {
@@ -467,6 +572,22 @@ export async function startShare(
     };
     const offer = await pc.createOffer();
     await pc.setLocalDescription(offer);
+    // The setup may have been abandoned while we built the offer. If THIS peer is
+    // no longer the map entry (serial-queue timeout closed it / a peer-leave
+    // arrived and its createOffer only just now resolved), close only this
+    // orphaned pc — don't closePeer(peerId) by id, which could hit a different
+    // entry. If it's still us but the socket was recycled (SIG_REFRESH_MS), drop
+    // cleanly; the browser re-joins on the fresh socket.
+    if (peers.get(peerId) !== peer) {
+      try {
+        peer.pc.close();
+      } catch {}
+      return;
+    }
+    if (ws.readyState !== WebSocket.OPEN) {
+      closePeer(peerId);
+      return;
+    }
     // Hand the browser the same ICE servers (incl. the short-lived TURN creds)
     // so it can relay too when there's no direct path.
     ws.send(
@@ -605,12 +726,44 @@ export async function startShare(
   await new Promise<void>((resolve) => connectSignaling(resolve));
   void minted; // (informational) caller decides how to surface the link
 
+  // Proactive restart to PREVENT the node-datachannel freeze (~60-90min onset):
+  // refresh the native stack well before it can wedge. Idle path refreshes early
+  // during a quiet moment; the hard ceiling fires even mid-session, closing peers
+  // gracefully first so browsers reconnect in ~1s (a tiny blip beats a ~90s
+  // freeze). Daemon-only (non-TTY): a foreground `ay serve` has no restart
+  // manager, so exiting would just stop sharing — and the user is there to act.
+  const startedAt = Date.now();
+  const proactiveRestart = process.stdout.isTTY
+    ? undefined
+    : setInterval(() => {
+        if (closed) return;
+        const up = Date.now() - startedAt;
+        if (peers.size === 0 && up > IDLE_RESTART_UPTIME_MS) {
+          process.stderr.write("[share] proactive restart (idle): refreshing the WebRTC stack\n");
+          process.exit(0); // `--restart always` brings us back with a fresh stack
+        } else if (up > HARD_RESTART_UPTIME_MS) {
+          process.stderr.write(
+            "[share] proactive restart (max uptime): closing peers, refreshing the WebRTC stack\n",
+          );
+          // graceful: DataChannel close → browsers reconnect to the fresh process.
+          // finally-guard the exit so a throw in close() can't leave us dead-but-
+          // not-respawned.
+          try {
+            close();
+          } finally {
+            setTimeout(() => process.exit(0), 250); // let close frames flush first
+          }
+        }
+      }, IDLE_RESTART_CHECK_MS);
+  proactiveRestart?.unref?.(); // don't keep the event loop alive on this timer alone
+
   // Clean shutdown: stop the rendezvous (so it can't reconnect or accept new
   // peers) and close every peer connection so browsers get an immediate
   // DataChannel close and reconnect right away, instead of waiting out the
   // ~15-30s ICE timeout that an abrupt process exit would otherwise force.
   const close = () => {
     closed = true;
+    if (proactiveRestart) clearInterval(proactiveRestart);
     try {
       currentWs?.close();
     } catch {