crewforth 3.2.0-rc.2 → 3.2.0-rc.3

package/kit/studio/server/lib/lan.js

@@ -0,0 +1,87 @@
+// lan.js — the listener on this machine's Wi-Fi address, for viewers on the same network.
+//
+// It exists only while a viewer does: index.js calls sync() with the number of live viewers, and with none it is
+// closed and every connection on it is ended, so nothing beyond 127.0.0.1 is listening. Every request it takes is
+// marked `crewLan`, and the request gate (index.js) answers such a request only for a viewer's token — the panel's
+// own token is not accepted from the network.
+//
+// Which address: the private IPv4 addresses of this machine's interfaces (10/8, 172.16/12, 192.168/16): the ranges a
+// home or office Wi-Fi hands out. A public, link-local or carrier-grade address is not listened on. There is no
+// tunnel here and no way to reach the panel from outside the network.
+import http from 'node:http';
+import os from 'node:os';
+
+const PRIVATE = (a) => /^10\./.test(a) || /^192\.168\./.test(a) || /^172\.(1[6-9]|2\d|3[01])\./.test(a);
+
+/** This machine's private IPv4 addresses. CREW_STUDIO_LAN_ADDR names one instead (the self-check uses loopback). */
+export function lanAddresses(env = process.env, ifaces = os.networkInterfaces()) {
+  if (env.CREW_STUDIO_LAN_ADDR) return [env.CREW_STUDIO_LAN_ADDR];
+  const out = [];
+  for (const list of Object.values(ifaces ?? {})) {
+    for (const i of list ?? []) {
+      const v4 = i.family === 'IPv4' || i.family === 4;
+      if (v4 && !i.internal && PRIVATE(i.address) && !out.includes(i.address)) out.push(i.address);
+    }
+  }
+  return out;
+}
+
+/**
+ * The listener, opened and closed by the number of live viewers.
+ * @param handler  the server's own request handler; a request is marked `req.crewLan = true` before it is called
+ * @param port     the panel's port (CREW_STUDIO_LAN_PORT overrides it, for the self-check)
+ */
+export function lanListener({ handler, port, env = process.env, addresses = null }) {
+  let servers = [];
+  let errors = [];
+  let pending = null;
+  const lanPort = env.CREW_STUDIO_LAN_PORT !== undefined ? Number(env.CREW_STUDIO_LAN_PORT) : port;
+  // The port actually listened on: the asked one, or the one the system picked for 0 (the self-check).
+  const portOf = (e) => e.server.address()?.port ?? lanPort;
+
+  const open = () => {
+    const addrs = addresses ?? lanAddresses(env);
+    errors = [];
+    servers = addrs.map((addr) => {
+      const sockets = new Set();
+      const s = http.createServer((req, res) => { req.crewLan = true; handler(req, res); });
+      s.on('connection', (c) => { sockets.add(c); c.on('close', () => sockets.delete(c)); });
+      const entry = { addr, server: s, sockets, listening: false };
+      s.on('error', (e) => { errors.push(`${addr}: ${e.code ?? e.message}`); entry.listening = false; });
+      s.listen(lanPort, addr, () => { entry.listening = true; });
+      return entry;
+    });
+    return new Promise((resolve) => { let n = servers.length; if (!n) resolve(); for (const e of servers) { e.server.once('listening', () => --n || resolve()); e.server.once('error', () => --n || resolve()); } });
+  };
+
+  const close = () => {
+    const was = servers; servers = [];
+    return Promise.all(was.map((e) => new Promise((resolve) => {
+      for (const c of e.sockets) c.destroy();
+      if (!e.listening) return resolve();
+      e.server.close(() => resolve());
+    })));
+  };
+
+  return {
+    /** Open with at least one live viewer, close with none. Resolves once the change has happened. */
+    sync(liveViewers) {
+      pending = (pending ?? Promise.resolve()).then(() => {
+        if (liveViewers > 0 && !servers.length) return open();
+        if (liveViewers === 0 && servers.length) return close();
+        return undefined;
+      });
+      return pending;
+    },
+    state() {
+      const on = servers.filter((e) => e.listening);
+      return { listening: on.length > 0, port: on.length ? portOf(on[0]) : lanPort,
+        addresses: servers.filter((e) => e.listening).map((e) => e.addr), errors: [...errors] };
+    },
+    /** The link a viewer opens on the phone, one per address listened on. */
+    urls(token) {
+      return servers.filter((e) => e.listening).map((e) => `http://${e.addr}:${portOf(e)}/?token=${encodeURIComponent(token)}`);
+    },
+    close,
+  };
+}

