agent-yes 1.175.0 → 1.176.0

package/lab/ui/index.html

@@ -303,6 +303,178 @@
         background: var(--line);
         margin: 4px 2px;
       }
+      /* View-only share: read-only badge in the header + hiding write controls. */
+      .robadge {
+        display: none;
+        align-items: center;
+        gap: 4px;
+        font-size: 11px;
+        font-weight: 600;
+        padding: 2px 8px;
+        border-radius: 999px;
+        color: #b45309;
+        background: color-mix(in srgb, #f59e0b 18%, transparent);
+        border: 1px solid color-mix(in srgb, #f59e0b 45%, transparent);
+        white-space: nowrap;
+      }
+      .app.readonly-agent .robadge {
+        display: inline-flex;
+      }
+      /* A viewer can't steer/share — hide the composer, key bar and every agent
+         action in the ⋯ menu (Share/Stop/Restart/Kill). View prefs stay. */
+      .app.readonly-agent .composer,
+      .app.readonly-agent .keybar,
+      .app.readonly-agent .rmenuact {
+        display: none !important;
+      }
+      /* Read-write (steer) share: the viewer CAN type, so composer + key bar stay.
+         But they aren't granted control/admin, so hide stop/restart/kill/share. */
+      .rwbadge {
+        display: none;
+        align-items: center;
+        gap: 4px;
+        font-size: 11px;
+        font-weight: 600;
+        padding: 2px 8px;
+        border-radius: 999px;
+        color: #7c3aed;
+        background: color-mix(in srgb, #8b5cf6 18%, transparent);
+        border: 1px solid color-mix(in srgb, #8b5cf6 45%, transparent);
+        white-space: nowrap;
+      }
+      .app.steer-agent .rwbadge {
+        display: inline-flex;
+      }
+      .app.steer-agent #stopAgent,
+      .app.steer-agent #restartAgent,
+      .app.steer-agent #killAgent,
+      .app.steer-agent #shareAgent,
+      .app.steer-agent #shareAgentRW {
+        display: none !important;
+      }
+      /* Share modal — QR + link for a single-agent view-only share. */
+      .modal-backdrop {
+        position: fixed;
+        inset: 0;
+        background: rgba(0, 0, 0, 0.55);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 60;
+        padding: 16px;
+      }
+      .modal-backdrop[hidden] {
+        display: none;
+      }
+      .sharebox {
+        background: var(--bg);
+        color: var(--fg);
+        border: 1px solid var(--line);
+        border-radius: 12px;
+        max-width: 380px;
+        width: 100%;
+        padding: 20px;
+        box-shadow: 0 12px 40px rgba(0, 0, 0, 0.4);
+      }
+      .sharebox h3 {
+        margin: 0 0 4px;
+        font-size: 15px;
+      }
+      .sharebox .sub {
+        margin: 0 0 14px;
+        font-size: 12px;
+        opacity: 0.7;
+      }
+      .sharebox .qr {
+        display: flex;
+        justify-content: center;
+        padding: 12px;
+        background: #fff;
+        border-radius: 8px;
+        margin: 0 auto 14px;
+        width: fit-content;
+      }
+      .sharebox .qr canvas {
+        display: block;
+        image-rendering: pixelated;
+      }
+      .sharebox .shareurl {
+        width: 100%;
+        box-sizing: border-box;
+        font: 11px var(--mono);
+        padding: 8px;
+        border: 1px solid var(--line);
+        border-radius: 6px;
+        background: var(--bg2, var(--bg));
+        color: var(--fg);
+        word-break: break-all;
+      }
+      .sharebox .srow {
+        display: flex;
+        gap: 8px;
+        margin-top: 12px;
+      }
+      .sharebox button {
+        flex: 1;
+        padding: 9px;
+        border-radius: 8px;
+        border: 1px solid var(--line);
+        background: var(--bg2, var(--bg));
+        color: var(--fg);
+        cursor: pointer;
+        font-size: 13px;
+      }
+      .sharebox button.primary {
+        background: #2563eb;
+        border-color: #2563eb;
+        color: #fff;
+      }
+      .sharebox button.danger {
+        color: #dc2626;
+        border-color: color-mix(in srgb, #dc2626 45%, transparent);
+      }
+      .sharebox .note {
+        font-size: 11px;
+        opacity: 0.65;
+        margin-top: 12px;
+        line-height: 1.4;
+      }
+      .sharewarn[hidden] {
+        display: none;
+      }
+      .sharewarn {
+        border: 1px solid color-mix(in srgb, #dc2626 55%, transparent);
+        background: color-mix(in srgb, #dc2626 12%, transparent);
+        border-radius: 10px;
+        padding: 14px;
+        margin-bottom: 4px;
+      }
+      .sharewarn .warnhead {
+        font-weight: 700;
+        color: #dc2626;
+        margin-bottom: 8px;
+        font-size: 14px;
+      }
+      .sharewarn p {
+        margin: 0 0 8px;
+        font-size: 12.5px;
+        line-height: 1.45;
+      }
+      .sharewarn button {
+        width: 100%;
+        padding: 10px;
+        margin-top: 4px;
+        border-radius: 8px;
+        border: 1px solid #dc2626;
+        background: #dc2626;
+        color: #fff;
+        font-size: 13px;
+        font-weight: 600;
+        cursor: pointer;
+      }
+      #shareRevealable[hidden] {
+        display: none;
+      }
       /* Terminal font-size stepper (a static row, not a hover/click target). */
       .rmenufont {
         justify-content: space-between;
@@ -1460,6 +1632,10 @@
     <script src="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/lib/xterm.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-web-links@0.11.0/lib/addon-web-links.min.js"></script>
+    <!-- QR generator (MIT, Kazuhiko Arase) — vendored locally so single-agent
+         share QR codes render offline under `ay serve --http`. Classic script:
+         defines the global `qrcode`. -->
+    <script src="./qrcode.js"></script>
     <script type="module">
       // codehost room transport — vendored from codehost's `bun run build:lib`.
       // Loaded as a module (deferred), so the classic script below awaits the
@@ -1524,6 +1700,12 @@
           <span class="dot" id="rdot"></span>
           <span class="name" id="rname"></span>
           <span class="badge" id="rpid"></span>
+          <span class="robadge" title="view-only share — you can watch but not steer this agent"
+            >👁 read-only</span
+          >
+          <span class="rwbadge" title="read-write share — you can type but not stop/restart this agent"
+            >✏️ read-write</span
+          >
           <span class="live"
             ><span class="dot" id="livedot"></span><span id="livetxt">connecting…</span></span
           >
@@ -1549,6 +1731,13 @@
                 ><input type="checkbox" id="perfToggle" /> <span>Perf HUD</span></label
               >
               <div class="rmenusep"></div>
+              <button class="rmenuitem rmenuact" id="shareAgent" type="button">
+                👁 Share (view-only)
+              </button>
+              <button class="rmenuitem rmenuact" id="shareAgentRW" type="button">
+                ✏️ Share (read-write)…
+              </button>
+              <div class="rmenusep"></div>
               <button class="rmenuitem rmenuact" id="stopAgent" type="button">⏹ Stop agent</button>
               <button class="rmenuitem rmenuact" id="restartAgent" type="button">
                 ↻ Restart (resume)
@@ -1646,6 +1835,52 @@
     <div class="launchoverlay" id="launch" style="display: none"></div>
     <div class="launchoverlay" id="newform" style="display: none"></div>
 
+    <!-- Single-agent view-only share: QR + link a viewer can open to watch (not
+         steer) just this agent. The link opens a read-only console; the host
+         enforces read-only regardless of the client. -->
+    <div class="modal-backdrop" id="shareModal" hidden>
+      <div class="sharebox" role="dialog" aria-modal="true" aria-label="Share agent">
+        <h3 id="shareTitle">Share this agent</h3>
+        <p class="sub" id="shareSub">view-only · anyone with the link can watch</p>
+
+        <!-- Read-write warning gate: the link is NOT shown until the operator
+             acknowledges that it hands over control. Shown only for rw shares. -->
+        <div class="sharewarn" id="shareWarn" hidden>
+          <div class="warnhead">⚠️ This link lets anyone control this agent</div>
+          <p>
+            Whoever opens this link can <strong>type into this agent</strong> — and because an
+            agent can run commands, that can mean <strong>control of your whole system</strong>.
+            The link isn't a password prompt: no further confirmation is asked.
+          </p>
+          <p><strong>Only share it with someone you completely trust.</strong></p>
+          <button class="danger" id="shareReveal" type="button">
+            I understand — reveal the link
+          </button>
+        </div>
+
+        <!-- Link + QR, hidden behind the warning for rw shares. -->
+        <div id="shareRevealable">
+          <div class="qr" id="shareQr"></div>
+          <div class="shareurl" id="shareUrl"></div>
+          <div class="srow">
+            <button class="primary" id="shareCopy" type="button">Copy link</button>
+            <button id="shareClose" type="button">Close</button>
+          </div>
+          <div class="srow">
+            <button class="danger" id="shareRevoke" type="button">Revoke</button>
+          </div>
+          <p class="note" id="shareNote">
+            View-only: viewers see this agent's terminal (which may include secrets) but cannot
+            type, stop, or restart it. The link expires automatically and stops working when
+            revoked.
+          </p>
+        </div>
+        <div class="srow" id="shareWarnClose" hidden>
+          <button id="shareCloseAlt" type="button">Cancel</button>
+        </div>
+      </div>
+    </div>
+
     <!-- Cmd/Ctrl+K omnibox: search agents by title (instant) then output (tail),
          or spawn a new agent in the highlighted agent's cwd with the typed prompt. -->
     <div class="omni" id="omni" style="display: none">
@@ -1702,21 +1937,10 @@
         docTitle,
         omniScore,
       } from "./console-logic.js";
-      import {
-        MARKER as E2E_MARKER,
-        ALLOW_LEGACY_PLAINTEXT,
-        FLAG_CONFIRM,
-        CONFIRM_TIMEOUT_MS,
-        deriveAuthToken,
-        deriveDirKeys,
-        computeTranscriptHash,
-        seal as e2eSeal,
-        open as e2eOpen,
-        packEnvelope,
-        unpackEnvelope,
-        parseSecret,
-        randomHex,
-      } from "./e2e.js";
+      // The ay-share (rtc) remote-room transport lives in a shared module so the
+      // /r/ rgui viewer reuses the exact same WebRTC + e2e wire (rtc.js imports
+      // e2e.js internally). The console only needs the client class.
+      import { RTCClient } from "./rtc.js";
 
       let entries = [];
       let sel = null; // selected agent's composite key (room#pid)
@@ -1806,8 +2030,17 @@
       });
 
       const $ = (id) => document.getElementById(id);
+      // Escape for HTML — including BOTH quote styles, because esc() is
+      // interpolated into double-quoted attribute values (title="${esc(...)}",
+      // data-key="${esc(...)}", …), not just element text. A remote host controls
+      // agent metadata (OSC terminal title, prompt, cwd) that lands in those
+      // attributes; without escaping " an agent titled `" onfocus=…` breaks out of
+      // the attribute and runs script at this origin (theft of saved room tokens).
       const esc = (s) =>
-        String(s ?? "").replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]);
+        String(s ?? "").replace(
+          /[&<>"']/g,
+          (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c],
+        );
 
       // ---- transport ---------------------------------------------------------
       // Local: same-origin fetch + EventSource (via the ay-serve proxy).
@@ -1815,278 +2048,11 @@
       // `ay serve --share` — established through the signaling server. Same call
       // sites, two wires. Remote is selected by a URL hash: #room:token[@sighost].
       const SIG_DEFAULT = "s.agent-yes.com"; // signaling host (override in the hash with @host)
-      const SUB = "ay-signal-1";
 
-      // Tunnels request/response + streaming over one DataChannel. Mirrors the
-      // envelope in lab/ui/share-host.ts: {t:"req"|"abort"} out, {t:"res"|"data"|"end"} in.
-      class RTCClient {
-        constructor(host, room, token) {
-          let resolveKeys;
-          const keysReady = new Promise((r) => (resolveKeys = r));
-          Object.assign(this, {
-            host,
-            room,
-            token,
-            dc: null,
-            calls: new Map(),
-            streams: new Map(),
-            onstate: () => {},
-            // e2e (v2) per-connection state
-            _s: null,
-            _v2: false,
-            _send: { sendCtr: 0n },
-            _recvState: { lastSeen: -1n },
-            _tHash: null,
-            _keyH2C: null, // host->client: client decrypts with this
-            _keyC2H: null, // client->host: client encrypts with this
-            _keysReady: keysReady,
-            _resolveKeys: resolveKeys,
-            _myNonce: randomHex(16),
-            _confirmedIn: false,
-            _confirmedOut: false,
-            _confirmed: false,
-            _confirmTimer: null,
-            _recvChain: Promise.resolve(), // serialize decrypts (ordered replay check)
-            _sendChain: Promise.resolve(), // serialize seals (wire order == counter order)
-          });
-        }
-        async connect() {
-          // Parse the secret marker (fail-closed on malformed) and split into the
-          // server-visible authToken vs the end-to-end keys the server never sees.
-          const { s, v2 } = parseSecret(this.token);
-          this._s = s;
-          this._v2 = v2;
-          if (!v2 && !ALLOW_LEGACY_PLAINTEXT)
-            throw new Error(
-              "this link uses the old unencrypted protocol — ask the host to upgrade",
-            );
-          const authToken = v2 ? await deriveAuthToken(s, this.room, this.host) : this.token;
-          return new Promise((resolve, reject) => {
-            const ws = new WebSocket(`wss://${this.host}/${this.room}`, [SUB]);
-            this.ws = ws; // kept so close() can drop the signaling registration too
-            let pc,
-              settled = false;
-            const fail = (e) => {
-              if (!settled) {
-                settled = true;
-                reject(e);
-              }
-            };
-            // Resolve ONLY after the mutual key-confirmation completes (see _dcRecv),
-            // never on bare dc.onopen — there must be no "connected but unverified" window.
-            const done = () => {
-              if (!settled) {
-                settled = true;
-                this.onstate("open");
-                resolve();
-              }
-            };
-            ws.onopen = () =>
-              ws.send(JSON.stringify({ type: "hello", role: "client", v: 2, token: authToken }));
-            ws.onmessage = async (ev) => {
-              const m = JSON.parse(ev.data);
-              if (m.type === "welcome") {
-                if (this._v2 && m.v !== 2)
-                  return fail(new Error("host is running an old agent-yes — ask it to upgrade"));
-                // pc is created on the offer below so it can use the host-supplied
-                // iceServers (incl. short-lived TURN creds for relaying behind NAT).
-              } else if (m.type === "offer") {
-                if (!pc) {
-                  pc = new RTCPeerConnection({
-                    iceServers:
-                      m.iceServers && m.iceServers.length
-                        ? m.iceServers
-                        : [{ urls: "stun:stun.l.google.com:19302" }],
-                  });
-                  this.pc = pc;
-                  pc.onicecandidate = (e) => {
-                    if (e.candidate)
-                      ws.send(JSON.stringify({ type: "candidate", candidate: e.candidate }));
-                  };
-                  pc.onconnectionstatechange = () => this.onstate(pc.connectionState);
-                  pc.ondatachannel = (e) => {
-                    this.dc = e.channel;
-                    this.dc.binaryType = "arraybuffer";
-                    this.dc.onopen = async () => {
-                      try {
-                        await this._keysReady;
-                        // Open the bidirectional confirmation handshake.
-                        this._dcSend(FLAG_CONFIRM, { t: "confirm", nonce: this._myNonce });
-                        this._confirmTimer = setTimeout(() => {
-                          if (!this._confirmed) fail(new Error("key confirmation timed out"));
-                        }, CONFIRM_TIMEOUT_MS);
-                      } catch (err) {
-                        fail(err);
-                      }
-                    };
-                    this.dc.onmessage = (ev2) => {
-                      this._recvChain = this._recvChain
-                        .then(() => this._dcRecv(ev2.data, done))
-                        .catch(() => {});
-                    };
-                    this.dc.onclose = () => this.onstate("closed");
-                  };
-                }
-                await pc.setRemoteDescription({ type: "offer", sdp: m.sdp });
-                await pc.setLocalDescription(await pc.createAnswer());
-                ws.send(JSON.stringify({ type: "answer", sdp: pc.localDescription.sdp }));
-                // Derive per-connection keys now both descriptions are stable, before
-                // the DataChannel opens. Client: remote=host offer, local=our answer.
-                try {
-                  this._tHash = await computeTranscriptHash(
-                    pc.remoteDescription.sdp,
-                    pc.localDescription.sdp,
-                  );
-                  const { keyH2C, keyC2H } = await deriveDirKeys(this._s, this._tHash);
-                  this._keyH2C = keyH2C;
-                  this._keyC2H = keyC2H;
-                  this._resolveKeys();
-                } catch (err) {
-                  fail(err);
-                }
-              } else if (m.type === "candidate") {
-                if (pc) await pc.addIceCandidate(m.candidate).catch(() => {});
-              }
-            };
-            ws.onerror = () => fail(new Error("signaling error"));
-            ws.onclose = () => fail(new Error("signaling closed"));
-            setTimeout(() => fail(new Error("connect timeout")), 8000);
-          });
-        }
-        // Seal an envelope and send it, serialized so wire order == counter order.
-        _dcSend(flags, obj) {
-          this._sendChain = this._sendChain.then(async () => {
-            if (!this.dc || this.dc.readyState !== "open" || !this._keyC2H || !this._tHash) return;
-            let frame;
-            try {
-              frame = await e2eSeal(
-                this._keyC2H,
-                this._send,
-                flags,
-                this._tHash,
-                packEnvelope(obj),
-              );
-            } catch {
-              this.close();
-              return;
-            }
-            try {
-              this.dc.send(frame);
-            } catch {}
-          });
-          return this._sendChain;
-        }
-        // Decrypt + route one frame. Fail-closed: any failure, replay, string
-        // frame, or pre-confirmation app frame closes the connection.
-        async _dcRecv(data, done) {
-          if (!this.dc) return;
-          if (typeof data === "string" || !this._keyH2C || !this._tHash) return this.close();
-          let env;
-          try {
-            const { plaintext } = await e2eOpen(this._keyH2C, data, this._tHash, this._recvState);
-            env = unpackEnvelope(plaintext);
-          } catch {
-            return this.close();
-          }
-          if (!this._confirmed) {
-            if (!env || env.t !== "confirm") return this.close();
-            if (typeof env.nonce === "string" && !this._confirmedOut) {
-              // Send (and flush) our echo BEFORE marking confirmed-out, so connect()
-              // can't resolve and let a req() race ahead of the echo on the wire.
-              await this._dcSend(FLAG_CONFIRM, {
-                t: "confirm",
-                nonce: this._myNonce,
-                echo: env.nonce,
-              });
-              this._confirmedOut = true;
-            }
-            if (env.echo && env.echo === this._myNonce) this._confirmedIn = true;
-            if (this._confirmedIn && this._confirmedOut) {
-              this._confirmed = true;
-              if (this._confirmTimer) clearTimeout(this._confirmTimer);
-              done(); // connect() resolves only now — the channel is mutually verified
-            }
-            return;
-          }
-          if (!env || env.t === "confirm") return; // stray confirm after handshake
-          this._recv(env);
-        }
-        _recv(r) {
-          // Frames are authenticated + replay-checked before they reach here, so an
-          // id we don't know is a late/cancelled response from the legitimate host,
-          // not an attack — drop it rather than tear down the channel.
-          const call = this.calls.get(r.id),
-            stream = this.streams.get(r.id);
-          if (r.t === "res") {
-            if (call) call.status = r.status;
-          } else if (r.t === "data") {
-            if (call) {
-              call.body += r.chunk;
-              call.dataCount = (call.dataCount || 0) + 1;
-            }
-            if (stream) stream(r.chunk);
-          } else if (r.t === "end") {
-            if (call) {
-              clearTimeout(call.timer);
-              this.calls.delete(r.id);
-              // end.seq is the count of data frames the host sent; a mismatch means
-              // the stream was truncated, so don't resolve it as complete.
-              if (typeof r.seq === "number" && r.seq !== (call.dataCount || 0))
-                call.reject(new Error("truncated response"));
-              else if (r.error) call.reject(new Error(r.error));
-              else call.resolve({ status: call.status, text: call.body });
-            }
-          }
-        }
-        req(method, path, body) {
-          const id = randomHex(16);
-          return new Promise((resolve, reject) => {
-            // Without a deadline a request over a silently-dead DataChannel (host
-            // gone, ICE not yet timed out) never settles, so the caller — and the
-            // poll loop — hangs forever and the room never reconnects. Reject on a
-            // timeout so listSource sees the failure and triggers backoff.
-            const timer = setTimeout(() => {
-              if (this.calls.delete(id)) reject(new Error("request timed out"));
-            }, 12000);
-            this.calls.set(id, { status: 0, body: "", dataCount: 0, resolve, reject, timer });
-            this._dcSend(0, { t: "req", id, method, path, body }).catch((e) => {
-              clearTimeout(timer);
-              this.calls.delete(id);
-              reject(e); // channel already torn down
-            });
-          });
-        }
-        subscribe(path, onRaw) {
-          const id = randomHex(16);
-          this.streams.set(id, onRaw);
-          this._dcSend(0, { t: "req", id, method: "GET", path });
-          return () => {
-            this.streams.delete(id);
-            this._dcSend(0, { t: "abort", id });
-          };
-        }
-        // Tear down BOTH wires. Closing only the pc leaves the signaling socket
-        // open and this client registered in the room, so each reconnect would
-        // leak another peer on the host. onstate is detached by the caller first.
-        close() {
-          if (this._confirmTimer) clearTimeout(this._confirmTimer);
-          try {
-            this.ws?.close();
-          } catch {}
-          try {
-            this.pc?.close();
-          } catch {}
-          this.dc = null;
-          // Settle anything still in flight now, rather than letting each req's
-          // 12s timeout fire long after the client is gone.
-          for (const c of this.calls.values()) {
-            clearTimeout(c.timer);
-            c.reject(new Error("connection closed"));
-          }
-          this.calls.clear();
-          this.streams.clear();
-        }
-      }
+      // The RTCClient (ay-share rtc wire) now lives in the shared ./rtc.js module
+      // — imported above and reused by the /r/ rgui viewer. SUB (subprotocol) and
+      // the client class moved there; SIG_DEFAULT stays here (used by saveRoom /
+      // addRoomSource / the header pill below).
 
       // ---- codehost rooms: a THIRD wire -----------------------------------
       // A codehost room can hold several machines: every `codehost serve`
@@ -2269,6 +2235,10 @@
           });
           return { ok: r.ok, text: await r.text() };
         },
