crewforth 3.2.0-rc.2 → 3.2.0-rc.4

package/kit/skills/crew-map/SKILL.md

@@ -27,18 +27,29 @@ the scan itself read, and a gate holds it to that. **Never commit.** Show the di
 
 3. **Describe.** Read `.crewforth/crew-map.json`, and as much of the cited source as you need. Then edit that
    file, changing ONLY these fields:
-   - each `module` node's `narrative`: `{ "text": "…", "cites": ["file:line", …] }`. What the module is for, in
-     at most two sentences. Every cite is a `file:line` from THAT node's own `evidence`; cite at least one. Leave a
-     node `null` when its evidence does not tell you what it is for: an honest gap beats a guess.
+   - each `module` node's `narrative`: `{ "text": "…", "cites": ["file:line", …], "layer": "…", "domain": "…" }`.
+     What the module is for, in at most two sentences. Every cite is a `file:line` the scan read for THAT node: its
+     `evidence`, its `entryPoint`, or its `about` (the first prose line of its README); cite at least one. `layer` is where it sits, one of `ui` (what a person uses: an app, a site),
+     `api` (serves requests to others), `service` (runs work: a worker, a job), `data` (holds or shapes data),
+     `infra` (deploys and runs the rest), `tool` (a script or CLI for the team), `library` (code other modules
+     import); `domain` is the part of the business it serves, a short phrase ("payments", "mail import"). Both
+     are optional and rest on the same cites: leave one out rather than guess. Leave a node `null` when its
+     evidence does not tell you what it is for: an honest gap beats a guess.
    - the document's `overview`: the same shape, at most 2000 characters, for someone new to the project: the entry
      points, where data goes, the risky places. Its cites may be any node's evidence.
+   - the document's `tour`: `[{ "node": "<id>", "text": "…", "cites": ["file:line"] }, …]`, one to eight stops a
+     newcomer reads in order, usually the entry point first and the riskiest place last. Each stop names a node of
+     the map, says in at most two sentences why to look there, and cites lines from that node's own evidence.
    Describe what the cited lines show. A connection, a purpose or a risk the scan did not find is not added here:
    say it to the user instead.
 
 4. **Validate:** `bash MAP --validate` (Bash tool, not PowerShell). It refuses a description that cites a line
-   the scan did not read, cites nothing, or runs past two sentences, and a map whose scanner fields were changed.
+   the scan did not read, cites nothing, or runs past two sentences; a layer not on the list or a domain written
+   as a sentence; a tour stop at no node, citing another node's lines, or at a node twice; and a map whose
+   scanner fields were changed.
    Fix what it names, in the descriptions only, until it holds.
 
-5. **Hand over:** the scan's summary line, how many modules you described and how many you left `null` and why,
+5. **Hand over:** the scan's summary line, how many modules you described (and gave a layer) and how many you
+   left `null` and why, the tour's stops,
    then `git diff --stat .crewforth/crew-map.json`. Studio's **Map** view (`/crew-studio`) draws the result.
    Committing it is the user's call.

package/kit/skills/crew-review/SKILL.md

@@ -16,7 +16,8 @@ Run the change set through the review trio (read-only). **The audits go out in p
    - @agent-crew-privacy-agent (`privacy-compliance`) — **when the diff touches personal data**: legal basis,
      minimisation, retention, transfer.
 2. (if SonarQube is in use) **sonarqube-check** — 0/0/0/0 gate (language-agnostic).
-3. **Last, once 1-2 leave no blocker:** @agent-crew-review-agent (crew-code-review) — "does it improve overall
+3. **Last, once 1-2 leave no blocker:** @agent-crew-review-agent (crew-code-review) — it starts from the
+   deterministic pre-pass (`.crewforth/review-prepass.json`) and writes `.crewforth/review.json`; "does it improve overall
    code health": the plan (what changed, the risks), then findings with a severity and a category. "Clean" means
    what crew-code-review means by it: **no critical or high finding open**. A medium or low audit finding does not
    hold the reviewer back; hand it over in the reviewer's prompt and keep it in the report. A critical or high one

package/kit/skills/crew-ship/SKILL.md