package/kit/studio/server/lib/redact.js

@@ -0,0 +1,60 @@
+// redact.js — what a viewer whose link hides transcripts is sent.
+//
+// Text that came from a transcript (a prompt, a reply, a tool's input or output, the short task an agent was given,
+// a session's title) is not sent to such a viewer at all. Hiding it in the page would not do: it would still be on
+// the wire and in the phone's memory.
+//
+// AN ALLOW-LIST, NOT A DENY-LIST. Transcript text only ever travels as a string, so every string in an answer is
+// dropped unless its key is one of the few below, which name things that do not come from a transcript: ids,
+// states, model and agent-type names, tool names, times as text. A field added to an answer tomorrow is therefore
+// hidden until someone decides it is safe and adds its key here. Numbers, booleans and the shape of an answer pass,
+// so the viewer still sees the agents, their states, their timing and what they cost.
+//
+// A few routes are nothing but transcript (a conversation, an agent's detail, the live conversation of a session
+// the panel runs): those are refused outright rather than sent empty.
+
+/** Keys whose string values are not transcript text. Checked by key name, wherever in the answer they are. */
+export const SAFE_STRING_KEYS = new Set([
+  // identity and links between things
+  'id', 'sessionId', 'agentId', 'parentId', 'toolUseId', 'workflowId', 'workflow', 'source', 'target', 'origin',
+  // kinds and states
+  'kind', 'status', 'launchStatus', 'trigger', 'role', 'reason',
+  // which model and which kind of agent, and which tool (a tool's NAME, never its input)
+  'model', 'modelAsked', 'models', 'unpriced', 'agentType', 'toolName', 'lastTool', 'version',
+  // where, as the machine knows it rather than as anybody wrote it
+  'cwd', 'gitBranch', 'dir', 'url', 'read', 'at',
+]);
+
+// `label` is safe only where the server writes it from one of the safe things above (a session's short id, an agent
+// type, 'workflow'); measured in lib/graph.js. Anywhere else it is dropped like any other string.
+const LABEL_SAFE_KINDS = new Set(['session', 'agent', 'workflow']);
+
+/** Routes that are nothing but transcript: refused for a viewer whose link hides transcripts. */
+export function transcriptOnly(pathname) {
+  return /^\/api\/session\/[^/]+\/(conversation|agent\/[^/]+)$/.test(pathname)
+    || pathname === '/api/owned' || pathname === '/api/owned-events' || /^\/api\/owned\/[^/]+(\/.*)?$/.test(pathname);
+}
+
+/** The answer with every string that may be transcript text removed. A new object; the input is not touched. */
+export function redact(value, key = null, parent = null) {
+  if (typeof value === 'string') {
+    if (SAFE_STRING_KEYS.has(key)) return value;
+    if (key === 'label' && parent && LABEL_SAFE_KINDS.has(parent.kind)) return value;
+    // A machine's name (an origin: no sessionId of its own). A session's `name` is its title, written from its
+    // first prompt, and is dropped.
+    if (key === 'name' && parent && parent.sessionId === undefined && typeof parent.local === 'boolean') return value;
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value.map((x) => redact(x, key, parent)).filter((x) => x !== undefined);
+  }
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      const r = redact(v, k, value);
+      if (r !== undefined) out[k] = r;
+    }
+    return out;
+  }
+  return value;
+}

package/kit/studio/server/lib/remote.js

@@ -1,60 +1,129 @@
 // remote.js — read-only viewers.
 //
