@songsid/agend 2.3.0-beta.1 → 2.3.0-beta.11

package/dist/web-api.js

@@ -1,4 +1,6 @@
 import { webHumanOrigin } from "./human-delivery-receipts.js";
+import { classifyWebPeer, confirmAfterBody, noAuthority } from "./authority/web-authority.js";
+import { guestChatRefusal, guestCommandText, guestDeliveries, guestFrameData, guestHistory, guestMessages, guestPollBody, guestPrefs, guestRequestOf, guestSeesMessage, guestStatus } from "./web-guest-access.js";
 import { withSpawnHoldReply } from "./spawn-hold-reply.js";
 import { binaryProbe } from "./binary-probe.js";
 import { settingsRequestExecution, settingsWrite, isSettingsReplay } from "./settings-request-capability.js";
@@ -41,6 +43,7 @@ import { parseMentionQuery } from "./web-mentions.js";
 import { authorizeExplicitInstanceRemoval } from "./instance-removal.js";
 import { measureSyncWork } from "./sync-work-attribution.js";
 import { resolveTz } from "./tz-utils.js";
+import { filesPlayInChat } from "./web-effect.js";
 // ── Strict public-facing schemas ────────────────────────────────────────────
 // web-api endpoints must reject unknown fields so the dashboard cannot inject
 // internal-only flags that would reach handleCreate/scheduler/config writers.
@@ -96,11 +99,41 @@ const safeInstanceSegment = (name) => /^[^\\/\x00]+$/.test(name) && name !== "."
  * the eviction the dead entry leaks forever, and without the try/catch a
  * single dead client breaks delivery to every client iterated after it.
  */
