crewforth 3.1.1 → 3.2.0-rc.10

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/model-outcomes.js

@@ -2,7 +2,7 @@
 //
 // Crewforth writes one line per finished crew agent to `.claude/state/model-outcomes.tsv` (hooks/agent-outcome.sh):
 //
-//   ts  agent_id  agent  change  risk  card  model  verify  fixes  escalated_from  ran_on  confidence
+//   ts  agent_id  agent  change  risk  card  model  verify  fixes  escalated_from  ran_on  confidence  [risk_why]
 //
 // Twelve columns, tab-separated, a header on the first line, "-" for an empty value, and any column added later
 // is added at the end. This file reads that and adds nothing to it: a class's first-try success is counted from
@@ -19,11 +19,18 @@
 // failed too often. Lowering such a hold is the user's to approve, with a Crewforth command in their own session:
 // Studio shows which holds could be lowered (`suggestionsOf`) and writes nothing. A panel's button is a request
 // any process of the same user can send, so it cannot stand for the user.
+//
+// The gate holds a floor and no ceiling: normal work may run on a model above the one the table in CLAUDE.md asks
+// for it. Studio shows that work (`aboveTableOf`) and blocks nothing. That the table's model would have done is
+// said only where this record shows it: the class's latest LOOSEN_AFTER verified calls on that model all passed the
+// first time, the same test a hold is offered for lowering by.
 
 import fs from 'node:fs';
 import path from 'node:path';
 
 export const COLUMNS = ['ts', 'agent_id', 'agent', 'change', 'risk', 'card', 'model', 'verify', 'fixes', 'escalated_from', 'ran_on', 'confidence'];
+// Added at the end later, so a line written before them is still whole without them.
+export const LATER_COLUMNS = ['risk_why'];
 const VERIFIED = new Set(['pass', 'fail']);
 // What the hooks write, and nothing else is a row. The words are hooks/guard-agent-model.sh's and
 // hooks/agent-outcome.sh's; a word they do not use is a line this file cannot read, not a new kind of work.
@@ -36,6 +43,14 @@ const MAX_BYTES = 4 * 1024 * 1024;      // the record is read whole; past this o
 // A starting point; it has not been measured.
 export const LOOSEN_AFTER = 10;
 const TRAIL_MAX = 6;
+// What the table in CLAUDE.md asks of normal work, at most. Above it is a choice the gate lets the caller make.
+export const NORMAL_TIER = 'sonnet';
+// The floor hooks/guard-agent-model.sh puts under an agent whatever its card says (its `case "$st"`).
+export const AGENT_FLOORS = {
+  'crew-security-expert': 'opus',
+  'crew-privacy-agent': 'sonnet', 'crew-review-agent': 'sonnet', 'crew-planner': 'sonnet', 'crew-database-expert': 'sonnet',
+};
+const rankOf = (t) => TIERS.indexOf(t) + 1;   // 1..4, 0 for no tier: the gate's _am_rank
 
 const stateDir = (cwd) => path.join(cwd, '.claude', 'state');
 const dash = (v) => (v === '-' || v === '' || v == null ? null : v);
@@ -72,6 +87,8 @@ export function parseOutcomes(text) {
       line: i, ts: f[0], at, agentId: f[1], agent: f[2], change: f[3], risk: f[4], card: dash(f[5]),
       model: dash(f[6]), verify: f[7], fixes: Number.parseInt(f[8], 10), escalatedFrom: dash(f[9]), ranOn: dash(f[10]),
       confidence: dash(f[11]),
+      // Written by the gate when it called the work critical; a line from before it kept the reason has no column.
+      riskWhy: dash(f[12]),
     });
   }
   return out;
@@ -102,9 +119,53 @@ export function parseLoosened(text) {
   return out;
 }
 