-// The panel's own token can start a session and answer a tool call. Handing that token to a phone, over
-// whatever tunnel reaches this machine, hands the phone all of it. A viewer token is the smaller thing: it
-// reads what the panel reads and can change nothing. The server decides that, not the page — a viewer's
-// request is refused here before any handler sees it.
+// The panel's own token can start a session and answer a tool call. Handing that token to a phone hands the phone
+// all of it. A viewer token is the smaller thing: it reads what the panel reads and can change nothing. The server
+// decides that, not the page — a viewer's request is refused here before any handler sees it.
 //
-// THE SERVER STILL LISTENS ON LOOPBACK ONLY. A viewer does not widen that. The way in from another device is a
-// tunnel the user runs (an ssh forward, a tailnet), and this module knows nothing about it.
+// THE WAY IN FROM ANOTHER DEVICE IS THE SAME WI-FI. While at least one viewer is live, the server also listens on
+// this machine's Wi-Fi address (index.js), and there it answers a viewer's token and nothing else: the panel's own
+// token is not accepted from the network at all. With no viewer, nothing listens beyond 127.0.0.1.
 //
-// Kept in memory, like the owner's token: a viewer lasts as long as the server that made it. A link that
-// survived a restart would be a credential nobody remembers handing out.
+// A viewer lasts EIGHT HOURS, or until it is revoked, or until the server stops — whichever comes first. Kept in
+// memory, like the owner's token: a link that survived a restart would be a credential nobody remembers handing out.
+// An expired token is remembered as expired (not as unknown) so the phone can say "Session expired" rather than
+// "no access", and only for as long as the server runs.
+//
+// TRANSCRIPTS ARE HIDDEN by default: a viewer made without `transcripts` is answered with no text that came from a
+// transcript (lib/redact.js does that on the server; the page hiding it would not be enough).
 import { randomUUID } from 'node:crypto';
 
 export const MAX_VIEWERS = 8;
+export const VIEWER_TTL_MS = 8 * 60 * 60 * 1000;
 const LABEL_MAX = 40;
+const LOG_MAX = 200;
 
 const viewers = new Map();          // id -> viewer
 const byToken = new Map();          // token -> viewer
+const expired = new Map();          // token -> label, for "Session expired"
+const log = [];                     // what happened to viewers' links, newest last
+
+let clock = () => Date.now();
+let onChange = () => {};
+let note = () => {};
+
+/** For the self-check: a clock it can move (eight hours are not waited for). */
+export function _setClock(fn) { clock = fn ?? (() => Date.now()); }
+/** index.js opens and closes the Wi-Fi listener when the number of live viewers changes. */
+export function onViewersChange(fn) { onChange = fn ?? (() => {}); }
+/** Where a log line also goes (the server's own output). */
+export function onLog(fn) { note = fn ?? (() => {}); }
+
+function record(entry) {
+  const e = { at: clock(), ...entry };
+  log.push(e);
+  if (log.length > LOG_MAX) log.splice(0, log.length - LOG_MAX);
+  note(e);
+}
 
 const publicOf = (v) => ({
   id: v.id,
   label: v.label,
   createdAt: v.createdAt,
+  expiresAt: v.expiresAt,
+  transcripts: v.transcripts,
   lastSeenAt: v.lastSeenAt,
   requests: v.requests,
   agent: v.agent,
   open: v.conns.size,
+  addresses: [...v.addresses],
 });
 
 /** Make a viewer. The token is in this answer and in no later one. */