+        async del(path) {
+          const r = await fetch(withTok(path), { method: "DELETE" });
+          return { ok: r.ok, text: await r.text() };
+        },
         subscribe(path, onText, onOpen, onError) {
           const ev = new EventSource(withTok(path));
           ev.onopen = () => onOpen && onOpen();
@@ -2289,6 +2259,10 @@
             const r = await rtc.req("POST", path, JSON.stringify(bodyObj));
             return { ok: r.status >= 200 && r.status < 300, text: r.text };
           },
+          async del(path) {
+            const r = await rtc.req("DELETE", path);
+            return { ok: r.status >= 200 && r.status < 300, text: r.text };
+          },
           subscribe(path, onText, onOpen, onError) {
             onOpen && onOpen();
             let buf = "";
@@ -2318,6 +2292,26 @@
       const sources = new Map(); // id -> { id, host, kind, tx, client, live, devices, serverCount }
       const srcFor = (e) => (e && sources.get(e._room)) || sources.get(LOCAL) || null;
       const txFor = (e) => srcFor(e)?.tx || localTx;
+      // True when the agent lives in a view-only share room (the host advertises
+      // this via /api/whoami → share.readonly and 403s every write regardless).
+      const isReadonlyEnt = (e) => !!srcFor(e)?.readonly;
+      // Wrap a source tx so every write (POST) is refused client-side on a
+      // read-only share — reads (fetchJSON/fetchText/subscribe) pass through. The
+      // host is the real boundary; this just stops the UI from firing doomed
+      // writes (send / resize / presence / kill / restart / share).
+      function readonlyTx(tx) {
+        if (!tx || tx._ro) return tx;
+        return {
+          ...tx,
+          _ro: true,
+          async post() {
+            return { ok: false, text: "read-only share" };
+          },
+          async del() {
+            return { ok: false, text: "read-only share" };
+          },
+        };
+      }
 
       // ---- connection-path classification (header [local/lan/wan/relay] pill) ----
       // Tells the user, at a glance, whether the terminal they're watching rides the
@@ -3083,6 +3077,159 @@
           alert(`Restart failed for ${who}:\n${(res && res.text) || "request failed"}`);
       }
 