+/**
+ * The `floor <agent> <change> <risk> <model>` lines of the project's .claude/crew-model-rules; `*` matches any.
+ * Read as hooks/guard-agent-model.sh reads them (`_am_rules`): a comment is cut at #, the model is found in the word.
+ */
+export function parseRuleFloors(text) {
+  const out = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const l = line.replace(/\r$/, '').replace(/#.*/, '').trim();
+    const m = l.match(/^floor\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)/);
+    if (!m) continue;
+    const model = TIERS.find((t) => m[4].toLowerCase().includes(t));
+    if (model) out.push({ agent: m[1], change: m[2], risk: m[3], model });
+  }
+  return out;
+}
+
 const keyOf = (r) => `${r.agent}\t${r.change}\t${r.risk}`;
 const firstTry = (r) => r.verify === 'pass' && r.fixes === 0;
 
+/**
+ * The lowest model the gate would have let this call run on, as a rank (see `rankOf`): the highest of what
+ * applies, the order of hooks/guard-agent-model.sh. The project's rules are read as they are now; a raise from the
+ * record counts for the calls made after it, lowered or not, so a call it held is never said to have run above.
+ */
+export function floorOfRow(r, ruleFloors = [], floors = []) {
+  let f = rankOf(AGENT_FLOORS[r.agent]);
+  if (r.verify === 'none') f = Math.max(f, 2);
+  if (r.change === 'test-write' || r.change === 'audit') f = Math.max(f, 2);
+  if (r.risk === 'critical' && r.change !== 'test-run') f = Math.max(f, 3);
+  const any = (want, v) => want === '*' || want === v;
+  for (const x of ruleFloors) if (any(x.agent, r.agent) && any(x.change, r.change) && any(x.risk, r.risk)) f = Math.max(f, rankOf(x.model));
+  for (const x of floors) if (keyOf(x) === keyOf(r) && !(String(r.ts) < String(x.when ?? ''))) f = Math.max(f, rankOf(x.model));
+  if (r.escalatedFrom) f = Math.max(f, rankOf(r.escalatedFrom) + 1);
+  return f;
+}
+
+/**
+ * How many of a class's latest `need` verified calls on `model`, since `since`, there are when every one of them
+ * passed the first time; 0 when there are fewer, or one did not. The test for lowering a hold and for saying the
+ * table's model would have done.
+ */
+function passedLatest(rows, k, model, since, need) {
+  const recent = rows.filter((r) => keyOf(r) === k && r.model === model && VERIFIED.has(r.verify) && (r.at ?? 0) >= since)
+    .sort((a, b) => (b.at ?? 0) - (a.at ?? 0)).slice(0, need);
+  return recent.length >= need && recent.every(firstTry) ? recent.length : 0;
+}
+
 /**
  * The lowering that stands for a raised floor, or null. The rule is hooks/guard-agent-model.sh's (`_am_floor_now`),
  * word for word: a lowering counts when it is not older than the raise it answers (the times are UTC text and are
@@ -161,13 +222,16 @@ export function classesOf(rows, floors = [], loosened = []) {
  * `costed` of `runs` were priced; the rest are not in the sum, so the sum is a floor and not the total.
  * @param costOf  (agentId) => USD or null
  */