-export function addViewer(label) {
+export function addViewer(label, { transcripts = false } = {}) {
+  sweep();
   if (viewers.size >= MAX_VIEWERS) {
     return { ok: false, reason: `${MAX_VIEWERS} viewers already; revoke one first` };
   }
   const named = typeof label === 'string' ? label.replace(/\s+/g, ' ').trim().slice(0, LABEL_MAX) : '';
+  const now = clock();
   const v = {
     id: randomUUID().slice(0, 8),
     label: named || `Viewer ${viewers.size + 1}`,
     token: randomUUID(),
-    createdAt: Date.now(),
+    createdAt: now,
+    expiresAt: now + VIEWER_TTL_MS,
+    transcripts: transcripts === true,
     lastSeenAt: null,
     requests: 0,
     agent: null,
     conns: new Set(),
+    addresses: new Set(),
   };
   viewers.set(v.id, v);
   byToken.set(v.token, v);
+  record({ event: 'added', viewer: v.label, transcripts: v.transcripts });
+  onChange(viewers.size);
   return { ok: true, viewer: { ...publicOf(v), token: v.token } };
 }
 
 export function listViewers() {
+  sweep();
   return [...viewers.values()].map(publicOf);
 }
 
+export function liveCount() {
+  sweep();
+  return viewers.size;
+}
+
+export function remoteLog(n = 50) {
+  return log.slice(-n);
+}
+
+/** The viewer this token belongs to, if it is live; `{ expired: label }` if it was one and its eight hours are up. */
 export function viewerByToken(token) {
-  return (typeof token === 'string' && byToken.get(token)) || null;
+  if (typeof token !== 'string') return null;
+  const v = byToken.get(token);
+  if (v && clock() >= v.expiresAt) { end(v, 'expired'); return { expired: v.label }; }
+  if (v) return v;
+  if (expired.has(token)) return { expired: expired.get(token) };
+  return null;
+}
+
+function end(v, why) {
+  viewers.delete(v.id);
+  byToken.delete(v.token);
+  if (why === 'expired') expired.set(v.token, v.label);
+  for (const res of v.conns) { try { res.destroy(); } catch { /* already gone */ } }
+  v.conns.clear();
+  record({ event: why, viewer: v.label });
+  onChange(viewers.size);
+}
+
+/** End every viewer whose eight hours are up. Called on every read of the list and by index.js's timer. */
+export function sweep() {
+  const now = clock();
+  for (const v of [...viewers.values()]) if (now >= v.expiresAt) end(v, 'expired');
 }
 
 /**
@@ -64,23 +133,38 @@ export function viewerByToken(token) {
 export function revokeViewer(id) {
   const v = viewers.get(id);
   if (!v) return { ok: true, revoked: false };
-  viewers.delete(id);
-  byToken.delete(v.token);
-  for (const res of v.conns) { try { res.destroy(); } catch { /* already gone */ } }
-  v.conns.clear();
+  end(v, 'revoked');
   return { ok: true, revoked: true };
 }
 
-/** Count a viewer's request and remember its response for as long as it is open. */
+/** Count a viewer's request and remember its response for as long as it is open. A new address is logged once. */
 export function noteRequest(v, req, res) {
   v.requests += 1;
-  v.lastSeenAt = Date.now();
+  v.lastSeenAt = clock();
   const ua = req.headers['user-agent'];
   v.agent = typeof ua === 'string' ? ua.slice(0, 160) : null;
+  const ip = req.socket?.remoteAddress ?? null;
+  if (ip && !v.addresses.has(ip)) {
+    v.addresses.add(ip);
+    record({ event: 'connected', viewer: v.label, ip, over: req.crewLan ? 'wifi' : 'loopback', result: 'ok' });
+  }
   v.conns.add(res);
   res.on('close', () => v.conns.delete(res));
 }
 
+/**
+ * A request that was turned away: logged with who it claimed to be, from where, and why. The same refusal again
+ * (same viewer, address, path and answer) is counted on its entry rather than written again, so a page that keeps
+ * asking cannot push everything else out of the log.
+ */
+export function noteRefusal(req, { viewer = null, status, reason }) {
+  const e = { event: 'refused', viewer, ip: req.socket?.remoteAddress ?? null, over: req.crewLan ? 'wifi' : 'loopback',
+    result: `${status} ${reason}`, path: String(req.url ?? '').split('?')[0].slice(0, 120) };
+  const same = log.findLast((x) => x.event === 'refused' && x.viewer === e.viewer && x.ip === e.ip && x.path === e.path && x.result === e.result);
+  if (same) { same.count = (same.count ?? 1) + 1; same.lastAt = clock(); return; }
+  record(e);
+}
+
 /**
  * What a viewer may ask for: a GET of anything the panel reads, and nothing about viewers themselves.
  * The list of viewers is the owner's; a viewer that could read it could count who else is watching.
@@ -95,5 +179,7 @@ export function viewerMay(method, pathname) {
 
 /** For the self-check: start from nothing. */
 export function _reset() {
-  for (const id of [...viewers.keys()]) revokeViewer(id);
+  for (const v of [...viewers.values()]) end(v, 'revoked');
+  expired.clear();
+  log.length = 0;
 }