+      // ---- Single-agent view-only share (QR + link) -----------------------
+      // Ask THIS agent's host to mint a fresh, scoped, read-only share room and
+      // show its link + QR. The host stands up an isolated e2ee room exposing
+      // only this agent (read-only) — see ts/agentShare.ts. Never reuses the
+      // fleet/master token, so the link can't reach other agents or steer.
+      let currentShare = null; // { shareId, link, perm } of the share shown in the modal
+      let pendingRw = null; // the agent awaiting a read-write warning acknowledgement
+      // perm: "r" (view-only) or "rw" (read-write / steer). A read-write link hands
+      // over keystroke control of the agent — effectively control of the host — so
+      // it is NOT even minted until the operator clicks through the warning.
+      async function shareAgent(perm, ent) {
+        const e = ent || (sel ? entries.find((x) => x._key === sel) : null);
+        if (!e) return;
+        // A shared viewer can't re-share; its tx 403s /api/share anyway.
+        if (isReadonlyEnt(e) || sharePermOf(e)) {
+          alert("This is a shared view — you can't re-share it from here.");
+          return;
+        }
+        if (perm === "rw") {
+          // Show the warning FIRST; mint only after "reveal" (revealRwShare).
+          pendingRw = e;
+          openShareModal(null, e, "rw");
+          return;
+        }
+        const info = await mintShare(e, "r");
+        if (info) openShareModal(info, e, "r");
+      }
+      async function mintShare(e, perm) {
+        const agentRef = e.agent_id || String(e.pid); // stable id; fall back to pid
+        const res = await txFor(e)
+          .post("/api/share", { agent: agentRef, perm })
+          .catch((err) => ({ ok: false, text: String(err?.message || err) }));
+        if (!res || !res.ok) {
+          alert(`Couldn't create share link:\n${(res && res.text) || "request failed"}`);
+          return null;
+        }
+        let info;
+        try {
+          info = JSON.parse(res.text);
+        } catch {
+          alert("Share created but the response was unreadable.");
+          return null;
+        }
+        currentShare = { shareId: info.shareId, link: info.link, srcRoom: e._room, perm };
+        return info;
+      }
+      // "I understand — reveal": now that the operator has read the warning, mint
+      // the read-write share and reveal its URL/QR.
+      async function revealRwShare() {
+        const e = pendingRw;
+        if (!e) return;
+        pendingRw = null;
+        const info = await mintShare(e, "rw");
+        if (!info) return closeShareModal();
+        $("shareUrl").textContent = info.link;
+        renderQr($("shareQr"), info.link);
+        $("shareWarn").hidden = true;
+        $("shareWarnClose").hidden = true;
+        $("shareRevealable").hidden = false;
+      }
+
+      function openShareModal(info, e, perm) {
+        const modal = $("shareModal");
+        if (!modal) return;
+        const who = e.title || cliLabel(e) || ident(e) || `pid ${e.pid}`;
+        const rw = perm === "rw";
+        $("shareTitle").textContent = rw ? "Share control of this agent" : "Share this agent";
+        $("shareSub").textContent = `${rw ? "read-write · can type" : "view-only · can watch"} · ${who}`;
+        $("shareNote").textContent = rw
+          ? "Read-write: viewers can type into this agent (interrupt, run commands). They cannot stop or restart it. The link expires and stops working when revoked."
+          : "View-only: viewers see this agent's terminal (which may include secrets) but cannot type, stop, or restart it. The link expires and stops working when revoked.";
+        // Read-write opens in the warning state with NO link/QR shown or rendered
+        // yet; view-only shows the link immediately (the milder note suffices).
+        $("shareWarn").hidden = !rw;
+        $("shareWarnClose").hidden = !rw;
+        $("shareRevealable").hidden = rw;
+        if (!rw && info) {
+          $("shareUrl").textContent = info.link;
+          renderQr($("shareQr"), info.link);
+        }
+        modal.hidden = false;
+      }
+      // The perm a shared SOURCE was granted (from whoami), or null when we're the
+      // owner. Used to hide re-share/admin controls a viewer isn't allowed.
+      function sharePermOf(e) {
+        return srcFor(e)?.sharePerm || null;
+      }
+      function closeShareModal() {
+        const modal = $("shareModal");
+        if (modal) modal.hidden = true;
+        pendingRw = null; // a cancelled read-write flow never minted anything
+      }
+      // Draw the QR onto a fresh canvas (white quiet-zone always, so it scans in
+      // dark mode too). `qrcode` is the vendored global from qrcode.js.
+      function renderQr(container, text) {
+        container.textContent = "";
+        try {
+          const qr = qrcode(0, "M"); // type 0 = smallest version that fits; EC level M
+          qr.addData(text);
+          qr.make();
+          const n = qr.getModuleCount();
+          const cell = 5,
+            margin = 4;
+          const px = (n + margin * 2) * cell;
+          const cv = document.createElement("canvas");
+          cv.width = cv.height = px;
+          const ctx = cv.getContext("2d");
+          ctx.fillStyle = "#fff";
+          ctx.fillRect(0, 0, px, px);
+          ctx.fillStyle = "#000";
+          for (let r = 0; r < n; r++)
+            for (let c = 0; c < n; c++)
+              if (qr.isDark(r, c))
+                ctx.fillRect((c + margin) * cell, (r + margin) * cell, cell, cell);
+          container.appendChild(cv);
+        } catch (err) {
+          container.textContent = "QR unavailable";
+        }
+      }
+      async function revokeCurrentShare() {
+        if (!currentShare) return closeShareModal();
+        // DELETE over whichever transport owns the agent's host (local or the
+        // room the agent lives in) — the same host that minted the share.
+        const e = entries.find((x) => x._room === currentShare.srcRoom) || null;
+        const tx = (e ? srcFor(e)?.tx : null) || localTx;
+        try {
+          await tx.del("/api/share/" + encodeURIComponent(currentShare.shareId));
+        } catch {}
+        currentShare = null;
+        closeShareModal();
+      }
+      (function shareModalBoot() {
+        $("shareClose")?.addEventListener("click", closeShareModal);
+        $("shareCloseAlt")?.addEventListener("click", closeShareModal);
+        $("shareReveal")?.addEventListener("click", revealRwShare);
+        $("shareRevoke")?.addEventListener("click", revokeCurrentShare);
+        $("shareCopy")?.addEventListener("click", async () => {
+          if (!currentShare) return;
+          try {
+            await navigator.clipboard.writeText(currentShare.link);
+            const b = $("shareCopy");
+            const t = b.textContent;
+            b.textContent = "Copied ✓";
+            setTimeout(() => (b.textContent = t), 1200);
+          } catch {
+            alert("Copy failed — select the link manually.");
+          }
+        });
+        $("shareModal")?.addEventListener("click", (ev) => {
+          if (ev.target === $("shareModal")) closeShareModal(); // backdrop click
+        });
+      })();
+
       // ---- Terminal right-click menu: copy + customizable quick commands ----
       // A right-click on the terminal used to copy the selection outright. Now it
       // opens a small menu: Copy, Paste, and user-defined quick commands. A quick
