crewforth 3.1.0 → 3.2.0-rc.1

package/kit/studio/server/lib/crew-map.js

@@ -0,0 +1,113 @@
+// What Crewforth's crew map says about a project, for the Map view.
+//
+// The map is `.crewforth/crew-map.json`, written by Crewforth's scanner (kit/eval/lib/crew-map/scan.mjs): the
+// project's modules, the external resources it touches, the endpoints it provides and calls, and the findings
+// between them, every one citing file:line. This file reads it and runs nothing that writes: no scan is started
+// from here, and a map that is not on disk is said to be missing. The one process it starts is `git rev-list
+// --count`, to say how far the project has moved since the commit the map was scanned at.
+//
+// Compare with: another project's map is read the same way. The scanner already says which of a project's calls
+// no endpoint in that project provides (they go somewhere else); those are the calls compared here. One the other
+// project provides is a match, one it does not is missing.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+
+export const MAP_FILE = path.join('.crewforth', 'crew-map.json');
+// How a project writes its map, said wherever a map is missing. The one place it is written: the view and the
+// page show what the server sends.
+// /crew-map in Claude Code: the scan, then the descriptions, in either edition (the plugin has no .claude/eval).
+export const WRITER = '/crew-map in Claude Code';
+export const SCHEMA = /^crewforth\.crew-map\/1$/;
+const MAX_BYTES = 8 * 1024 * 1024;
+const GIT_TIMEOUT_MS = 5000;
+
+const maps = new Map();               // cwd -> { sig, value }
+export const _stats = { parsed: 0 };  // how many times a map was really read: the claims count it
+
+/**
+ * The map of one project, read once and kept until the file changes (its time or its size).
+ * @returns { measured: true, file, bytes, doc } or { measured: false, reason }
+ */
+export function readMap(cwd) {
+  const file = path.join(cwd, MAP_FILE);
+  let st;
+  try { st = fs.statSync(file); } catch {
+    return { measured: false, missing: true, reason: `no ${MAP_FILE.replaceAll('\\', '/')} in this project. Write one there with: ${WRITER}` };
+  }
+  const sig = `${st.mtimeMs}:${st.size}`;
+  const hit = maps.get(cwd);
+  if (hit && hit.sig === sig) return hit.value;
+  const value = parseMap(file, st.size);
+  _stats.parsed += 1;
+  if (maps.size > 50) maps.clear();
+  maps.set(cwd, { sig, value });
+  return value;
+}
+
+function parseMap(file, size) {
+  const shown = MAP_FILE.replaceAll('\\', '/');
+  // Read whole or not at all: half a map would draw modules without the edges that belong to them.
+  if (size > MAX_BYTES) return { measured: false, reason: `${shown} is ${size} bytes, over the ${MAX_BYTES} Studio reads` };
+  let doc;
+  try { doc = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { return { measured: false, reason: `${shown} is not JSON (${e.message.slice(0, 80)})` }; }
+  if (!SCHEMA.test(String(doc?.schema))) return { measured: false, reason: `${shown} says schema ${JSON.stringify(doc?.schema ?? null)}, and Studio reads crewforth.crew-map/1` };
+  for (const k of ['nodes', 'edges', 'findings', 'notMeasured']) {
+    if (!Array.isArray(doc[k])) return { measured: false, reason: `${shown} has no ${k} list` };
+  }
+  return { measured: true, file: shown, bytes: size, doc };
+}
+
+/** What the navigator says of a project's map: null with none, else how many findings it shows unasked. */
+export function mapSummary(cwd) {
+  const m = readMap(cwd);
+  if (!m.measured) return m.missing ? null : { findings: null, reason: m.reason };
+  return { findings: m.doc.findings.filter((f) => !f?.data?.defaultHidden).length };
+}
+
+/**
+ * How many commits HEAD is past the commit the map was scanned at: { count } or { count: null, reason }.
+ * Only a commit id is handed to git, so nothing in the file can become an option.
+ */
+export function behindOf(cwd, commit) {
+  if (typeof commit !== 'string' || !/^[0-9a-f]{7,64}$/.test(commit)) return Promise.resolve({ count: null, reason: 'the map names no commit' });
+  return new Promise((resolve) => {
+    execFile('git', ['rev-list', '--count', `${commit}..HEAD`], { cwd, timeout: GIT_TIMEOUT_MS, windowsHide: true }, (err, stdout) => {
+      const n = Number.parseInt(String(stdout).trim(), 10);
+      if (err || !Number.isFinite(n)) resolve({ count: null, reason: 'git could not say (the commit may not be in this clone)' });
+      else resolve({ count: n });
+    });
+  });
+}
+
+/** One endpoint as it is matched: the method, and the path with each parameter written as one `*`. */
+export function endpointKey(e) {
+  const p = String(e?.path ?? '').split('?')[0].replace(/\/+$/, '') || '/';
+  const segs = p.split('/').map((s) => (/^(:\w+|\{[^}]*\}|<[^>]*>|\*)$/.test(s) ? '*' : s));
+  return `${String(e?.method ?? '').toUpperCase()} ${segs.join('/')}`;
+}
+
+/**
+ * Another project's calls into this one. `doc` is this project's map, `other` the other project's. A call of the
+ * other project is compared when no endpoint of its own provides it (the scanner's own endpoint-missing). Each
+ * calling module of the other project is one client: what it calls here that this project provides (`calls`,
+ * each with `to`, the module of this project that provides it),
+ * and what else it calls that its own project does not provide either (`missing`). A module none of whose calls
+ * this project provides is not a client of it, and is not listed: its calls go to a third place, and naming them
+ * missing here would say something the two maps do not.
+ */
+export function compareMaps(doc, other) {
+  const own = new Set((other?.provides?.endpoints ?? []).map(endpointKey));
+  const here = new Map((doc?.provides?.endpoints ?? []).map((e) => [endpointKey(e), e.module]));
+  const names = new Map((other?.nodes ?? []).filter((n) => n.kind === 'module').map((n) => [n.id, n]));
+  const by = new Map();
+  for (const e of other?.consumes?.endpoints ?? []) {
+    const k = endpointKey(e);
+    if (own.has(k)) continue;
+    const c = by.get(e.module) ?? by.set(e.module, { id: e.module, name: names.get(e.module)?.name ?? e.module, tech: names.get(e.module)?.tech ?? [], calls: [], missing: [] }).get(e.module);
+    const call = { method: e.method, path: e.path, evidence: (e.evidence ?? []).slice(0, 1) };
+    if (here.has(k)) c.calls.push({ ...call, to: here.get(k) }); else c.missing.push(call);
+  }
+  return [...by.values()].filter((c) => c.calls.length).sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

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/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/remote.js

@@ -0,0 +1,99 @@
+// 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 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.
+//
+// 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.
+import { randomUUID } from 'node:crypto';
+
+export const MAX_VIEWERS = 8;
+const LABEL_MAX = 40;
+
+const viewers = new Map();          // id -> viewer
+const byToken = new Map();          // token -> viewer
+
+const publicOf = (v) => ({
+  id: v.id,
+  label: v.label,
+  createdAt: v.createdAt,
+  lastSeenAt: v.lastSeenAt,
+  requests: v.requests,
+  agent: v.agent,
+  open: v.conns.size,
+});
+
+/** Make a viewer. The token is in this answer and in no later one. */
+export function addViewer(label) {
+  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 v = {
+    id: randomUUID().slice(0, 8),
+    label: named || `Viewer ${viewers.size + 1}`,
+    token: randomUUID(),
+    createdAt: Date.now(),
+    lastSeenAt: null,
+    requests: 0,
+    agent: null,
+    conns: new Set(),
+  };
+  viewers.set(v.id, v);
+  byToken.set(v.token, v);
+  return { ok: true, viewer: { ...publicOf(v), token: v.token } };
+}
+
+export function listViewers() {
+  return [...viewers.values()].map(publicOf);
+}
+
+export function viewerByToken(token) {
+  return (typeof token === 'string' && byToken.get(token)) || null;
+}
+
+/**
+ * Take a viewer's access back. Its token stops working with this call, and a stream it holds open is closed:
+ * a revoke that left the live graph running on the phone would be a revoke in name only.
+ */
+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();
+  return { ok: true, revoked: true };
+}
+
+/** Count a viewer's request and remember its response for as long as it is open. */
+export function noteRequest(v, req, res) {
+  v.requests += 1;
+  v.lastSeenAt = Date.now();
+  const ua = req.headers['user-agent'];
+  v.agent = typeof ua === 'string' ? ua.slice(0, 160) : null;
+  v.conns.add(res);
+  res.on('close', () => v.conns.delete(res));
+}
+
+/**
+ * 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.
+ */
+export function viewerMay(method, pathname) {
+  if (method !== 'GET') return { ok: false, reason: 'read-only token: GET only' };
+  if (pathname === '/api/remote' || pathname.startsWith('/api/remote/')) {
+    return { ok: false, reason: 'read-only token: viewers are managed from the machine itself' };
+  }
+  return { ok: true };
+}
+
+/** For the self-check: start from nothing. */
+export function _reset() {
+  for (const id of [...viewers.keys()]) revokeViewer(id);
+}

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