@@ -9,7 +9,9 @@ Closure flow — in order:
 1. **DoD gate:** was `/simplify` applied · are tests green (@agent-crew-test-expert) · (if SonarQube is used) `sonarqube-check` 0/0/0/0.
    If any one is red, **STOP**, report what is missing; no deferral.
 2. If clean, @agent-crew-commit-agent (commit-message) **proposes** an atomic Conventional Commit from the staged diff.
-3. Commit runs ONLY if the user says "commit" (§4.4). "Done" is not approval.
+3. Commit runs ONLY if the user says "commit" (§4.4). "Done" is not approval. In `auto`, Crewforth hands the session the
+   one-click approval question when crew-commit-agent is called: ask it with the message; the typed `/crew-approve` is
+   for when no question is offered.
 4. **Close the board item too** (`teamboard`), when one is held. Closing work is one movement: ask what shipped,
    run `board.sh done <id> "<note>"`, name the items it unblocked, and offer the next one as options. Do not
    leave this to the user to remember — a claim nobody closes reads to the whole team as still in progress, and

package/kit/studio/README.md

@@ -201,14 +201,23 @@ loopback and the tunnel does the crossing.
 ## Remote viewers
 
 A viewer is a second token that reads and changes nothing, for watching the
-panel from another device without handing that device the panel. Add one in the
-Machines tab; its link is shown once. The server refuses a viewer's every
-request that is not a `GET`, and its reads of `/api/remote`, with 403 before any
-handler runs (`server/lib/remote.js`). Revoke ends the token and closes a
-stream it holds open. Viewers live in memory and end with the server.
-
-The server still binds to loopback. Reaching it from a phone is a tunnel the
-user runs, an ssh forward or `tailscale serve 7777`; Studio starts none.
+panel from a phone on the same Wi-Fi without handing it the panel. Add one in
+the Machines tab; its link is shown once, as a QR code (`web/qr.js`, made in the
+page). The server refuses a viewer's every request that is not a `GET`, and its
+reads of `/api/remote`, with 403 before any handler runs (`server/lib/remote.js`).
+A viewer lasts eight hours, then its link answers 401 and the page says Session
+expired. Revoke ends the token at once and closes a stream it holds open.
+Viewers live in memory and end with the server.
+
+Transcripts are hidden unless the viewer was added with them shown: the routes
+that are only transcript are refused, and every other answer, the event stream
+included, passes through `server/lib/redact.js`, which drops every string whose
+key is not on its allow-list.
+
+While a viewer is live the server also listens on the machine's private Wi-Fi
+address (`server/lib/lan.js`), and there it takes a viewer's token only, never
+the panel's. With none, it is on loopback alone. Every viewer connection and
+refusal is logged (`GET /api/remote`, and the server's output).
 
 ## What Crewforth already measured
 
@@ -261,8 +270,10 @@ channel that does not exist.
 
 ## Security
 
-The server binds to `127.0.0.1` only, and the host is deliberately not
-configurable — it reads a developer's live sessions and can start new ones.
+The server binds to `127.0.0.1`, and the host is deliberately not configurable —
+it reads a developer's live sessions and can start new ones. The one exception is
+the Wi-Fi listener above: open only while a viewer is live, for viewer tokens
+only, read-only.
 
 A token is always required for `/api/`. Supply one, or let the server generate
 one and print it with the URL:

package/kit/studio/server/index.js

@@ -31,14 +31,17 @@ import { palette } from './lib/palette.js';
 import { latestVersion, latestVersionCached, kitStatus } from './lib/kit.js';
 import { parsePeers, askAll, ask } from './lib/peers.js';
 import {
-  createSession, getSession, listSessionsOwned, reap, stopAll, dropSpools, ALLOWED_MODES,
+  createSession, getSession, listSessionsOwned, reap, stopAll, dropSpools, ALLOWED_MODES, isHeldOpen,
 } from './lib/session.js';
 import { decide, pending, alwaysList, revoke, sweepLeft } from './lib/permissions.js';
-import { open as openTerminal, plan as terminalPlan } from './lib/terminal.js';
+import { open as openTerminal, plan as terminalPlan, desktopLine } from './lib/terminal.js';
 import { gateLog, gateReport, sessionStats, board } from './lib/kit-telemetry.js';
 import { writeState, clearStateSync, findRunning } from './lib/instance.js';
 import { remoteRoster } from './lib/roster.js';
-import { addViewer, listViewers, viewerByToken, revokeViewer, noteRequest, viewerMay, MAX_VIEWERS } from './lib/remote.js';
+import { addViewer, listViewers, viewerByToken, revokeViewer, noteRequest, noteRefusal, viewerMay, MAX_VIEWERS, VIEWER_TTL_MS,
+  liveCount, remoteLog, sweep as sweepViewers, onViewersChange, onLog } from './lib/remote.js';
+import { redact, transcriptOnly } from './lib/redact.js';
+import { lanListener } from './lib/lan.js';
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 
@@ -98,8 +101,12 @@ function send(res, status, body, headers = {}) {
   res.end(body);
 }
 
+// The answers that go to a viewer whose link hides transcripts: every one of them passes through redact() on its way
+// out, here and in the event stream, so no route has to remember to.
+const REDACTED = new WeakSet();
+
 function sendJson(res, status, value) {
-  send(res, status, JSON.stringify(value, null, 2), {
+  send(res, status, JSON.stringify(REDACTED.has(res) ? redact(value) : value, null, 2), {
     'content-type': 'application/json; charset=utf-8',
   });
 }
@@ -114,8 +121,12 @@ function sendJson(res, status, value) {
 const TOKEN = process.env.CREW_STUDIO_TOKEN || randomUUID();
 const TOKEN_GENERATED = !process.env.CREW_STUDIO_TOKEN;
 
+// The Wi-Fi listener (lib/lan.js): set by main() once the port is known, and opened and closed with the number of
+// live viewers. Null in the self-check unless it makes one.
+let LAN = null;
+
 /** For the self-check, which asks a real server as the owner and as a viewer. */
-export const _internals = { token: TOKEN };
+export const _internals = { token: TOKEN, setLan: (l) => { LAN = l; } };
 
 // Peers are other machines running Studio, reached over a forwarded port. This
 // server still listens on loopback only; a peer never widens that.
@@ -130,9 +141,12 @@ function whoAsks(req, url) {
   const header = req.headers['authorization'];
   const bearer = typeof header === 'string' && header.startsWith('Bearer ') ? header.slice(7) : null;
   const given = [bearer, url.searchParams.get('token')].filter(Boolean);
-  if (given.includes(TOKEN)) return { role: 'owner' };
+  // The panel's own token is accepted on loopback only. From the Wi-Fi it is not a token at all: a phone holding it
+  // would hold the panel, and nothing on the network should.
+  if (!req.crewLan && given.includes(TOKEN)) return { role: 'owner' };
   for (const t of given) {
     const viewer = viewerByToken(t);
+    if (viewer?.expired) return { role: 'expired', label: viewer.expired };
     if (viewer) return { role: 'viewer', viewer };
   }
   return null;
@@ -247,14 +261,30 @@ export async function handle(req, res) {
   // it for /style.css served an unstyled page and protected nothing: the shell
   // holds no secrets, and every /api/ path below is still gated.
   const who = url.pathname.startsWith('/api/') ? whoAsks(req, url) : null;
+  // From the Wi-Fi, no token (or the panel's own) is 401: the network is asked who it is. On loopback the answer
+  // stays 403, as it always was.
   if (url.pathname.startsWith('/api/') && !who) {
-    return sendJson(res, 403, { ok: false, reason: 'token required' });
+    if (req.crewLan) noteRefusal(req, { status: 401, reason: 'no viewer token' });
+    return sendJson(res, req.crewLan ? 401 : 403, { ok: false, reason: 'token required' });
+  }
+  if (who?.role === 'expired') {
+    noteRefusal(req, { viewer: who.label, status: 401, reason: 'expired' });
+    return sendJson(res, 401, { ok: false, expired: true, reason: 'this link has expired: viewer links last eight hours' });
   }
   // A viewer is refused HERE, before any handler: no route below has to remember that a viewer exists, and a
-  // route added tomorrow is read-only for a viewer without anyone writing a line for it.
+  // route added tomorrow is read-only for a viewer without anyone writing a line for it. The same holds for a
+  // link that hides transcripts: the routes that are nothing but transcript are refused here, and every other
+  // answer is filtered on its way out (REDACTED).
   if (who?.role === 'viewer') {
     const may = viewerMay(req.method, url.pathname);
-    if (!may.ok) return sendJson(res, 403, { ok: false, reason: may.reason });
+    if (!may.ok) { noteRefusal(req, { viewer: who.viewer.label, status: 403, reason: may.reason }); return sendJson(res, 403, { ok: false, reason: may.reason }); }
+    if (!who.viewer.transcripts) {
+      if (transcriptOnly(url.pathname)) {
+        noteRefusal(req, { viewer: who.viewer.label, status: 403, reason: 'transcripts hidden' });
+        return sendJson(res, 403, { ok: false, transcriptsHidden: true, reason: 'transcripts are hidden on this link' });
+      }
+      REDACTED.add(res);
+    }
     noteRequest(who.viewer, req, res);
   }
 
@@ -262,6 +292,7 @@ export async function handle(req, res) {
     return sendJson(res, 200, {
       ok: true,
       role: who.role,
+      ...(who.role === 'viewer' ? { transcripts: who.viewer.transcripts, expiresAt: who.viewer.expiresAt } : {}),
       node: process.version,
       pid: process.pid,
       uptimeMs: Math.round(process.uptime() * 1000),
@@ -502,8 +533,12 @@ export async function handle(req, res) {
     const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
 
     if (req.method === 'GET') {
-      // What WOULD run, so the panel can show it before anything is launched.
-      return sendJson(res, 200, { measured: true, cwd, plan: cwd ? terminalPlan({ cwd, sessionId: id }) : null });
+      // What WOULD run, so the panel can show it before anything is launched; and, before Continue here is pressed,
+      // what it will do: continue this same session (nothing else holds it), or start a copy (something does). The
+      // answer is the one createSession acts on, asked the same way.
+      const held = await isHeldOpen(id);
+      return sendJson(res, 200, { measured: true, cwd, plan: cwd ? terminalPlan({ cwd, sessionId: id }) : null,
+        continueAs: held ? 'copy' : 'same', desktop: cwd ? desktopLine({ cwd, sessionId: id }) : null });
     }
 
     const gate = writeAllowed(req);
@@ -515,7 +550,6 @@ export async function handle(req, res) {
     const out = openTerminal({
       cwd: typeof body.cwd === 'string' ? body.cwd : cwd,
       sessionId: id,
-      command: typeof body.command === 'string' ? body.command : undefined,
     });
     return sendJson(res, out.ok ? 200 : 400, out);
   }
@@ -529,7 +563,8 @@ export async function handle(req, res) {
      the owner reaches this far; a viewer was refused above. */
 
   if (url.pathname === '/api/remote' && req.method === 'GET') {
-    return sendJson(res, 200, { measured: true, viewers: listViewers(), max: MAX_VIEWERS, now: Date.now() });
+    return sendJson(res, 200, { measured: true, viewers: listViewers(), max: MAX_VIEWERS, ttlMs: VIEWER_TTL_MS, now: Date.now(),
+      lan: LAN ? LAN.state() : { listening: false, addresses: [], errors: [] }, log: remoteLog(30) });
   }
 
   const remoteMatch = url.pathname.match(/^\/api\/remote(?:\/([^/]+))?$/);
@@ -539,11 +574,16 @@ export async function handle(req, res) {
     if (req.method === 'POST' && !remoteMatch[1]) {
       const body = await readBody(req);
       if (!body) return sendJson(res, 400, { ok: false, reason: 'body was not JSON' });
-      const made = addViewer(body.label);
-      return sendJson(res, made.ok ? 201 : 409, { ...made, viewers: listViewers() });
+      const made = addViewer(body.label, { transcripts: body.transcripts === true });
+      // The Wi-Fi listener opens with the first viewer; its links are known once it listens.
+      if (made.ok && LAN) await LAN.sync(liveCount());
+      const lanUrls = made.ok && LAN ? LAN.urls(made.viewer.token) : [];
+      return sendJson(res, made.ok ? 201 : 409, { ...made, lanUrls, lan: LAN ? LAN.state() : null, viewers: listViewers() });
     }
     if (req.method === 'DELETE' && remoteMatch[1]) {
-      return sendJson(res, 200, { ...revokeViewer(decodeURIComponent(remoteMatch[1])), viewers: listViewers() });
+      const out = revokeViewer(decodeURIComponent(remoteMatch[1]));
+      if (LAN) await LAN.sync(liveCount());
+      return sendJson(res, 200, { ...out, lan: LAN ? LAN.state() : null, viewers: listViewers() });
     }
     return sendJson(res, 405, { ok: false, reason: 'POST to add a viewer, or DELETE a viewer id' });
   }
@@ -744,7 +784,7 @@ async function stream(req, res, url) {
   });
 
   const send = (event, data) => {
-    res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    res.write(`event: ${event}\ndata: ${JSON.stringify(REDACTED.has(res) ? redact(data) : data)}\n\n`);
   };
 
   // A session the panel just started has no transcript until its first turn
@@ -988,9 +1028,11 @@ async function main() {
         '  --help       this text\n\n' +
         'Set CREW_STUDIO_TOKEN to require a bearer token, CREW_STUDIO_PEERS for a\n' +
         'comma-separated peer list.\n\n' +
-        'To watch from another device, add a viewer under Machines in the panel\n' +
-        'and open its link through a tunnel of your own. A viewer reads and\n' +
-        'changes nothing, and the server stays on loopback.\n\n' +
+        'To watch from a phone on the same Wi-Fi, add a viewer under Machines in\n' +
+        'the panel and scan its QR code. A viewer reads and changes nothing, its\n' +
+        'link lasts eight hours, and transcripts stay hidden unless you show them.\n' +
+        'While a viewer is live the server also listens on this machine\'s Wi-Fi\n' +
+        'address, for viewer links only; with none it is on loopback alone.\n\n' +
         'Peers are normally reached over a forwarded port, which keeps every\n' +
         'Studio on loopback:\n' +
         '  ssh -N -L 7778:127.0.0.1:7777 other-machine\n' +
@@ -1007,12 +1049,21 @@ async function main() {
   // Only a server that is about to run does this; asking for --help or --selftest removes nothing.
   sweepLeft();
 
-  const server = http.createServer((req, res) => {
+  const handler = (req, res) => {
     handle(req, res).catch((e) => {
       process.stderr.write(`crewforth-studio: unhandled: ${e?.stack ?? e}\n`);
       if (!res.headersSent) send(res, 500, 'internal error');
     });
-  });
+  };
+  const server = http.createServer(handler);
+
+  // Viewers on the same Wi-Fi: a second listener on this machine's private address, open only while a viewer is
+  // live (lib/lan.js). It closes when the last one is revoked or expires; the sweep ends expired ones even when no
+  // request comes to notice them.
+  LAN = lanListener({ handler, port: args.port });
+  onViewersChange((n) => { LAN.sync(n); });
+  onLog((e) => process.stdout.write(`            viewer ${e.event}: ${e.viewer ?? 'unknown'}${e.ip ? ` from ${e.ip}` : ''}${e.over ? ` (${e.over})` : ''}${e.result ? ` — ${e.result}` : ''}\n`));
+  setInterval(sweepViewers, 60 * 1000).unref();
 
   // A BUSY PORT IS NOT AUTOMATICALLY A PROBLEM. Before 2.10.2 this printed "try --port n+1" and exited 1, which
   // is the right answer only when a stranger holds the port. When the holder is our OWN panel -- the common case,
@@ -1093,6 +1144,7 @@ async function main() {
       // leaks running sessions is worse than one that never started them.
       stopAll();
       dropSpools();
+      LAN?.close();
       server.close(() => process.exit(0));
       setTimeout(() => process.exit(0), 2000).unref();
     });

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

@@ -17,7 +17,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 
-import { readAll, contextFill } from './transcript.js';
+import { readAll, contextFill, contextMix } from './transcript.js';
 import { agentMetaFiles } from './projects.js';
 import { Usage, withTimes } from './usage.js';
 import { detailOf } from './permissions.js';
@@ -139,6 +139,7 @@ export function linkRetries(calls) {
     if (!c.refused) return;
     const again = list.slice(i + 1).find((n) => n.subagentType === c.subagentType && n.description === c.description);
     if (!again) return;
+    c.retried = true;
     // A call refused twice keeps the first thing that was asked.
     again.firstTry = c.firstTry ?? { asked: c.model, floor: c.refused.floor, text: c.refused.text };
   });
@@ -456,7 +457,14 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
     version: main.version,
     status: 'session',
     turns: main.userTurns,
+    // Agent calls the model gate refused and the session has not made again: no agent started, so nothing else on
+    // the canvas says they happened (seen on a real project: two refused calls, an empty canvas, "2 failed" only in
+    // the session's own view). A refused call made again is shown on the call that ran (`firstTry`).
+    refusedCalls: [...main.agentCalls.values()].filter((c) => c.refused && !c.retried)
+      .map((c) => ({ agent: c.subagentType ?? null, model: c.model ?? null, text: c.refused.text })),
     tokens: contextFill(records),
+    // What that context is made of: the tool-output share since the last compaction, and the compactions so far.
+    context: contextMix(records),
     startedAt: main.startedAt,
     endedAt: main.updatedAt,
     usage: withTimes(usage, records),

package/kit/studio/server/lib/kit-telemetry.js

@@ -52,11 +52,36 @@ function kitPaths(cwd) {
  * empty unless CREW_GATE_LOG_CMD=1 was set, and there is no timestamp at all —
  * both facts are returned rather than papered over.
  */
+/**
+ * Where the gate log is, by the rule the gates write by (eval/lib/gate-log.sh): .claude/gate-log.tsv, else the
+ * repository's own .git/crewforth-gate-log.tsv (a project that tracks .claude/ has it there), searched from the
+ * project root up. null when there is none yet.
+ */
+export function gateLogPath(cwd) {
+  const own = path.join(cwd, '.claude', 'gate-log.tsv');
+  if (fs.existsSync(own)) return own;
+  let d = cwd;
+  for (let n = 0; n < 12; n += 1) {
+    const g = path.join(d, '.git');
+    let st = null;
+    try { st = fs.statSync(g); } catch { /* not here */ }
+    if (st?.isDirectory()) { const f = path.join(g, 'crewforth-gate-log.tsv'); return fs.existsSync(f) ? f : null; }
+    if (st?.isFile()) {
+      const m = /^gitdir: (.+)$/m.exec(fs.readFileSync(g, 'utf8'));
+      if (!m) return null;
+      const gd = path.resolve(d, m[1].trim()); const f = path.join(gd, 'crewforth-gate-log.tsv');
+      return fs.existsSync(f) ? f : null;
+    }
+    const up = path.dirname(d); if (up === d) return null; d = up;
+  }
+  return null;
+}
+
 export function gateLog(cwd, { limit = 200 } = {}) {
-  const file = path.join(cwd, '.claude', 'gate-log.tsv');
+  const file = gateLogPath(cwd);
   let st;
-  try { st = fs.statSync(file); } catch {
-    return { measured: false, reason: 'no .claude/gate-log.tsv in this project', entries: [] };
+  try { st = fs.statSync(file ?? ''); } catch {
+    return { measured: false, reason: 'no gate log in this project yet (.claude/gate-log.tsv, or .git/crewforth-gate-log.tsv where .claude/ is tracked)', entries: [] };
   }
 
   // Only the tail: this file reached 21,730 lines in Crewforth's own checkout and
@@ -119,9 +144,9 @@ export async function gateReport(cwd) {
   // should read is one level up. Both layouts are given what they expect rather
   // than the script being asked to guess.
   const from = kit.kind === 'installed' ? cwd : path.dirname(kit.hooks);
-  const logPath = path.join(cwd, '.claude', 'gate-log.tsv');
+  const logPath = gateLogPath(cwd);
   const env = { ...process.env };
-  if (kit.kind !== 'installed' && fs.existsSync(logPath)) env.CREW_GATE_LOG = logPath;
+  if (logPath) env.CREW_GATE_LOG = logPath;
 
   const r = await run('bash', [script, '--json'], { cwd: from, env });
   // 3 means there is no log to read, which the script calls "not an error"; 4

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;
+}