@@ -3477,6 +3624,8 @@
           });
         }
         if (cb) cb.addEventListener("change", () => setPerfHud(cb.checked));
+        $("shareAgent")?.addEventListener("click", () => (closePanel(), shareAgent("r")));
+        $("shareAgentRW")?.addEventListener("click", () => (closePanel(), shareAgent("rw")));
         $("stopAgent")?.addEventListener("click", () => (closePanel(), stopAgent(false)));
         $("restartAgent")?.addEventListener("click", () => (closePanel(), restartAgent()));
         $("killAgent")?.addEventListener("click", () => (closePanel(), stopAgent(true)));
@@ -3969,6 +4118,13 @@
         // Mobile: flip the single-column layout to the terminal ("detail") pane.
         // Done BEFORE term.open below so xterm measures a visible container.
         document.querySelector(".app").classList.add("show-detail");
+        // Shared-view gating (host-enforced; this is UX):
+        //  • view-only (r)  → readonly-agent: hide composer/keybar + ALL agent actions.
+        //  • read-write (rw) → steer-agent: keep composer/keybar (can type), but hide
+        //    the admin actions (stop/restart/kill/share) a viewer isn't granted.
+        const _perm = sharePermOf(e);
+        document.querySelector(".app").classList.toggle("readonly-agent", isReadonlyEnt(e));
+        document.querySelector(".app").classList.toggle("steer-agent", _perm === "rw");
         $("rhead").style.display = "flex";
         $("rdot").className = "dot " + e.status;
         const rname = e.title || cliLabel(e) || ident(e) || "agent";