package/kit/studio/server/lib/session.js

@@ -290,7 +290,7 @@ class OwnedSession {
  * answer is "yes": an unreadable fleet must not be the reason two processes
  * end up writing one transcript.
  */
-async function isHeldOpen(id) {
+export async function isHeldOpen(id) {
   try {
     const fleet = await getFleet();
     const rows = fleet?.sessions ?? fleet ?? [];

package/kit/studio/server/lib/terminal.js

@@ -17,21 +17,60 @@ function q(s) {
   return `'${String(s).replace(/'/g, `'\\''`)}'`;
 }
 
+/** PowerShell literal string: a quote is doubled, nothing else is special inside one. */
+function psq(s) {
+  return `'${String(s).replace(/'/g, "''")}'`;
+}
+
+/**
+ * A session id is a UUID. It comes from the URL, and on Windows it ends up in a line cmd.exe interprets, where a
+ * quote is not a quote (cmd hands `'` to the program as part of the id) and `&` starts a second command. So
+ * nothing is built for anything else, and an id that passes needs no quoting in any shell.
+ */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isSessionId(s) {
+  return typeof s === 'string' && SESSION_ID.test(s);
+}
+
 /** AppleScript string literal: backslashes and quotes, nothing else. */
 function osaQuote(s) {
   return `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
 
+/**
+ * The command that opens the session in the Claude Desktop app again (`claude --desktop`, CLI 2.1.299), from its
+ * own directory: `--resume <id>` looks for the session among that directory's. On Windows it is a PowerShell line
+ * (5.1 and 7; Windows Terminal opens PowerShell): cmd needs `&&` and does not take single quotes, PowerShell 5.1
+ * rejects `&&`, and no one line works in both. `shell` says which, so the panel can say so.
+ */
+export function desktopLine({ cwd, sessionId, platform = process.platform }) {
+  if (!isSessionId(sessionId)) return null;
+  if (platform === 'win32') {
+    return { shell: 'PowerShell', line: `Set-Location -LiteralPath ${psq(cwd)}; claude --desktop --resume ${sessionId}` };
+  }
+  return { shell: 'sh', line: `cd ${q(cwd)} && claude --desktop --resume ${q(sessionId)}` };
+}
+
 /**
  * Build the launch for this platform.
  * Returns null when nothing here knows how to open a terminal, so the caller
  * can say so rather than fail silently.
  */
-export function plan({ cwd, sessionId, command }) {
-  const inner = command ?? `claude --resume ${q(sessionId)}`;
+export function plan({ cwd, sessionId, platform = process.platform }) {
+  if (!isSessionId(sessionId)) return null;
+
+  if (platform === 'win32') {
+    // Windows Terminal when present, the console host otherwise. wt sets the directory itself; what runs inside is
+    // cmd.exe, so the line shown is a cmd line: double quotes, `cd /d` for another drive, and the id bare (a UUID).
+    const inner = `claude --resume ${sessionId}`;
+    const wt = ['wt.exe', '-d', cwd, 'cmd.exe', '/k', inner];
+    return { platform: 'win32', via: 'wt.exe', shell: 'cmd', line: `cd /d "${cwd}" && ${inner}`, argv: wt };
+  }
+
+  const inner = `claude --resume ${q(sessionId)}`;
   const line = `cd ${q(cwd)} && ${inner}`;
 
-  if (process.platform === 'darwin') {
+  if (platform === 'darwin') {
     return {
       platform: 'darwin',
       via: 'Terminal.app',
@@ -41,12 +80,6 @@ export function plan({ cwd, sessionId, command }) {
     };
   }
 
-  if (process.platform === 'win32') {
-    // Windows Terminal when present, the console host otherwise.
-    const wt = ['wt.exe', '-d', cwd, 'cmd.exe', '/k', inner];
-    return { platform: 'win32', via: 'wt.exe', line, argv: wt };
-  }
-
   // Linux and the rest: whichever emulator is actually installed. Names are
   // tried by running them, not by resolving them — a name on PATH that fails
   // to start is the failure mode this ordering exists for.
@@ -57,14 +90,19 @@ export function plan({ cwd, sessionId, command }) {
     ['xfce4-terminal', ['--working-directory', cwd, '-e', `bash -lc ${q(line)}`]],
     ['xterm', ['-e', 'bash', '-lc', line]],
   ];
-  return { platform: process.platform, via: 'candidates', line, candidates };
+  return { platform, via: 'candidates', line, candidates };
 }
 
-/** Launch it, detached, and report what was run. */
-export function open({ cwd, sessionId, command }) {
+/**
+ * Launch it, detached, and report what was run. What runs is always `claude --resume <id>`: the route used to take a
+ * `command` from the request body and run it in place of that, with no id check, and the panel never sent one. An
+ * unused way to run anything in a terminal, behind a token that remote access puts on the network, was removed.
+ */
+export function open({ cwd, sessionId }) {
   if (!cwd || !fs.existsSync(cwd)) return { ok: false, reason: `no such directory: ${cwd}` };
 
-  const p = plan({ cwd, sessionId, command });
+  if (!isSessionId(sessionId)) return { ok: false, reason: `not a session id: ${sessionId}` };
+  const p = plan({ cwd, sessionId });
   if (!p) return { ok: false, reason: `no terminal launcher known for ${process.platform}` };
 
   const attempts = p.argv ? [p.argv] : p.candidates.map(([bin, args]) => [bin, ...args]);

package/kit/studio/server/lib/transcript.js

@@ -98,3 +98,35 @@ export function contextFill(records) {
   }
   return total;
 }
+
+/**
+ * What the context is made of since the last compaction: the share of its text that is tool output, and how many
+ * times the session was compacted, with the last one's tokens before and after. Measured in characters of the main
+ * session's records (text, a tool call's input, a tool's result), not tokens: the transcript keeps no per-block
+ * token count. A compaction is the transcript's own `compact_boundary` record.
+ */
+export function contextMix(records) {
+  let start = 0; let compactions = 0; let last = null;
+  records.forEach((r, i) => {
+    if (r?.isSidechain !== true && r?.type === 'system' && r?.subtype === 'compact_boundary') { start = i + 1; compactions += 1; last = r.compactMetadata ?? null; }
+  });
+  const size = (b) => {
+    if (typeof b === 'string') return b.length;
+    if (b?.type === 'text') return String(b.text ?? '').length;
+    if (b?.type === 'tool_use') return JSON.stringify(b.input ?? {}).length;
+    if (b?.type === 'tool_result') return typeof b.content === 'string' ? b.content.length : (Array.isArray(b.content) ? b.content.reduce((n, x) => n + (x?.type === 'text' ? String(x.text ?? '').length : 0), 0) : 0);
+    return 0;
+  };
+  let tool = 0; let all = 0;
+  for (let i = start; i < records.length; i += 1) {
+    const r = records[i];
+    if (r?.isSidechain === true || (r?.type !== 'user' && r?.type !== 'assistant')) continue;
+    const c = r?.message?.content;
+    for (const b of Array.isArray(c) ? c : [c]) { const n = size(b); all += n; if (b?.type === 'tool_result') tool += n; }
+  }
+  return {
+    toolShare: all ? Math.round((100 * tool) / all) : null,
+    compactions,
+    lastCompact: last ? { trigger: last.trigger ?? null, before: last.preTokens ?? null, after: last.postTokens ?? null } : null,
+  };
+}

package/kit/studio/web/app.js

@@ -29,6 +29,7 @@ import { cardOf, cardLines, workSteps, outsideRouting } from './models-plan.js';
 import { fitLevel, runsOver } from './toolbar-fit.js';
 import { roleName, shownType, modelFamily } from './names.js';
 import { shortcutOf } from './keys.js';
+import { qrSvg } from './qr.js';
 import { SESSION_MODES } from './convo.js';
 import { fmtDuration, fmtTokens, tiles, timeLine, rightNow, skillsOf, delegatedBy, reportOf, backgroundLines, modelLines, TABS as INSPECTOR_TABS, TAB_WORD } from './inspect.js';
 
@@ -113,12 +114,37 @@ const getJson = async (p) => {
     heard.failed = true;
     throw e;
   }
-  if (!r.ok) throw new Error(`HTTP ${r.status}`);
+  if (!r.ok) throw await statusError(r);
   const body = await r.json();
   heardNow();
   return body;
 };
 
+// What the server said about this page's link: a viewer whose link hides transcripts is sent no transcript text.
+let transcriptsHidden = false;
+
+/** The error for an answer with an error status. A viewer link whose eight hours are up covers the page, once. */
+async function statusError(r) {
+  if (r.status === 401) {
+    let b = null; try { b = await r.json(); } catch { /* not JSON */ }
+    if (b?.expired) showExpired();
+  }
+  if (r.status === 403 && transcriptsHidden) return new Error('Transcripts are hidden on this link');
+  return new Error(`HTTP ${r.status}`);
+}
+
+function showExpired() {
+  if (document.getElementById('expired')) return;
+  const box = document.createElement('div');
+  box.id = 'expired';
+  box.className = 'expired';
+  box.setAttribute('role', 'alert');
+  const h = document.createElement('h1'); h.textContent = 'Session expired';
+  const p = document.createElement('p'); p.textContent = 'Viewer links last eight hours. Ask for a new one on the machine running Studio.';
+  box.append(h, p);
+  document.body.append(box);
+}
+
 /* ---------------------------------------------------------------- theme */
 
 try { migrateStorage(localStorage); } catch { /* blocked storage */ }
@@ -2058,6 +2084,9 @@ let handed = null;            // the link of the viewer just added: the server s
 async function pollRemote() {
   if (role !== 'owner') return;
   try { remote = await getJson('/api/remote'); } catch { return; }
+  // The link shown once leaves with its viewer: revoked from elsewhere (the API, another tab) or past its eight
+  // hours, it no longer opens anything, and a QR code left on screen would say it does.
+  if (handed && !(remote.viewers ?? []).some((v) => v.id === handed.id)) handed = null;
   paintMachines();
 }
 
@@ -2074,16 +2103,25 @@ async function remoteWrite(method, path, body) {
   }
 }
 
+/** A time today or tomorrow as the clock on the wall says it, e.g. 23:40. */
+const clockTime = (ms) => (Number.isFinite(ms) ? new Date(ms).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) : '—');
+
+let showTranscripts = false;   // the owner's choice for the next viewer: transcripts stay hidden unless ticked
+
 async function addViewer(button) {
   button.disabled = true;
-  const res = await remoteWrite('POST', '/api/remote', {});
+  const res = await remoteWrite('POST', '/api/remote', { transcripts: showTranscripts });
   if (!res.ok) {
     toast(`No viewer added — ${res.reason ?? 'no reason given'}`);
     button.disabled = false;
     return;
   }
   remote = { ...(remote ?? {}), viewers: res.viewers ?? [] };
-  handed = { id: res.viewer.id, label: res.viewer.label, url: `${location.origin}/?token=${encodeURIComponent(res.viewer.token)}` };
+  // The Wi-Fi link when the server listens on one; this machine's own address only when it found no Wi-Fi address.
+  const wifi = res.lanUrls?.[0] ?? null;
+  handed = { id: res.viewer.id, label: res.viewer.label, wifi, expiresAt: res.viewer.expiresAt, transcripts: res.viewer.transcripts,
+    url: wifi ?? `${location.origin}/?token=${encodeURIComponent(res.viewer.token)}`, lanErrors: res.lan?.errors ?? [] };
+  showTranscripts = false;
   paintMachines();
 }
 
@@ -2114,6 +2152,7 @@ function viewerRow(v) {
     ? `${seenAgo(v.lastSeenAt, Date.now())} · ${v.requests} request${v.requests === 1 ? '' : 's'}${v.open ? ' · watching now' : ''}`
     : 'link not opened yet';
   row.append(node('div', 'sub srow-sub', seen));
+  row.append(node('div', 'sub srow-sub', `until ${clockTime(v.expiresAt)} · transcripts ${v.transcripts ? 'shown' : 'hidden'}${v.addresses?.length ? ` · from ${v.addresses.join(', ')}` : ''}`));
   return row;
 }
 
@@ -2131,9 +2170,24 @@ function remoteSection() {
   head.append(node('span', 'rv-title', 'Remote viewers'), node('span', 'row-fill'), add);
   box.append(head);
 
+  // Transcripts stay hidden on a new link unless this is ticked before Add viewer.
+  const opt = node('label', 'rv-opt');
+  const tick = document.createElement('input');
+  tick.type = 'checkbox'; tick.checked = showTranscripts;
+  tick.addEventListener('change', () => { showTranscripts = tick.checked; });
+  opt.append(tick, document.createTextNode(' Show transcripts on the next link'));
+  box.append(opt);
+
   if (handed) {
     const give = node('div', 'rv-give');
-    give.append(node('div', 'sub rv-say', `Link for ${handed.label}. Shown once; open it on the other device, through your tunnel.`));
+    give.append(node('div', 'sub rv-say', handed.wifi
+      ? `Link for ${handed.label}, shown once. Scan it with a phone on the same Wi-Fi. It lasts until ${clockTime(handed.expiresAt)}; transcripts ${handed.transcripts ? 'shown' : 'hidden'}.`
+      : `Link for ${handed.label}, shown once. No Wi-Fi address was found${handed.lanErrors.length ? ` (${handed.lanErrors.join('; ')})` : ''}, so it opens on this machine only.`));
+    if (handed.wifi) {
+      const code = node('div', 'rv-qr');
+      code.innerHTML = qrSvg(handed.wifi, { px: 3 });
+      give.append(code);
+    }
     const url = node('code', 'rv-url', handed.url);
     const copy = node('button', 'btn sm', 'Copy link');
     copy.type = 'button';
@@ -2150,7 +2204,7 @@ function remoteSection() {
   for (const v of list) box.append(viewerRow(v));
   if (!list.length) {
     box.append(node('div', 'sub rv-say',
-      'A viewer reads this panel from another device and changes nothing. The server stays on 127.0.0.1; the link opens through a tunnel you run.'));
+      'A viewer watches this panel from a phone on the same Wi-Fi and changes nothing. Its link lasts eight hours. With no viewer, the server listens on 127.0.0.1 only.'));
   }
   return box;
 }
@@ -2636,7 +2690,9 @@ if (typeof ResizeObserver !== 'undefined') new ResizeObserver(() => requestAnima
 // They survive a page reload as long as the server does.
 let ownedBusy = false;
 async function pollOwned() {
-  if (ownedBusy) return;
+  // A link that hides transcripts is refused the sessions the panel runs (their conversation is all transcript):
+  // asking every few seconds would only fill the machine's log with the same refusal.
+  if (ownedBusy || transcriptsHidden) return;
   ownedBusy = true;
   try {
     const r = await getJson('/api/owned');
@@ -2822,8 +2878,14 @@ getJson('/api/health').then((h) => {
   // A Map read before this answer showed the old server's 404; read it again so it says why.
   if (restartNote) { paintStageNote(); if (view === 'map') loadMap(true); }
   role = h.role === 'viewer' ? 'viewer' : 'owner';
+  transcriptsHidden = role === 'viewer' && h.transcripts === false;
   document.body.dataset.role = role;
-  document.getElementById('role').hidden = role !== 'viewer';
+  const badge = document.getElementById('role');
+  badge.hidden = role !== 'viewer';
+  if (transcriptsHidden) {
+    badge.textContent = 'Read-only · transcripts hidden';
+    badge.title = 'This link reads the panel and changes nothing; no transcript text is sent to it';
+  }
   if (role === 'owner') pollRemote(); else paintMachines();
 }).catch(() => { /* the Live indicator says the server is unreachable */ });
 setInterval(() => { nextPollAt = Date.now() + FLEET_POLL_MS; pollFleet(); }, FLEET_POLL_MS);