-export function classCosts(rows, costOf) {
+export function classCosts(rows, costOf, advisorOf = () => null) {
   const out = {};
   for (const r of rows) {
-    const c = (out[keyOf(r)] ??= { cost: 0, costed: 0, runs: 0 });
+    const c = (out[keyOf(r)] ??= { cost: 0, costed: 0, runs: 0, advisorCalls: 0, advisorCost: 0 });
     c.runs += 1;
     const usd = costOf(r.agentId);
     if (typeof usd === 'number') { c.cost += usd; c.costed += 1; }
+    // The advisor's share is part of `cost` already; it is counted apart only to be said.
+    const a = advisorOf(r.agentId);
+    if (a?.calls > 0) { c.advisorCalls += a.calls; if (typeof a.cost === 'number') c.advisorCost += a.cost; }
   }
   return out;
 }
@@ -186,11 +250,52 @@ export function suggestionsOf(rows, floors = [], loosened = [], need = LOOSEN_AF
     const k = keyOf(f);
     // Once for each raise: a floor whose lowering stands is not offered again (the same rule the gate reads it by).
     if (loweringOf(f, loosened)) continue;
-    const since = Date.parse(f.when ?? '') || 0;
-    const recent = rows.filter((r) => keyOf(r) === k && r.model === f.model && VERIFIED.has(r.verify) && (r.at ?? 0) >= since)
-      .sort((a, b) => (b.at ?? 0) - (a.at ?? 0)).slice(0, need);
-    if (recent.length < need || !recent.every(firstTry)) continue;
-    out.push({ key: k, agent: f.agent, change: f.change, risk: f.risk, from: f.model, to: TIERS[tier - 1], passed: recent.length, heldSince: f.when ?? null });
+    const passed = passedLatest(rows, k, f.model, Date.parse(f.when ?? '') || 0, need);
+    if (!passed) continue;
+    out.push({ key: k, agent: f.agent, change: f.change, risk: f.risk, from: f.model, to: TIERS[tier - 1], passed, heldSince: f.when ?? null });
+  }
+  return out;
+}
+
+/**
+ * Normal work that ran above the table's model, by class, the busiest first: the calls on a model above both
+ * NORMAL_TIER and the floor the gate held them to (`floorOfRow`). `passed` is how many of the class's latest
+ * verified calls on NORMAL_TIER passed the first time (counted from the class's raise, where it has one), when it
+ * is `need` of `need`; otherwise 0, and nothing is said about whether NORMAL_TIER would have done.
+ * `ids` are the agents' ids, for pricing; they are not sent to a page (`readModels`).
+ */
+export function aboveTableOf(rows, ruleFloors = [], floors = [], need = LOOSEN_AFTER) {
+  const by = new Map();
+  const top = rankOf(NORMAL_TIER);
+  for (const r of rows) {
+    if (r.risk !== 'normal' || rankOf(r.model) <= Math.max(top, floorOfRow(r, ruleFloors, floors))) continue;
+    const k = keyOf(r);
+    const c = by.get(k) ?? by.set(k, { key: k, agent: r.agent, change: r.change, risk: r.risk, to: NORMAL_TIER, runs: 0, models: {}, ids: [] }).get(k);
+    c.runs += 1;
+    c.models[r.model] = (c.models[r.model] ?? 0) + 1;
+    c.ids.push(r.agentId);
+  }
+  return [...by.values()].map((c) => {
+    const held = floors.find((f) => keyOf(f) === c.key);
+    return { ...c, need, passed: passedLatest(rows, c.key, NORMAL_TIER, Date.parse(held?.when ?? '') || 0, need) };
+  }).sort((a, b) => b.runs - a.runs || a.key.localeCompare(b.key));
+}
+
+/**
+ * What the work above the table cost, by class: { classKey: { cost, atNormal, costed, runs } }. `atNormal` is the
+ * same tokens at NORMAL_TIER's list price: what that model would have cost had it used as many, which no record
+ * can say it would have. As with `classCosts`, only priced calls are in the sums.
+ * @param priceOf  (agentId) => { cost, atNormal } in USD, or null
+ */
+export function aboveCosts(above, priceOf) {
+  const out = {};
+  for (const c of above) {
+    const o = (out[c.key] = { cost: 0, atNormal: 0, costed: 0, runs: c.ids.length });
+    for (const id of c.ids) {
+      const p = priceOf(id);
+      if (typeof p?.cost !== 'number' || typeof p?.atNormal !== 'number') continue;
+      o.cost += p.cost; o.atNormal += p.atNormal; o.costed += 1;
+    }
   }
   return out;
 }