@@ -4053,6 +4209,12 @@
         let suppressPush = true;
         const pushSize = () => {
           if (term && sel === e._key && !suppressPush) {
+            // Read-only viewer: we can't drive the agent's PTY, so a pane resize
+            // just re-letterboxes the agent's fixed grid to fit — never a SIGWINCH.
+            if (isReadonlyEnt(e)) {
+              applyCanvasScale();
+              return;
+            }
             lastDroveAt = Date.now(); // we're driving the size now (lease the grid)
             tx.post("/api/resize/" + encodeURIComponent(pid), {
               cols: term.cols,
@@ -4094,6 +4256,16 @@
         const fitAndSync = (sz) => {
           if (sel !== selKey || !term) return;
           if (sz && sz.cols && sz.rows) agentSize = sz; // remember for the badge tooltip
+          // Read-only viewer: don't reflow the agent to our pane (we can't resize
+          // it, and shouldn't). Adopt the AGENT's own grid and CSS-scale it to fit,
+          // exactly like a shared-canvas watcher — otherwise the raw stream (emitted
+          // at the agent's width) wraps at the wrong column in our terminal.
+          if (isReadonlyEnt(e)) {
+            if (sz && sz.cols && sz.rows) followAgentSize(sz);
+            else applyCanvasScale();
+            suppressPush = false;
+            return;
+          }
           try {
             fit.fit();
           } catch {}
@@ -4113,7 +4285,18 @@
         // inside fitAndSync keeps an already-matching agent from a redundant SIGWINCH.
         // Returns the in-flight sync promise so the initial open can await it
         // before starting the tail (below); tab-reactivation callers ignore it.
-        resyncTerm = () => {
+        resyncTerm = async () => {
+          if (sel !== selKey || !term) return;
+          // Settle the source's read-only state first (bounded) so fitAndSync picks
+          // the right sizing path on the FIRST render: a read-only viewer must
+          // adopt the agent's grid, not fit-to-pane — the raw snapshot can't be
+          // re-wrapped later. Bounded so an older host without whoami never wedges.
+          const src = srcFor(e);
+          if (src?.whoamiReady) {
+            try {
+              await Promise.race([src.whoamiReady, new Promise((r) => setTimeout(r, 1500))]);
+            } catch {}
+          }
           if (sel !== selKey || !term) return;
           return tx
             .fetchJSON("/api/size/" + encodeURIComponent(pid))
@@ -4867,15 +5050,36 @@
           // every machine's rows would be unlabelled. Ask the host who it is once
           // and tag this room's agents with it in listSource. Best-effort: an older
           // host with no /api/whoami just leaves rows device-less.
+          // Expose whoami as an awaitable so the terminal can settle the read-only
+          // state BEFORE it sizes/renders — otherwise a fast selection races the
+          // fetch and the initial raw snapshot lands on a fit-to-pane grid that a
+          // later resize can't un-wrap (a read-only viewer must render at the
+          // AGENT's grid). Re-created on every (re)connect.
+          let resolveWhoami;
+          s.whoamiReady = new Promise((r) => (resolveWhoami = r));
           try {
-            s.deviceLabel = (await s.tx.fetchJSON("/api/whoami"))?.host || "";
+            const who = await s.tx.fetchJSON("/api/whoami");
+            s.deviceLabel = who?.host || "";
+            // A single-agent view-only share advertises its capability here so the
+            // console enters read-only mode (hide + refuse writes). Wrap this
+            // source's tx so no write leaks through any call path; the host still
+            // enforces (403s writes) as the real boundary.
+            s.readonly = !!who?.share?.readonly;
+            s.sharePerm = who?.share?.perm || null; // "r" | "rw" | null(owner)
+            s.shareAgentId = who?.share?.agent_id || null;
+            if (s.readonly) s.tx = readonlyTx(s.tx);
             // whoami resolves after the first listSource may have already rendered
             // this room's rows device-less (and activity-gated polling might not
             // re-fire soon on a backgrounded tab). Re-render now so the host label
-            // lands immediately instead of lagging a poll.
-            if (s.deviceLabel) loadList();
+            // (and any read-only state) lands immediately instead of lagging a poll.
+            if (s.deviceLabel || s.readonly) loadList();
           } catch {
             s.deviceLabel = "";
+            // No whoami (older host / error): treat as writable, don't wedge the
+            // terminal — resolve so any awaiter proceeds immediately.
+            s.readonly = s.readonly || false;
+          } finally {
+            resolveWhoami();
           }
         } finally {
           s.reconnecting = false;