@@ -4,25 +4,41 @@
 // usage. Measured on one machine before this was written: 23,867 assistant records carried usage, for 11,245
 // responses, and every repeat carried the same numbers. So a response is counted once, by its message id — and
 // once across the session's files too, which is what keeps an agent's tokens from being added twice.
+//
+// An advisor call (the advisor tool: the model consults a second one mid-response) is not in that usage. The API
+// keeps it out of the top-level fields, which are the executor's, and lists it in `usage.iterations[]` as an
+// `advisor_message` entry with its own `model`. It is billed at that model's rates, so it is priced on its own.
+// Measured on a real advisor session: the entry is written to the transcript, and repeated, like the rest of the
+// usage, on every record of the response; the message id above counts it once.
 
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 
 import { readAll } from './transcript.js';
 import { agentMetaFiles } from './projects.js';
-import { costOf, SOURCE } from './pricing.js';
+import { costOf, SOURCE, NORMAL_TIER_MODEL } from './pricing.js';
 
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
 
+/**
+ * A usage's cache writes by kind. A write the split does not account for is the 5-minute kind: that is the default,
+ * and the cheaper of the two. The split can fall short of the total: measured on a real response, the split said
+ * 12,400 one-hour and 0 five-minute against a total of 12,670, and the 270 missing were billed as five-minute
+ * writes (its iterations listed them so, and Claude Code's own cost for the session matched only with them in).
+ */
+function writesOf(u) {
+  const split = u.cache_creation && typeof u.cache_creation === 'object' ? u.cache_creation : null;
+  const w1h = num(split?.ephemeral_1h_input_tokens);
+  const w5m = num(split?.ephemeral_5m_input_tokens);
+  return { cacheWrite5m: w5m + Math.max(0, num(u.cache_creation_input_tokens) - w5m - w1h), cacheWrite1h: w1h };
+}
+
 /** One response's usage, in the shape pricing.js prices. Null when the record carries none. */
 export function usageOfRecord(r) {
   const m = r?.type === 'assistant' ? r.message : null;
   const u = m?.usage;
   if (!u || typeof u !== 'object') return null;
-  const split = u.cache_creation && typeof u.cache_creation === 'object' ? u.cache_creation : null;
-  const w1h = num(split?.ephemeral_1h_input_tokens);
-  // With no split recorded, a cache write is the 5-minute kind: that is the default, and the cheaper of the two.
-  const w5m = split ? num(split.ephemeral_5m_input_tokens) : num(u.cache_creation_input_tokens);
+  const { cacheWrite5m: w5m, cacheWrite1h: w1h } = writesOf(u);
   return {
     id: typeof m.id === 'string' ? m.id : null,
     model: typeof m.model === 'string' ? m.model : null,
@@ -33,9 +49,28 @@ export function usageOfRecord(r) {
     cacheRead: num(u.cache_read_input_tokens),
     fast: u.speed === 'fast',
     usOnly: u.inference_geo === 'us',
+    advisor: advisorCallsOf(u),
   };
 }
 
+/** The advisor calls one response's usage lists, each in the shape pricing.js prices: [] when it made none. */
+export function advisorCallsOf(u) {
+  const out = [];
+  for (const it of Array.isArray(u?.iterations) ? u.iterations : []) {
+    if (it?.type !== 'advisor_message') continue;
+    out.push({
+      model: typeof it.model === 'string' ? it.model : null,
+      input: num(it.input_tokens),
+      output: num(it.output_tokens),
+      ...writesOf(it),
+      cacheRead: num(it.cache_read_input_tokens),
+      fast: false,
+      usOnly: u.inference_geo === 'us',
+    });
+  }
+  return out;
+}
+
 const KINDS = ['input', 'output', 'cacheWrite', 'cacheRead'];
 
 /** One running sum: tokens by kind, what they cost, and which models had no price. */
@@ -43,25 +78,29 @@ class Tally {
   constructor() {
     this.tokens = { input: 0, output: 0, cacheWrite: 0, cacheRead: 0 };
     this.usd = 0;
+    this.usdAtNormal = 0;     // the same tokens at NORMAL_TIER_MODEL's price
     this.responses = 0;
     this.unpriced = new Set();
   }
 
-  take(u, usd) {
-    this.responses += 1;
+  /** @param response  false for an advisor call: its tokens and cost are added, but it is part of a response, not one. */
+  take(u, usd, atNormal = null, response = true) {
+    if (response) this.responses += 1;
     this.tokens.input += u.input;
     this.tokens.output += u.output;
     this.tokens.cacheWrite += u.cacheWrite5m + u.cacheWrite1h;
     this.tokens.cacheRead += u.cacheRead;
     if (usd === null) this.unpriced.add(u.model ?? 'unknown model');
     else this.usd += usd;
+    if (atNormal !== null) this.usdAtNormal += atNormal;
   }
 
   /**
    * `fresh` is what was sent and written for the first time: input, output and cache writes. `cacheRead` is the
    * same context read back from the cache on every later response, which is why it dwarfs the rest in a long
    * session and is kept out of the headline. `cost` is null when any of the tokens came from a model the price
-   * table has no row for — a sum that leaves some of them out would read as the whole.
+   * table has no row for — a sum that leaves some of them out would read as the whole. `costAtNormal` is the same
+   * tokens at NORMAL_TIER_MODEL's list price, null under the same rule.
    */
   result() {
     const t = this.tokens;
@@ -69,6 +108,7 @@ class Tally {
       tokens: { ...t, fresh: t.input + t.output + t.cacheWrite, total: KINDS.reduce((a, k) => a + t[k], 0) },
       responses: this.responses,
       cost: this.unpriced.size ? null : this.usd,
+      costAtNormal: this.unpriced.size ? null : this.usdAtNormal,
       unpriced: [...this.unpriced].sort(),
     };
   }
@@ -80,6 +120,9 @@ export class Usage {
     this.all = new Tally();
     this.who = new Map();      // 'session', or an agent's id -> Tally
     this.model = new Map();    // model id -> Tally
+    this.advisor = new Tally(); // the advisor calls alone, one take per call
+    this.advisorModels = new Map(); // advisor model id -> Tally
+    this.advisorWho = new Map();    // 'session' or an agent's id -> Tally of its advisor calls alone
     this.first = null;         // the earliest and the latest record of any file added
     this.last = null;
   }
@@ -104,11 +147,22 @@ export class Usage {
       const u = usageOfRecord(r);
       if (!u) continue;
       if (u.id) { if (this.seen.has(u.id)) continue; this.seen.add(u.id); }
-      if (!(u.input + u.output + u.cacheWrite5m + u.cacheWrite1h + u.cacheRead)) continue;   // a record the harness made up carries no tokens
-      const usd = costOf(u);
-      this.all.take(u, usd);
-      this.#tally(this.who, who === 'session' && r.isSidechain === true ? 'agents:inline' : who).take(u, usd);
-      this.#tally(this.model, u.model ?? 'unknown model').take(u, usd);
+      if (!(u.input + u.output + u.cacheWrite5m + u.cacheWrite1h + u.cacheRead) && !u.advisor.length) continue;   // a record the harness made up carries no tokens
+      const mine = this.#tally(this.who, who === 'session' && r.isSidechain === true ? 'agents:inline' : who);
+      // The response, then each advisor call it made, priced at the advisor's own model.
+      for (const x of [u, ...u.advisor]) {
+        const usd = costOf(x);
+        const atNormal = costOf({ ...x, model: NORMAL_TIER_MODEL });
+        const own = x === u;
+        this.all.take(x, usd, atNormal, own);
+        mine.take(x, usd, atNormal, own);
+        this.#tally(this.model, x.model ?? 'unknown model').take(x, usd, atNormal, own);
+        if (!own) {   // here each call is one
+          this.advisor.take(x, usd, atNormal);
+          this.#tally(this.advisorWho, who === 'session' && r.isSidechain === true ? 'agents:inline' : who).take(x, usd, atNormal);
+          this.#tally(this.advisorModels, x.model ?? 'unknown model').take(x, usd, atNormal);
+        }
+      }
     }
     return this;
   }
@@ -134,6 +188,9 @@ export class Usage {
       ...all,
       models: [...this.model.keys()].filter((m) => !all.unpriced.includes(m)).sort(),
       parts: { session: (this.who.get('session') ?? new Tally()).result(), agents: agents.result() },
+      // Null when no advisor call is recorded: a session without one has no advisor line, not a zero.
+      advisor: this.advisor.responses ? { ...this.advisor.result(), calls: this.advisor.responses } : null,
+      advisorModels: Object.fromEntries([...this.advisorModels].map(([m, t]) => [m, { ...t.result(), calls: t.responses }])),
       byModel: Object.fromEntries([...this.model].map(([m, t]) => [m, t.result()]).sort((a, b) => b[1].tokens.total - a[1].tokens.total)),
       startedAt: this.first,
       lastAt: this.last,
@@ -192,7 +249,10 @@ export async function sessionUsage(session) {
   for (const [who, t] of usage.who) {
     if (who === 'session' || who.startsWith('agents:')) continue;
     const r = t.result();
-    agents[who] = { fresh: r.tokens.fresh, cacheRead: r.tokens.cacheRead, cost: r.cost };
+    // What of it was the advisor: its calls and their cost, already in `cost`. Zero calls when it consulted none.
+    const adv = usage.advisorWho.get(who)?.result() ?? null;
+    agents[who] = { fresh: r.tokens.fresh, cacheRead: r.tokens.cacheRead, cost: r.cost, costAtNormal: r.costAtNormal,
+      advisorCalls: adv?.responses ?? 0, advisorCost: adv?.cost ?? null };
   }
   return { ...withTimes(usage, records), agents };
 }