@@ -210,16 +315,18 @@ function readBounded(file) {
 
 const sigOf = (file) => { try { const st = fs.statSync(file); return `${st.mtimeMs}:${st.size}`; } catch { return '-'; } };
 const FILES = ['model-outcomes.tsv', 'crew-model-floors.auto', 'crew-model-loosened.tsv'];
+const RULES = (cwd) => path.join(cwd, '.claude', 'crew-model-rules');   // the project's own, beside the state
 const records = new Map();           // cwd -> { sig, value }
 export const _stats = { parsed: 0 };  // how many times a record was really read: the claims count it
 
 /**
- * The record of one project, read once and kept until one of its three files changes (its time or its size).
+ * The record of one project, read once and kept until one of its files, or the project's rules, changes (its
+ * time or its size).
  * A view that asks every few seconds costs three stats, not a parse.
  */
 export function readRecord(cwd) {
   const dir = stateDir(cwd);
-  const sig = FILES.map((f) => sigOf(path.join(dir, f))).join('|');
+  const sig = [...FILES.map((f) => sigOf(path.join(dir, f))), sigOf(RULES(cwd))].join('|');
   const hit = records.get(cwd);
   if (hit && hit.sig === sig) return hit.value;
   const value = parseRecord(dir, cwd);
@@ -231,10 +338,11 @@ export function readRecord(cwd) {
 
 function parseRecord(dir, cwd) {
   const record = readBounded(path.join(dir, FILES[0]));
-  if (!record) return { measured: false, reason: 'no .claude/state/model-outcomes.tsv in this project: no crew agent has finished here since model routing was installed', classes: [], suggestions: [], byAgent: {} };
+  if (!record) return { measured: false, reason: 'no .claude/state/model-outcomes.tsv in this project: no crew agent has finished here since model routing was installed', classes: [], suggestions: [], above: [], byAgent: {} };
   const parsed = parseOutcomes(record.text);
   const floors = parseFloors(readBounded(path.join(dir, FILES[1]))?.text ?? '');
   const loosened = parseLoosened(readBounded(path.join(dir, FILES[2]))?.text ?? '');
+  const ruleFloors = parseRuleFloors(readBounded(RULES(cwd))?.text ?? '');
   const byAgent = {};
   for (const r of parsed.rows) byAgent[r.agentId] = r;           // a resumed agent's latest line is the one that stands
   // A card that failed is given again one model up, to another agent: the calls of one card, oldest first, are
@@ -258,6 +366,7 @@ function parseRecord(dir, cwd) {
     classes: classesOf(parsed.rows, floors, loosened),
     floors,
     suggestions: suggestionsOf(parsed.rows, floors, loosened),
+    above: aboveTableOf(parsed.rows, ruleFloors, floors),
     loosened,
     byAgent,
     all: parsed.rows,
@@ -276,12 +385,18 @@ export function readModels(cwd, { agents = null } = {}) {
   if (!rec.measured) return rec;
   const byAgent = {};
   for (const id of agents ?? []) if (Object.hasOwn(rec.byAgent, id)) byAgent[id] = rec.byAgent[id];
-  const { all, byAgent: _every, ...rest } = rec;
-  return { ...rest, byAgent };
+  const { all, byAgent: _every, above, ...rest } = rec;
+  return { ...rest, above: above.map(({ ids, ...c }) => c), byAgent };
 }
 
 /** What the classes of one project cost, from the kept record: see `classCosts`. Null when there is no record. */
-export function readCosts(cwd, costOf) {
+export function readCosts(cwd, costOf, advisorOf) {
+  const rec = readRecord(cwd);
+  return rec.measured ? classCosts(rec.all, costOf, advisorOf) : null;
+}
+
+/** What the work above the table cost, from the kept record: see `aboveCosts`. Null when there is no record. */
+export function readAboveCosts(cwd, priceOf) {
   const rec = readRecord(cwd);
-  return rec.measured ? classCosts(rec.all, costOf) : null;
+  return rec.measured ? aboveCosts(rec.above, priceOf) : null;
 }

package/kit/studio/server/lib/owned-stream.js

@@ -0,0 +1,56 @@
+// owned-stream.js — the conversations of several owned sessions, replayed then followed, on ONE connection.
+//
+// A browser holds six connections to one host over HTTP/1.1, and a pane per stream reached them at five panes
+// beside the page's own: the panel kept painting, but a message sent and every request the page made itself waited
+// until a pane was closed (measured on Windows, Claude Code 2.1.301: a send did not arrive in 35 s, then in 8 s once
+// two panes closed). Each event and state carries the session id it belongs to.
+//   ids=a,b,c          the sessions (at most MAX_STREAM_IDS; an unknown id is answered with `gone`)
+//   after=a:12,b:3     resume each where the client last was, so a reconnect neither replays nor drops
+
+export const MAX_STREAM_IDS = 32;
+
+/** Read `ids` and `after` from a URL: the ids, de-duplicated and capped, and each one's resume point. */
+export function parseOwnedQuery(url) {
+  const ids = [...new Set((url.searchParams.get('ids') ?? '').split(',').filter(Boolean))].slice(0, MAX_STREAM_IDS);
+  const after = new Map();
+  for (const part of (url.searchParams.get('after') ?? '').split(',')) {
+    const at = part.lastIndexOf(':');
+    if (at > 0) after.set(part.slice(0, at), Number(part.slice(at + 1)) || 0);
+  }
+  return { ids, after };
+}
+
+/**
+ * @param getSession  id -> an owned session ({ summary(), subscribe(fn, after) }) or null
+ * @param stateAfter  the record types after which a session's summary is sent again
+ * @param beatMs      how often every summary is sent regardless
+ */
+export function streamOwned(req, res, url, { getSession, stateAfter = new Set(), beatMs = 15000 }) {
+  const { ids, after } = parseOwnedQuery(url);
+  res.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-store',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+  });
+  const write = (event, data) => {
+    try { res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); } catch { /* client gone */ }
+  };
+  const unsubscribes = [];
+  for (const id of ids) {
+    const s = getSession(id);
+    if (!s) { write('gone', { id }); continue; }
+    write('state', { id, session: s.summary() });
+    unsubscribes.push(s.subscribe((ev) => {
+      write('event', { id, ev });
+      if (stateAfter.has(ev.rec?.type)) write('state', { id, session: s.summary() });
+    }, after.get(id) ?? 0));
+  }
+  const beat = setInterval(() => {
+    for (const id of ids) { const s = getSession(id); if (s) write('state', { id, session: s.summary() }); }
+  }, beatMs);
+  const stop = () => { clearInterval(beat); for (const u of unsubscribes) u(); try { res.end(); } catch { /* gone */ } };
+  req.on('close', stop);
+  req.on('error', stop);
+  return stop;
+}

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

@@ -36,6 +36,9 @@ export const PRICES = {
   'claude-haiku-4-5': { input: 1, output: 5 },
 };
 
+// The model the table's normal tier is priced at, for the Models view's "the same tokens on the table's model".
+export const NORMAL_TIER_MODEL = 'claude-sonnet-5-5';
+
 /** The row for a model id, or null. A dated snapshot (`<id>-20260101`) is the same model; nothing else matches. */
 export function priceOf(model) {
   if (typeof model !== 'string') return null;

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

@@ -24,10 +24,17 @@ import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-// Overridable so a second instance can be pointed at a different transcript
-// store — which is also the only way to exercise the peer relay on one machine.
-export const PROJECTS_ROOT = process.env.CREW_STUDIO_PROJECTS_ROOT
-  || path.join(os.homedir(), '.claude', 'projects');
+// Where Claude Code writes its transcripts: <config dir>/projects, the config dir being CLAUDE_CONFIG_DIR when it is
+// set and ~/.claude otherwise. Reading ~/.claude alone, sessions started under a moved config dir (Studio's own
+// included) were not listed and read a cost of 0 (measured on Windows). The studio gate hook reads it the same way.
+// CREW_STUDIO_PROJECTS_ROOT still wins: a second instance pointed at a different store, which is also the only way to
+// exercise the peer relay on one machine.
+export function projectsRoot(env = process.env, home = os.homedir()) {
+  if (env.CREW_STUDIO_PROJECTS_ROOT) return env.CREW_STUDIO_PROJECTS_ROOT;
+  const config = env.CLAUDE_CONFIG_DIR ? path.resolve(env.CLAUDE_CONFIG_DIR) : path.join(home, '.claude');
+  return path.join(config, 'projects');
+}
+export const PROJECTS_ROOT = projectsRoot();
 
 /** Fold a working directory into the directory name Claude Code uses. */
 export function encodeCwd(cwd) {

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