+/** #1920 phase 1b: the open streams that are a guest's, and whose — each event is projected for them (guestFrameData). */
+const streamGuests = new WeakMap();
+/**
+ * #1920 §5.2: one event for the guests' streams only, each as projected for it — a message that has just become what
+ * its channel saw (an admin's page already has it, unchanged).
+ */
+export function broadcastToGuests(clients, event, data, onError) {
+    const guests = [...clients].filter((c) => streamGuests.has(c));
+    if (!guests.length)
+        return;
+    const live = new Set(guests);
+    broadcastSseEvent(live, event, data, onError);
+    for (const c of guests)
+        if (!live.has(c))
+            clients.delete(c); // the ones it ended (their session went)
+}
 export function broadcastSseEvent(clients, event, data, onError, id) {
     const payload = sseFrame(event, data, id);
     const dead = [];
     for (const client of clients) {
         try {
+            // An admin's stream gets these bytes; a guest's, the event as projected for its scope now, or nothing (no id: it
+            // never replays chat, so a cursor of the admin's stream is not its to hold).
+            const guest = streamGuests.get(client);
+            if (guest) {
+                // The exact session that opened it ended (revoked, expired, rotated away): nothing more, and the stream goes.
+                if (!guest.current()) {
+                    dead.push(client);
+                    continue;
+                }
+                const shown = guestFrameData(event, data, guest.scope(), guest);
+                if (shown !== undefined)
+                    client.write(sseFrame(event, shown));
+                continue;
+            }
             client.write(payload);
         }
         catch (err) {
@@ -381,7 +414,7 @@ function handleEffectTrials(req, res, url, ctx, path, method) {
                 css = value;
         }
         catch { /* unavailable is never off */ }
-        // CSS remains a checked runtime value. The authority refuses anything except off on start/read.
+        // CSS is diagnostic for Try; its host-owned shadow shell isolates controls and local paint.
         const actor = Object.freeze({ via: "session", surface: "local", tier: "admin", sessionHash: v.session.idHash, epoch: v.session.handle, person, ownerCss: css });
         return { actor, record: v.session, sessions };
     };
@@ -483,7 +516,12 @@ function handleEffects(req, res, url, ctx, path, method) {
     const reading = method === "GET";
     // Reports are bounded untrusted diagnostics, not an appearance or admission write (r2 §6).
     const profilePost = method === "POST" && /^\/ui\/effects\/profile\/[0-9a-f]{32}$/.test(path);
-    if (gatewayRequestContext(req)) {
+    const gateway = gatewayRequestContext(req), guest = guestRequestOf(req);
+    const instanceQuery = url.searchParams.get("instance"), keys = [...url.searchParams.keys()];
+    const chatRead = reading && (path === "/ui/effects/placements" || /^\/ui\/effects\/resource\/[0-9a-f]{32}$/.test(path))
+        && keys.length === 2 && keys.includes("instance") && keys.includes("ownerEpoch") && !!instanceQuery && instanceQuery.length <= 128;
+    // Public viewing grants current Chat reads, never ordinary library/owner/Trial access or writes.
+    if (gateway && (!chatRead || !gateway.isCurrent())) {
         json(res, reading ? 404 : 403, { error: "effects_not_over_public_link" });
         return true;
     }
@@ -495,7 +533,9 @@ function handleEffects(req, res, url, ctx, path, method) {
             return { status: 403, error: "effects_need_a_signed_in_person" };
         if (!reading && !profilePost && verdict.session.tier !== "admin")
             return { status: 403, error: "effects_read_only" };
-        return { person: webPersonKey(verdict.session.owner), canWrite: verdict.session.tier === "admin", epoch: verdict.session.handle };
+        if (verdict.session.tier === "guest" && (!chatRead || !guest || !guest.current() || !guest.scope().has(instanceQuery)))
+            return { status: 404, error: "not_found" };
+        return { person: webPersonKey(verdict.session.owner), canWrite: verdict.session.tier === "admin", epoch: verdict.session.handle, guest: verdict.session.tier === "guest" };
     };
     const first = who();
     if ("status" in first) {
@@ -538,9 +578,9 @@ function handleEffects(req, res, url, ctx, path, method) {
         else if (path === "/ui/effects/owner" && instance === undefined && slot === null)
             answer(service.ownerSelections(first.person));
         else if (path === "/ui/effects/placements" && instance !== undefined)
-            answer(service.placements(first.person, instance));
+            answer(service.placements(first.person, instance, !!gateway || first.guest));
         else if (idPath?.[1] === "resource")
-            answer(slot === null ? service.resource(first.person, idPath[2], instance) : service.ownerResource(first.person, idPath[2], slot));
+            answer(slot === null ? service.resource(first.person, idPath[2], instance, !!gateway || first.guest) : service.ownerResource(first.person, idPath[2], slot));
         else if (idPath?.[1] === "profile" && instance === undefined)
             answer(service.profile(first.person, idPath[2]));
         else
@@ -594,8 +634,13 @@ function handleEffects(req, res, url, ctx, path, method) {
             answer(service.remove(now.person, body));
         else if (path === "/ui/effects/share")
             answer(service.share(now.person, body));
-        else
-            answer(service.report(now.person, idPath[2], body, instance));
+        else {
+            if (body && typeof body === "object" && body.kind === "playback" && (url.searchParams.getAll("instance").length !== 1 || slot !== null)) {
+                json(res, 400, { error: "playback_report" });
+                return;
+            }
+            answer(service.report(now.person, idPath[2], body, instance, now.epoch));
+        }
     })().catch(() => { try {
         json(res, 500, { error: "effect_request_failed" });
     }
@@ -804,7 +849,7 @@ export function exportMod(ctx, person, body) {
         return { ok: false, status: 400, error: "title", detail: "1..60 characters on one line" };
     const parts = {};
     let omitted = 0;
-    const wantsInstance = inc.theme === true || inc.identity === true || (isObj(inc.widgets) && AGENT_WIDGET_SLOTS.some(s => inc.widgets[s] === true));
+    const wantsInstance = inc.theme === true || inc.identity === true || inc.ambient === true || (isObj(inc.widgets) && AGENT_WIDGET_SLOTS.some(s => inc.widgets[s] === true));
     let name = null;
     if (wantsInstance) {
         if (typeof body.instance !== "string" || !ctx.isKnownInstance?.(body.instance) || !ctx.themeStore)
@@ -817,7 +862,8 @@ export function exportMod(ctx, person, body) {
         if (inc.theme === true) {
             // The effects the theme places travel with it, as the library keeps them (a person may export what is placed).
             // Only effects this person may carry away travel (Sol's ACL); the rest are counted, never packaged.
-            const effects = rec.placements.effects.flatMap(p => { const e = ctx.modPlacedEffect?.(person, p.id); if (!e) {
+            // #2017: an older placement of an effect that doesn't play in chat stays out (a mod can't place it): counted.
+            const effects = rec.placements.effects.flatMap(p => { const e = ctx.modPlacedEffect?.(person, p.id); if (!e || !filesPlayInChat(e.files)) {
                 omitted++;
                 return [];
             } return [{ name: e.name, files: e.files, params: p.params ?? {} }]; });
@@ -830,6 +876,11 @@ export function exportMod(ctx, person, body) {
             if (isObj(inc.widgets) && inc.widgets[slot] === true && w)
                 (parts.widgets ??= {})[slot] = { spec: w.spec, data: w.data };
         }
+        // #2117: its ambients, whoever set them (a person exports what is on the chat).
+        if (inc.ambient === true) {
+            const specs = Object.fromEntries(Object.entries(rec.placements.ambient).flatMap(([k, a]) => a ? [[k, a.spec]] : []));
+            parts.ambient = { specs, picture: id => { const a = rec.assets.find(x => x.id === id); const b = store.asset(name, id); return a && b ? { bytes: b.bytes, kind: a.kind } : null; } };
+        }
     }
     if (isObj(inc.widgets) && inc.widgets.sidebar === true && ctx.webPrefs) {
         const v = ctx.webPrefs.read(OPERATOR).values["widget.sidebar"];
@@ -869,6 +920,30 @@ function webPersonOf(req, url, ctx) {
     const who = webAccountOf(req, url, ctx);
     return who ? ctx.webPerson(who.owner) : null;
 }
+/**
+ * #1939 S1: whether this request carries `web-session` authority, asked as it stands now — on arrival without an instance,
+ * after the body with the one it names (then confirmAfterBody joins the two). Never touches the session.
+ */
+function webAuthorityOf(req, url, ctx, instance) {
+    if (!ctx.webAuthority)
+        return { authority: noAuthority(0), refusal: "not_session" };
+    const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
+    return ctx.webAuthority({ session: v.kind === "allow" && v.via === "session" ? v.session : null, gateway: !!gatewayRequestContext(req),
+        peer: classifyWebPeer(req), ...(instance !== undefined ? { instance } : {}) });
+}
+/**
+ * #2122: what let this request in, asked now — its session (by handle, under the token it was signed in with) or the
+ * header token; null when nothing does any more (the gate also refuses a public link that is no longer the current
+ * one). Equal before and after an await: the same admission still holds. Never touches the session.
+ */
+function admissionOf(req, url, ctx) {
+    const gateway = gatewayRequestContext(req);
+    const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
+    if (v.kind !== "allow")
+        return null;
+    const via = v.via === "session" ? `session:${v.session.handle}:${v.session.tokenEpoch}` : "token";
+    return gateway ? `${via}@${gateway.exposureId}` : via;
+}
 /** #1827: the person, or the request is answered 401 here (it is no longer authorized) and null is returned. */
 function webPersonOr401(req, res, url, ctx) {
     const p = webPersonOf(req, url, ctx);
@@ -944,7 +1019,20 @@ export function handleWebRequest(req, res, url, ctx) {
         return true;
     }
     // ── Backend detection ─────────────────────────────────
+    // #2072: the model a Settings field offers — the cached catalog of that backend (that instance's account's). Read only.
+    if (method === "GET" && path === "/ui/models") {
+        const backend = url.searchParams.get("backend") ?? "";
+        const instance = url.searchParams.get("instance");
+        if (!/^[a-z][a-z0-9-]{0,31}$/.test(backend) || (instance !== null && (instance.length < 1 || instance.length > 256))) {
+            json(res, 400, { error: "backend (and optional instance) required" });
+            return true;
+        }
+        json(res, 200, { backend, models: ctx.modelCatalogFor?.(backend, instance) ?? [] });
+        return true;
+    }
     if (method === "GET" && path === "/ui/backends") {
+        // #2072 (#2098 review P3-3): the backend an agent created with "fleet default" runs, so its model list can be shown.
+        const defaultBackend = ctx.fleetConfig?.defaults?.backend ?? "claude-code";
         const BACKENDS = [
             { name: "claude-code", binary: "claude" },
             { name: "codex", binary: "codex" },
@@ -954,6 +1042,16 @@ export function handleWebRequest(req, res, url, ctx) {
             { name: "grok", binary: "grok" },
             { name: "muse", binary: "muse" },
         ];
+        // #2072: the published availability snapshot — installed, signed in, new enough — when the fleet has one.
+        if (ctx.backendAvailabilityRows) {
+            const binaryOf = new Map(BACKENDS.map(b => [b.name, b]));
+            const backends = ctx.backendAvailabilityRows().filter(r => binaryOf.has(r.backend)).map(r => ({
+                name: r.backend, binary: binaryOf.get(r.backend).binary, installed: r.state !== "not_installed" && r.path !== null, path: r.path ?? "",
+                deprecated: binaryOf.get(r.backend).deprecated ?? false, state: r.state, minVersion: r.minVersion, ...(r.state === "unknown" ? { unknown: true } : {}),
+            }));
+            json(res, 200, { backends, defaultBackend });
+            return true;
+        }
         // #1490: seven sequential 2 s `execFileSync("which")` calls used to block the event loop here. The shared probe
         // runs `which` as bounded async children and reuses an answer for BINARY_PROBE_TTL_MS. `unknown`: no answer in
         // time (shown as not installed, as the old timeout was).
@@ -963,7 +1061,7 @@ export function handleWebRequest(req, res, url, ctx) {
             return { name: b.name, binary: b.binary, installed: path !== null, path: path ?? "", deprecated: b.deprecated ?? false,
                 ...(found.known ? {} : { unknown: true }) };
         })).then((backends) => { if (!res.headersSent)
-            json(res, 200, { backends }); }, () => { if (!res.headersSent)
+            json(res, 200, { backends, defaultBackend }); }, () => { if (!res.headersSent)
             json(res, 500, { error: "backend probe failed" }); });
         return true;
     }
@@ -976,9 +1074,24 @@ export function handleWebRequest(req, res, url, ctx) {
     // that arrived while the stream was silent is not skipped by the cursor this answer hands out (#1251
     // review). The page keeps one entry per boot+id, so what it already loaded from /ui/history is not doubled.
     if (method === "GET" && path === "/ui/poll") {
+        // #1920: a guest's poll is projected for its scope (web-guest-access.ts) — the same rule as its stream.
+        const guest = guestRequestOf(req);
         const history = ctx.webChatHistory;
         const after = url.searchParams.get("after");
         const fresh = after === null || after === ""; // a cursor that is not ours in shape still gets nothing
+        if (guest) {
+            // #2085 review: and what became the channel's after its cursor (an older row, its copy sent since), once each.
+            json(res, 200, guestPollBody(ctx.getUiStatus(), guest.scope(), Date.now(), guest, after, () => {
+                if (!history)
+                    return [];
+                if (fresh)
+                    return history.after(0);
+                const cursor = parseLastEventId(after);
+                const rows = [...history.replayFor(cursor), ...history.seenAfter(cursor)];
+                return rows.filter((m, i) => rows.findIndex((x) => x.boot === m.boot && x.id === m.id) === i);
+            }));
+            return true;
+        }
         json(res, 200, {
             status: ctx.getUiStatus(),
             messages: history ? (fresh ? history.after(0) : history.replayFor(parseLastEventId(after))) : [],
@@ -1011,30 +1124,49 @@ export function handleWebRequest(req, res, url, ctx) {
         });
         // #1823 (#1830 review): with the status, the server's clock — now and with every heartbeat — that the page counts a
         // poll down by (one write: the frames a connect sends are unchanged in number).
-        res.write(`event: status\ndata: ${JSON.stringify(ctx.getUiStatus())}\n\n${sseClock()}`);
+        // #1920: a guest's stream: its projected status now and with each heartbeat, its replay and ticks as it may see them
+        // (§5.2), then only what guestFrameData lets through — no prompts or Needs you.
+        const guest = guestRequestOf(req);
+        if (guest) {
+            streamGuests.set(res, guest);
+            guest.streamOpened?.();
+        }
+        const statusFrame = () => `event: status\ndata: ${JSON.stringify(guest ? guestStatus(ctx.getUiStatus(), guest.scope()) : ctx.getUiStatus())}\n\n`;
+        res.write(`${statusFrame()}${sseClock()}`);
         // An EventSource that reconnects says what it last saw: send what it missed, before anything new.
         const lastSeen = parseLastEventId(req.headers["last-event-id"]);
         if (lastSeen !== null && ctx.webChatHistory) {
             const history = ctx.webChatHistory;
-            for (const m of history.replayFor(lastSeen))
-                res.write(sseFrame("message", m, history.cursorOf(m)));
+            if (guest) {
+                // Its own projection, with no cursor: an admin's ids are not a guest's to hold (it reloads its history instead).
+                for (const m of guestMessages(history.replayFor(lastSeen), guest, guest.scope()))
+                    res.write(sseFrame("message", m));
+            }
+            else {
+                for (const m of history.replayFor(lastSeen))
+                    res.write(sseFrame("message", m, history.cursorOf(m)));
+            }
         }
         // Ticks change messages already sent and carry no cursor: every (re)connect gets where each one is now, so a
         // report that fell into a gap is not lost until a reload (#1253 review). No id: it is not a message.
-        if (ctx.webChatHistory)
-            res.write(`event: deliveries\ndata: ${JSON.stringify(ctx.webChatHistory.deliveries())}\n\n`);
+        if (ctx.webChatHistory) {
+            const ticks = guest ? guestDeliveries(ctx.webChatHistory, guest, guest.scope()) : ctx.webChatHistory.deliveries();
+            res.write(`event: deliveries\ndata: ${JSON.stringify(ticks)}\n\n`);
+        }
         // The same for the fleet prompts (C4): one posted, answered or expired during a gap is caught up here.
-        if (ctx.listWebPrompts)
+        if (!guest && ctx.listWebPrompts)
             res.write(`event: prompts\ndata: ${JSON.stringify(ctx.listWebPrompts())}\n\n`);
         // #1386: and "Needs you" as it is now; changes follow as `needs` events.
-        if (ctx.needsYouItems)
+        if (!guest && ctx.needsYouItems)
             res.write(`event: needs\ndata: ${JSON.stringify({ items: ctx.needsYouItems() })}\n\n`);
         ctx.sseClients.add(res);
         const interval = setInterval(() => {
             // A stream authorized once must not outlive the authorization. Re-checked
             // without counting as activity, or an open tab would keep an idle session
             // alive forever; a revoked, expired or rotated-away session ends here.
-            if (!isWebRequestAuthorized(req, url, ctx.webToken, ctx.webSessions, { touch: false })) {
+            // #2049 review: a guest's stream also needs the exact session that opened it — another cookie on the same request
+            // still authenticating does not keep a revoked device's stream (with its scope) alive.
+            if (!isWebRequestAuthorized(req, url, ctx.webToken, ctx.webSessions, { touch: false }) || (guest && !guest.current())) {
                 // Close the connection too, not just the response: an ended response leaves the socket idle in
                 // keep-alive, still held open by whoever's session just ended.
                 const socket = req.socket;
@@ -1047,7 +1179,7 @@ export function handleWebRequest(req, res, url, ctx) {
             }
             try {
                 // Every open dashboard tab, every 10 s: the status of every instance, serialized on the fleet's loop (#1235).
-                res.write(measureSyncWork("web.sseStatus", () => `event: status\ndata: ${JSON.stringify(ctx.getUiStatus())}\n\n`) + sseClock());
+                res.write(measureSyncWork("web.sseStatus", statusFrame) + sseClock());
             }
             catch {
                 cleanup();
@@ -1081,7 +1213,10 @@ export function handleWebRequest(req, res, url, ctx) {
             json(res, 400, { error: "instance (1-128 chars) and limit (1-500) required" });
             return true;
         }
-        json(res, 200, { messages: ctx.webChatHistory?.list(instance, limit) ?? [], boot: ctx.webChatHistory?.boot ?? null, lastId: ctx.webChatHistory?.lastId ?? 0 });
+        // #1920 §5.2: a guest gets what the channel showed of it, and its own messages (the gate checked the scope).
+        const guest = guestRequestOf(req);
+        const messages = !ctx.webChatHistory ? [] : guest ? guestHistory(ctx.webChatHistory, instance, limit, guest, guest.scope()) : ctx.webChatHistory.list(instance, limit);
+        json(res, 200, { messages, boot: ctx.webChatHistory?.boot ?? null, lastId: ctx.webChatHistory?.lastId ?? 0 });
         return true;
     }
     // ── #1218: the Log tab ─────────────────────────────────
@@ -1136,6 +1271,16 @@ export function handleWebRequest(req, res, url, ctx) {
     const fileMatch = path.match(/^\/ui\/file\/([^/]+)$/);
     if (method === "GET" && fileMatch) {
         const id = fileMatch[1];
+        // #1920: a guest gets a file only when its stored instance is in scope — "no such file" otherwise, like an unknown id
+        // (an id from another instance's chat is useless).
+        const guest = guestRequestOf(req);
+        if (guest) {
+            const served = isFileId(id) ? ctx.webFiles?.servedFile?.(id) ?? null : null;
+            if (!served || !guest.scope().has(served.instance)) {
+                json(res, 404, { error: "No such file" });
+                return true;
+            }
+        }
         // #1589: audio and video, played in the page — one byte range at a time (206), by id only, never a whole video in
         // memory. Every other type is answered exactly as before.
         const media = isFileId(id) ? ctx.webFiles?.mediaOf?.(id) ?? null : null;
@@ -1167,9 +1312,10 @@ export function handleWebRequest(req, res, url, ctx) {
         return true;
     }
     // ── #1629: agents' themes — read by every page (the public link included: it views them), changed by a person ──
-    // GET /ui/themes: { rev, themes, locked, widgets } when the status frame's themes_rev moves (passive, web-auth.ts).
+    // GET /ui/themes: { rev, themes, locked, widgets, ambient (#2117) } when the status frame's themes_rev moves (passive, web-auth.ts).
     // GET /ui/img/theme/<instance>/<id>: a theme's picture (same headers as #1630's images; the id is the content hash).
-    // POST /ui/themes/<instance>/reset | lock | widget (r4-4: { slot } — take an agent's widget out): a person's, from an admin session — never the CLI token, never the public
+    // POST /ui/themes/<instance>/reset | lock | widget (r4-4: { slot } — take an agent's widget out) | ambient (#2117: { spec } sets one,
+    // { which? } alone clears that kind or both): a person's, from an admin session — never the CLI token, never the public
     // link (absent from its manifest, and refused here too).
     if (method === "GET" && path === "/ui/themes") {
         const store = ctx.themeStore;
@@ -1177,7 +1323,7 @@ export function handleWebRequest(req, res, url, ctx) {
             json(res, 404, { error: "Themes are not kept on this fleet" });
             return true;
         }
-        json(res, 200, { rev: store.rev(), themes: store.themes(), locked: store.lockedNames(), widgets: store.widgets() });
+        json(res, 200, { rev: store.rev(), themes: store.themes(), locked: store.lockedNames(), widgets: store.widgets(), ambient: store.ambients() });
         return true;
     }
     const themeImage = path.match(/^\/ui\/img\/theme\/([^/]+)\/([0-9a-f]{32})$/);
@@ -1203,7 +1349,7 @@ export function handleWebRequest(req, res, url, ctx) {
         res.end(image.bytes);
         return true;
     }
-    const themeWrite = path.match(/^\/ui\/themes\/([^/]+)\/(reset|lock|widget)$/);
+    const themeWrite = path.match(/^\/ui\/themes\/([^/]+)\/(reset|lock|widget|ambient)$/);
     if (method === "POST" && themeWrite) {
         const service = ctx.webAppearance;
         if (!service) {
@@ -1255,7 +1401,8 @@ export function handleWebRequest(req, res, url, ctx) {
             }
             const r = themeWrite[2] === "reset" ? service.humanReset(name)
                 : themeWrite[2] === "widget" ? service.humanRemoveWidget(name, body.slot)
-                    : typeof body.locked === "boolean" ? service.humanLock(name, body.locked) : { error: "locked: true or false", status: 400 };
+                    : themeWrite[2] === "ambient" ? service.humanSetAmbient(name, body.spec ?? null, body.which)
+                        : typeof body.locked === "boolean" ? service.humanLock(name, body.locked) : { error: "locked: true or false", status: 400 };
             if (typeof r.error === "string") {
                 json(res, typeof r.status === "number" ? r.status : 503, { error: r.error });
                 return;
@@ -1439,6 +1586,7 @@ export function handleWebRequest(req, res, url, ctx) {
             return true;
         }
         const click = ctx.clickWebReplyButton.bind(ctx);
+        const arrival = webAuthorityOf(req, url, ctx); // #1939 §3: on arrival, and again after the body
         (async () => {
             let body;
             try {
@@ -1455,13 +1603,29 @@ export function handleWebRequest(req, res, url, ctx) {
                 json(res, 400, { error: "instance, id and index required" });
                 return;
             }
+            // #1920 step 2b: a guest clicks only on a reply it may see (§5.2), of an in-scope instance, while guests may chat.
+            const guest = guestRequestOf(req);
+            const refused = guestChatRefusal(guest, instance);
+            if (refused) {
+                json(res, refused.status, { error: refused.error });
+                return;
+            }
+            if (guest) {
+                const row = guest.history?.()?.findByButtons(instance, id);
+                if (!row || !guestSeesMessage(row, guest, guest.scope())) {
+                    json(res, 404, { error: "not found" });
+                    return;
+                }
+            }
             // #1823/#1827: the click is this page's person's — on a poll their vote (one per person, on every device of
             // theirs), on one-click buttons their choice — under their web id and name. A request that no longer passes the
             // gate (a session revoked meanwhile) clicks nothing as anyone.
             const person = webPersonOr401(req, res, url, ctx);
             if (!person)
                 return;
-            const r = await click(instance, id, index, { key: person.voterKey, userId: person.userId, name: person.name });
+            // #1920 review: a guest's choice reaches the agent marked as a guest's, as its typed messages do.
+            const { authority } = confirmAfterBody(arrival, webAuthorityOf(req, url, ctx, instance));
+            const r = await click(instance, id, index, { key: person.voterKey, userId: person.userId, name: person.name, ...(guest ? { guest: true } : {}), authority });
             json(res, r.status, r.status === 200 ? { answered: true, ...(r.options ? { options: r.options } : {}) } : { error: r.error ?? "Refused", ...(r.status === 409 ? { gone: true } : {}) });
         })().catch(err => {
             ctx.logger.error({ err: err.message }, "Web reply-button click failed");
@@ -1639,12 +1803,57 @@ export function handleWebRequest(req, res, url, ctx) {
     // #1269: an instance's chat command (/ctx, /compact, /clear, /model, …) — a session write (CSRF, checked by the
     // gate), run through the platforms' own handlers and command table. The public link is told it is one (/save is
     // refused there).
+    // ── #1939 S2b: this browser's authorization — what the app shows (GET), and "Authorize this browser" (POST: posts the
+    // Confirm card in the account's DM). Judged on this request (§3), never touching the session.
+    if (path === "/ui/authorization" && (method === "GET" || method === "POST")) {
+        const judge = () => {
+            const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
+            return { session: v.kind === "allow" && v.via === "session" ? v.session : null, gateway: !!gatewayRequestContext(req), peer: classifyWebPeer(req) };
+        };
+        res.setHeader("Cache-Control", "no-store");
+        if (method === "GET") {
+            if (!ctx.webSessionAuthorization) {
+                json(res, 404, { error: "not available" });
+                return true;
+            }
+            json(res, 200, ctx.webSessionAuthorization(judge()));
+            return true;
+        }
+        if (!ctx.requestSessionAuthorization) {
+            json(res, 404, { error: "not available" });
+            return true;
+        }
+        const ask = ctx.requestSessionAuthorization.bind(ctx);
+        (async () => {
+            try {
+                await parseBody(req);
+            }
+            catch {
+                json(res, 400, { error: "Invalid JSON" });
+                return;
+            }
+            if (!permitWebContinuation(req, res, ctx))
+                return;
+            const r = await ask(judge()); // asked again now the body is in
+            // A refusal is an answer the page shows (pending, three this hour, why not), not a failed request: 200 with
+            // ok: false — a 4xx would be logged as an error in the browser's console every time.
+            json(res, 200, r);
+        })().catch(err => {
+            ctx.logger.error({ err: err.message }, "Web authorization request failed");
+            try {
+                json(res, 500, { error: "Request failed" });
+            }
+            catch { /* already answered */ }
+        });
+        return true;
+    }
     if (method === "POST" && path === "/ui/command") {
         if (!ctx.webCommand) {
             json(res, 404, { error: "Not available" });
             return true;
         }
         const run = ctx.webCommand.bind(ctx);
+        const arrival = webAuthorityOf(req, url, ctx); // #1939 §3: on arrival, and again after the body
         (async () => {
             let body;
             try {
@@ -1673,7 +1882,8 @@ export function handleWebRequest(req, res, url, ctx) {
             const person = webPersonOr401(req, res, url, ctx); // #1827: asked again, now the body is in
             if (!person)
                 return;
-            const r = await run({ instance, command, args: str(body.args, MAX_COMMAND_ARGS), confirm: body.confirm }, { publicLink: !!gatewayRequestContext(req), person });
+            const { authority } = confirmAfterBody(arrival, webAuthorityOf(req, url, ctx, instance));
+            const r = await run({ instance, command, args: str(body.args, MAX_COMMAND_ARGS), confirm: body.confirm }, { publicLink: !!gatewayRequestContext(req), person, authority });
             json(res, r.status, r.body);
         })().catch(err => {
             ctx.logger.error({ err: err.message }, "Web command failed");
@@ -1703,6 +1913,12 @@ export function handleWebRequest(req, res, url, ctx) {
             json(res, 404, { error: `Instance not found: ${name}` });
             return true;
         }
+        // #1920 step 2b: a guest's Cancel is the platform button's (anyone allowed there), while guests may chat.
+        const cancelRefused = guestChatRefusal(guestRequestOf(req), name);
+        if (cancelRefused) {
+            json(res, cancelRefused.status, { error: cancelRefused.error });
+            return true;
+        }
         if (!ctx.cancelInstance(name)) {
             json(res, 409, { error: `${name} is not running` });
             return true;
@@ -2112,6 +2328,47 @@ export function handleWebRequest(req, res, url, ctx) {
         }
         return true;
     }
+    // #2122: the usage report. Signed-in sessions by default (guests never: not in GUEST_ROUTES); hidden with the rest of
+    // usage by web.usage_panel: false; over the public link only when web.usage_report_on_public_link is true. Answered
+    // from the ledgers and rollups as they are; a catch-up runs behind. The page's CSV is built from this same answer.
+    if (method === "GET" && path === "/ui/usage-report") {
+        // Who may have it, asked on arrival and again before it is sent (the report is awaited: a switch turned off, a
+        // session signed out or a public link ended meanwhile gets nothing). The same boundary both times, no new gate.
+        const refusal = () => {
+            if (!ctx.usageReport || ctx.fleetConfig?.web?.usage_panel === false)
+                return [404, "Not available"];
+            if (gatewayRequestContext(req) && ctx.fleetConfig?.web?.usage_report_on_public_link !== true)
+                return [403, "usage_report_not_over_public_link"];
+            return null;
+        };
+        // Over the public link, where to turn it on: Settings → Web on the dashboard reached directly (this computer's own
+        // address — the public link's Settings only reads). Never the public origin's own Settings, which cannot change it.
+        const answer = ([status, error]) => json(res, status, {
+            error, ...(status === 403 ? { settings: `http://localhost:${ctx.fleetConfig?.health_port ?? 19280}/settings/web` } : {})
+        });
+        const first = refusal();
+        if (first) {
+            answer(first);
+            return true;
+        }
+        const admitted = admissionOf(req, url, ctx);
+        if (!admitted) {
+            json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
+            return true;
+        }
+        void import("./usage-report.js").then(({ usageRange, usageGroup }) => ctx.usageReport({
+            range: usageRange(url.searchParams.get("range"), url.searchParams.get("from") ?? undefined, url.searchParams.get("to") ?? undefined),
+            group: usageGroup(url.searchParams.get("group")),
+        })).then((report) => {
+            const now = refusal();
+            if (now)
+                return answer(now);
+            if (admissionOf(req, url, ctx) !== admitted)
+                return json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
+            json(res, 200, report);
+        }, (err) => { ctx.logger.error({ err }, "usage report failed"); json(res, 500, { error: "Usage report failed" }); });
+        return true;
+    }
     // #1468: the prompt-cache expiry analysis. Opening it is a person's navigation, like any Fleet tab (it counts as
     // use); the page never re-reads it on a timer. Answered from the ledgers as they are; a catch-up runs behind.
     if (method === "GET" && path === "/ui/cache") {
@@ -2129,6 +2386,12 @@ export function handleWebRequest(req, res, url, ctx) {
         json(res, 200, ctx.orgChart?.() ?? { general: [], teams: [], instances: {} });
         return true;
     }
+    // #1918: the org canvas's traffic on opening, and the public link's (which has no stream) on its poll cadence. The
+    // fleet works it out at most once every two seconds and caps it, whoever asks how often.
+    if (method === "GET" && path === "/ui/traffic") {
+        json(res, 200, ctx.trafficSnapshot?.() ?? { now: new Date().toISOString(), items: [], delegations: [] });
+        return true;
+    }
     if (method === "GET" && path === "/ui/teams") {
         const teams = ctx.fleetConfig?.teams ?? {};
         json(res, 200, { teams });
@@ -2317,6 +2580,7 @@ function webEchoPreview(message, names) {
 }
 /** Handle POST /ui/send — extracted for readability. */
 function handleSendMessage(req, res, ctx) {
+    const arrival = webAuthorityOf(req, new URL(req.url ?? "/", "http://localhost"), ctx); // #1939 §3: again after the body
     let body = "";
     let size = 0;
     req.on("data", (chunk) => {
@@ -2340,6 +2604,17 @@ function handleSendMessage(req, res, ctx) {
                 return;
             }
             const { instance, message: typed, attachments = [] } = parsed.data;
+            // #1920 step 2b: a guest writes only to an in-scope instance, while guests may chat, and never a command.
+            const guest = guestRequestOf(req);
+            const refused = guestChatRefusal(guest, instance);
+            if (refused) {
+                json(res, refused.status, { error: refused.error });
+                return;
+            }
+            if (guest && guestCommandText(typed)) {
+                json(res, 403, { error: "guest_no_commands" });
+                return;
+            }
             const ipc = ctx.instanceIpcClients.get(instance);
             if (!ipc) {
                 json(res, 404, { error: `Instance not found: ${instance}` });
@@ -2373,6 +2648,8 @@ function handleSendMessage(req, res, ctx) {
                 json(res, 401, { error: WEB_TOKEN_INVALID_MESSAGE });
                 return;
             }
+            // #1939 S1: what the receipt records about who authorized it (observe only: agents still read web as recognition).
+            const { authority } = confirmAfterBody(arrival, webAuthorityOf(req, new URL(req.url ?? "/", "http://localhost"), ctx, instance));
             const ts = new Date().toISOString();
             // The id the agent is given, and the one its delivery reports come back under: the page's ticks.
             const messageId = newWebMessageId();
@@ -2387,11 +2664,13 @@ function handleSendMessage(req, res, ctx) {
                 && !ctx.isClassicInstance?.(instance) && syncAdapter && groupId && topicId != null;
             // Add no runtime credentials or local attachment paths to the display copy.
             const preview = webEchoPreview(message, files.map(f => f.name));
-            // ClassicBot echo (#1320 part B): same ordering lane, per-entry
-            // opt-in resolved at send time inside sendClassicWebEcho.
+            // ClassicBot echo (#1320 part B): same ordering lane, each room's setting (#2054: on unless it says false, or
+            // the fleet-wide switch is off for a room that is unset) resolved at send time inside sendClassicWebEcho.
             const canClassicEcho = ctx.isClassicInstance?.(instance) === true && !!ctx.sendClassicWebEcho;
             const settleClassicEcho = canClassicEcho ? ctx.reserveWebChannelEcho?.(instance, async () => {
-                await ctx.sendClassicWebEcho(instance, formatWebChannelEcho(person.name, preview, t("web.echo_full_text")), person.name);
+                const posted = await ctx.sendClassicWebEcho(instance, formatWebChannelEcho(person.name, preview, t("web.echo_full_text"), { guest: !!guest }), person.name);
+                if (posted > 0)
+                    ctx.webMessageInChannel?.(instance, messageId); // #1920 §5.2: the room saw it
             }) : undefined;
             const settleEcho = canEcho ? ctx.reserveWebChannelEcho?.(instance, async () => {
                 // A replacement adapter or edited binding is not the route we reserved.
@@ -2399,12 +2678,14 @@ function handleSendMessage(req, res, ctx) {
                     || (ctx.getGroupIdForInstance?.(instance) ?? String(ctx.fleetConfig?.channel?.group_id ?? "")) !== groupId
                     || ctx.fleetConfig?.instances[instance]?.topic_id !== topicId)
                     return;
-                return syncAdapter.sendText(String(groupId), formatWebChannelEcho(person.name, preview, t("web.echo_full_text")), { threadId: String(topicId), format: "text", allowedMentions: { parse: [] } });
+                const sent = await syncAdapter.sendText(String(groupId), formatWebChannelEcho(person.name, preview, t("web.echo_full_text"), { guest: !!guest }), { threadId: String(topicId), format: "text", allowedMentions: { parse: [] } });
+                ctx.webMessageInChannel?.(instance, messageId); // #1920 §5.2: the topic saw it
+                return sent;
             }) : undefined;
             let delivered;
             try {
                 const deliver = (name, payload) => ctx.deliverHumanToInstance
-                    ? ctx.deliverHumanToInstance(name, payload, webHumanOrigin(), typed)
+                    ? ctx.deliverHumanToInstance(name, payload, webHumanOrigin(false, authority), typed)
                     : ctx.deliverToInstance(name, payload);
                 delivered = await deliver(instance, {
                     type: "fleet_inbound",
@@ -2417,6 +2698,7 @@ function handleSendMessage(req, res, ctx) {
                         ts,
                         thread_id: topicId != null ? String(topicId) : "",
                         source: "web",
+                        ...(guest ? { web_guest: "1" } : {}), // #1920: "[user:… via web (guest), id:…]" (authority none)
                         adapter_id: syncAdapter?.id,
                         ...delivery.meta,
                     },
@@ -2453,7 +2735,8 @@ function handleSendMessage(req, res, ctx) {
             ctx.webFiles?.commit(files);
             ctx.lastInboundUser.set(instance, person.name);
             ctx.eventLog?.logActivity("message", person.name, (message || `[${files.length} file(s)]`).slice(0, 200), instance);
-            ctx.emitSseEvent("message", { instance, sender: person.name, role: "user", text: message, ts, attachments: files.map(publicAttachment), messageId });
+            // #1920: the account that wrote it (a guest sees its own); channel-visible once its copy was sent (above).
+            ctx.emitSseEvent("message", { instance, sender: person.name, role: "user", text: message, ts, attachments: files.map(publicAttachment), messageId, ...(person.bound ? { from: person.voterKey } : {}) });
             json(res, 200, { sent: true, messageId });
         }
         catch {
@@ -2477,6 +2760,13 @@ function handleUpload(req, res, url, ctx) {
         json(res, 404, { error: "uploads are not available" });
         return;
     }
+    // #1920 step 2b: a guest's upload is for an in-scope instance's message, while guests may chat.
+    const guestRefused = guestChatRefusal(guestRequestOf(req), instance);
+    if (guestRefused) {
+        req.resume();
+        json(res, guestRefused.status, { error: guestRefused.error });
+        return;
+    }
     if (!instance || instance.length > 128 || !safeInstanceSegment(instance) || !ctx.instanceIpcClients.has(instance)) {
         json(res, 404, { error: `Instance not found: ${instance}` });
         return;
@@ -2671,14 +2961,22 @@ function prefsViewer(req, url, ctx) {
     const v = evaluateWebRequest(req, url, ctx.webToken ?? null, ctx.webSessions, { touch: false });
     if (v.kind !== "allow")
         return null;
+    // #1920: a guest is a guest on every listener. The public link's page and reads too — before, a guest signed in through
+    // it (#2094) read the host's preferences unfiltered: the sidebar's order and favourites, naming instances out of its
+    // scope. Its account (phase 3) names it on its page.
+    const guest = v.via === "session" && v.session?.tier === "guest" ? { guest: true, ...(v.session.owner ? { owner: v.session.owner } : {}) } : {};
     if (!gatewayRequestContext(req) && v.via === "session" && v.session) {
         const person = webPersonKey(v.session.owner);
-        return { person, epoch: v.session.handle, scope: person === OPERATOR ? "operator" : "person", canWrite: v.session.tier === "admin", via: "session" };
+        return { person, epoch: v.session.handle, scope: person === OPERATOR ? "operator" : "person", canWrite: v.session.tier === "admin", via: "session", ...guest };
     }
-    return { person: null, epoch: null, scope: "none", canWrite: v.via !== "session" || v.session?.tier === "admin", via: v.via };
+    return { person: null, epoch: null, scope: "none", canWrite: v.via !== "session" || v.session?.tier === "admin", via: v.via, ...guest };
 }
 const prefsScope = (v) => ({ ownerScope: v?.scope ?? "none", ownerEpoch: v?.epoch ?? null });
-const prefsView = (prefs, v) => ({ ...prefs.readForViewer(v?.person ?? null), ...prefsScope(v) });
+// #1920: a guest reads the host's look and its own, never a preference that names an instance (guestPrefs).
+const prefsView = (prefs, v) => {
+    const view = { ...prefs.readForViewer(v?.person ?? null), ...prefsScope(v) };
+    return v?.guest ? guestPrefs(view) : view;
+};
 function shellHtmlTag(ctx, mode, viewer) {
     if (mode !== "full" || !ctx.webPrefs)
         return '<html lang="en">';
@@ -2692,26 +2990,40 @@ function shellHtmlTag(ctx, mode, viewer) {
  * the public link, the anonymous View reader, the CLI's header token or the sign-in and setup pages (other panels).
  */
 function shellOwnerCss(ctx, mode, viewer) {
-    return mode === "full" && viewer?.person !== null && viewer?.person !== undefined && ctx.ownerCss ? ctx.ownerCss.active(viewer.person) : null;
+    return mode === "full" && !viewer?.guest && viewer?.person !== null && viewer?.person !== undefined && ctx.ownerCss ? ctx.ownerCss.active(viewer.person) : null;
+}
+function guestBodyAttrs(ctx, owner, attr) {
+    const badge = ctx.guestBadge?.(owner);
+    return ` data-tier="guest"${badge ? ` data-guest-name="${attr(badge.name)}" data-guest-platform="${attr(badge.platform)}"` : ""}`;
+}
+/** A separate session fence for Chat playback: public/guest viewers acquire no owner-pref identity. */
+function shellEffect(req, ctx, mode) {
+    if (mode !== "full" || typeof ctx.effectBoot !== "string" || !/^[0-9a-f]{32}$/.test(ctx.effectBoot))
+        return null;
+    const v = evaluateWebRequest(req, new URL(req.url ?? "/", "http://localhost"), ctx.webToken ?? null, ctx.webSessions, { touch: false });
+    if (v.kind !== "allow" || v.via !== "session" || !v.session || !/^[a-f0-9]{16}$/.test(v.session.handle))
+        return null;
+    return { boot: ctx.effectBoot, epoch: v.session.handle, scope: gatewayRequestContext(req) || v.session.tier === "guest" ? "chat" : "owner" };
 }
 function shellBodyTag(req, ctx, mode, viewer) {
     const p = shellPreview(req, ctx, mode);
-    const ownerCss = shellOwnerCss(ctx, mode, viewer);
-    let ownerCssState = "unknown";
-    if (mode === "full" && viewer?.person != null && ctx.ownerCss) {
+    const ownerCss = shellOwnerCss(ctx, mode, viewer), effect = shellEffect(req, ctx, mode);
+    let ownerCssState = mode === "full" && (gatewayRequestContext(req) || viewer?.guest) ? "off" : "unknown";
+    if (mode === "full" && !viewer?.guest && viewer?.person != null && ctx.ownerCss) {
         ownerCssState = ctx.ownerCss.effectState(viewer.person);
         if (ownerCssState === "off" && ownerCss !== null || ownerCssState === "on" && ownerCss === null)
             ownerCssState = "unknown";
     }
     const attr = (v) => String(v ?? "").replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);
     return `<body data-mode="${mode}"${mode === "full" && gatewayRequestContext(req) ? ' data-web-transport="poll"' : ""} data-dashboard-origin="${attr(p?.dashboardOrigin)}" data-preview-origin="${attr(p?.previewOrigin)}"`
+        + `${effect ? ` data-effect-boot="${effect.boot}" data-effect-epoch="${effect.epoch}" data-effect-scope="${effect.scope}"` : ""}`
         + ` data-preview-boot="${attr(p?.previewOrigin ? p.boot : "")}" data-preview-reason="${attr(p ? p.reason : "Previews are not available on this fleet.")}"`
         // #1554: no availability asked (the public link, or not the full app) still says why, in the page's language.
         + ` data-preview-reason-code="${attr(p ? p.code ?? "" : gatewayRequestContext(req) ? "publicLink" : "notOffered")}"`
         // #1723: why the public link's preview tunnel failed (a fixed reason the page words), when it did.
         + `${p?.detail ? ` data-preview-detail="${attr(p.detail)}"` : ""}`
-        // #1523 N3: whether the fleet serves /api/ai-usage (web.usage_panel), for every page's ◔.
-        + ` data-usage-panel="${ctx.fleetConfig?.web?.usage_panel === false ? "0" : "1"}"`
+        // #1523 N3: whether the fleet serves /api/ai-usage (web.usage_panel), for every page's ◔ — never to a guest (#1920).
+        + ` data-usage-panel="${ctx.fleetConfig?.web?.usage_panel === false || viewer?.guest ? "0" : "1"}"`
         // #1218: whether the Log tab is on (web.log_tab; off by default): the tab says so and offers to turn it on.
         + ` data-log-tab="${ctx.fleetConfig?.web?.log_tab === true ? "1" : "0"}"`
         // #1937: the upload limits in force for this page (the config's; the public link's own cap on it) — what the chat
@@ -2722,7 +3034,9 @@ function shellBodyTag(req, ctx, mode, viewer) {
         // #1629 r4 §3: the person's owner CSS in force (a sha), linked by the page unless this device or this load says not.
         + ` data-owner-css-state="${ownerCssState}"${ownerCss ? ` data-owner-css="${attr(ownerCss)}"` : ""}`
         // #1589: the public link shows attachments as downloads only (no inline text or media): its scope is unchanged.
-        + `${gatewayRequestContext(req) ? ' data-public-link="1"' : ""}>`;
+        + `${gatewayRequestContext(req) ? ' data-public-link="1"' : ""}`
+        // #1920 phase 3: a guest's page — the shell shows only what a guest may use, and who it is signed in as.
+        + `${mode === "full" && viewer?.guest && viewer.owner ? guestBodyAttrs(ctx, viewer.owner, attr) : ""}>`;
 }
 /** The app shell page for one entry, under the panels' CSP; it may frame exactly <preview origin>/frame, and only
  *  when this load chose one. */
@@ -2738,8 +3052,11 @@ export function serveAppShell(req, res, ctx, mode) {
         const mediaSrc = own ? `${own}/ui/file/` : "'none'";
         // A public-link page frames what its exposure's preview names (the quick-tunnel wildcard: its host is not known when
         // the page may load); every other page frames exactly the origin this load chose (#1723).
-        const frameSrc = p && "frameSrc" in p ? p.frameSrc : p?.previewOrigin
-            ? `${p.previewOrigin}/frame${mode === "full" && !gatewayRequestContext(req) ? ` ${p.previewOrigin}/effect` : ""}` : null;
+        const previewFrames = p && "frameSrc" in p ? p.frameSrc : p?.previewOrigin ? `${p.previewOrigin}/frame` : null;
+        // This fixed trusted document is independent of HTML preview. Its own response confines all Worker execution.
+        const effectOrigin = gatewayRequestContext(req)?.expectedOrigin ?? dashboardOriginFor(typeof req.headers.host === "string" ? req.headers.host : undefined, isSecureRequest(req));
+        const effectFrame = shellEffect(req, ctx, mode) && effectOrigin ? `${effectOrigin}/effect-bootstrap` : null;
+        const frameSrc = [previewFrames, effectFrame].filter(Boolean).join(" ");
         sendPanelHtml(res, html.replace('<html lang="en">', shellHtmlTag(ctx, mode, viewer)).replace("<body>", shellBodyTag(req, ctx, mode, viewer)), 200, {}, { ...(frameSrc ? { frameSrc } : {}), mediaSrc });
     }
     catch {