crewforth 3.1.1 → 3.2.0-rc.10

package/kit/studio/server/index.js

@@ -21,25 +21,34 @@ import { projectDir, listSessions, findSession, listProjects, sessionCwd, agentM
 import { agentOrigins } from './lib/agent-origin.js';
 import { buildGraph, agentDetail, conversation, STALE_MS } from './lib/graph.js';
 import { cachedUsage } from './lib/usage.js';
-import { readModels, readRecord, readCosts } from './lib/model-outcomes.js';
+import { streamOwned } from './lib/owned-stream.js';
+import { stampAtStart } from './lib/code-stamp.js';
+import { readModels, readRecord, readCosts, readAboveCosts } from './lib/model-outcomes.js';
+import { readMap, behindOf, compareMaps, mapSummary, MAP_FILE } from './lib/crew-map.js';
 
 const USAGE_BATCH = 12;
 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, 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';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const WEB_ROOT = path.resolve(HERE, '..', 'web');
+// The server's own code as it was when it started: an update on disk since then is said to the page (code-stamp.js).
+const codeChanged = stampAtStart(HERE);
 const LOOPBACK = '127.0.0.1';
 
 const MIME = {
@@ -92,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',
   });
 }
@@ -108,15 +121,35 @@ 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, 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.
 let PEERS = [];
 let SELF_NAME = 'this machine';
 
-function authorised(req, url) {
+/**
+ * Whose request this is: the owner's, a read-only viewer's (lib/remote.js), or nobody's.
+ * The token is read from the same two places for both, so a viewer's link works exactly as the owner's does.
+ */
+function whoAsks(req, url) {
   const header = req.headers['authorization'];
-  if (header === `Bearer ${TOKEN}`) return true;
-  return url.searchParams.get('token') === TOKEN;
+  const bearer = typeof header === 'string' && header.startsWith('Bearer ') ? header.slice(7) : null;
+  const given = [bearer, url.searchParams.get('token')].filter(Boolean);
+  // 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;
 }
 
 /**
@@ -167,10 +200,16 @@ async function modelCosts(cwd) {
     for (const s of (await listSessions(dir)).filter((x) => x.modifiedAt >= since).slice(0, MODELS_SESSIONS_MAX)) {
       const u = await cachedUsage(s);
       read += 1;
-      for (const [id, a] of Object.entries(u.agents ?? {})) per.set(id, a.cost);
+      for (const [id, a] of Object.entries(u.agents ?? {})) per.set(id, a);
     }
   }
-  return { measured: true, costs: readCosts(cwd, (id) => (per.has(id) ? per.get(id) : null)), sessionsRead: read };
+  return {
+    measured: true,
+    costs: readCosts(cwd, (id) => per.get(id)?.cost ?? null,
+      (id) => (per.get(id)?.advisorCalls ? { calls: per.get(id).advisorCalls, cost: per.get(id).advisorCost } : null)),
+    above: readAboveCosts(cwd, (id) => (per.has(id) ? { cost: per.get(id).cost, atNormal: per.get(id).costAtNormal } : null)),
+    sessionsRead: read,
+  };
 }
 const MODELS_SESSIONS_MAX = 60;
 
@@ -214,23 +253,52 @@ async function serveStatic(res, urlPath) {
   }
 }
 
-async function handle(req, res) {
+export async function handle(req, res) {
   const url = new URL(req.url, `http://${LOOPBACK}`);
 
   // The token guards data and actions, not the app shell. A browser does not
   // carry the page's query string into its sub-resource requests, so demanding
   // it for /style.css served an unstyled page and protected nothing: the shell
   // holds no secrets, and every /api/ path below is still gated.
-  if (url.pathname.startsWith('/api/') && !authorised(req, url)) {
-    return sendJson(res, 403, { ok: false, reason: 'token required' });
+  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) {
+    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. 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) { 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);
   }
 
   if (url.pathname === '/api/health') {
     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),
+      // `changed`: the server's files on disk are not the ones it started with. A page that finds no `code` at all
+      // is talking to a server older than this field, which is the same thing.
+      code: codeChanged(),
     });
   }
 
@@ -288,7 +356,12 @@ async function handle(req, res) {
     // dead time whenever the feed hung, measured. The refresh runs behind this response.
     const latest = latestVersionCached();
     const projects = await listProjects({ currentCwd: cwd, kitOf: (c) => kitStatus(c, latest) });
-    for (const p of projects) { p.origin = SELF_NAME; p.local = true; }
+    for (const p of projects) {
+      p.origin = SELF_NAME; p.local = true;
+      // The navigator's Map entry and its count: the findings the map shows unasked. A stat per project; the map
+      // is parsed again only when its file changes (crew-map.js).
+      p.map = p.exists && p.cwd ? mapSummary(p.cwd) : null;
+    }
 
     const origins = [{ name: SELF_NAME, local: true, ok: true, projects: projects.length }];
     if (PEERS.length) {
@@ -339,7 +412,7 @@ async function handle(req, res) {
     const sid = url.searchParams.get('session');
     const session = sid ? await findSession(sid) : null;
     const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
-    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', classes: [], suggestions: [], byAgent: {} });
+    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', classes: [], suggestions: [], above: [], byAgent: {} });
     return sendJson(res, 200, readModels(cwd, { agents: await agentIdsOf(session) }));
   }
 
@@ -347,10 +420,29 @@ async function handle(req, res) {
     const sid = url.searchParams.get('session');
     const session = sid ? await findSession(sid) : null;
     const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
-    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', costs: {}, sessionsRead: 0 });
+    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', costs: {}, above: {}, sessionsRead: 0 });
     return sendJson(res, 200, await modelCosts(cwd));
   }
 
+  // The project's crew map, as Crewforth's scanner wrote it, and how far HEAD has moved since. Nothing is scanned here.
+  // `compare` names another project of this machine by its directory; only a project the panel lists, with a map
+  // of its own, is read, so the route cannot be pointed at an arbitrary path.
+  if (url.pathname === '/api/map') {
+    const sid = url.searchParams.get('session');
+    const session = sid ? await findSession(sid) : null;
+    const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
+    if (!cwd) return sendJson(res, 200, { measured: false, reason: 'no project named', others: [] });
+    const map = readMap(cwd);
+    const others = (await listProjects({ currentCwd: cwd })).filter((p) => p.cwd && p.cwd !== cwd && readMap(p.cwd).measured)
+      .map((p) => ({ label: p.label, cwd: p.cwd }));
+    if (!map.measured) return sendJson(res, 200, { ...map, cwd, others });
+    const asked = url.searchParams.get('compare');
+    const peer = asked ? others.find((o) => o.cwd === asked) : null;
+    const compare = peer ? { label: peer.label, cwd: peer.cwd, clients: compareMaps(map.doc, readMap(peer.cwd).doc) }
+      : asked ? { label: null, cwd: asked, clients: [], reason: 'not a project of this machine with a crew map' } : null;
+    return sendJson(res, 200, { ...map, cwd, behind: await behindOf(cwd, map.doc.source?.commit), others, compare });
+  }
+
   if (url.pathname === '/api/kit') {
     const cwd = url.searchParams.get('cwd') || process.cwd();
     const sid = url.searchParams.get('session');
@@ -441,8 +533,12 @@ 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);
@@ -454,7 +550,6 @@ 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);
   }
@@ -463,6 +558,36 @@ async function handle(req, res) {
     return stream(req, res, url);
   }
 
+  /* --------------------------------------------------------- remote ---
+     Read-only viewers: who holds a link, and the way to take it back. Only
+     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, 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(?:\/([^/]+))?$/);
+  if (remoteMatch) {
+    const gate = writeAllowed(req);
+    if (!gate.ok) return sendJson(res, 403, { ok: false, reason: gate.reason });
+    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, { 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]) {
+      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' });
+  }
+
   /* ---------------------------------------------------------- owned ---
      Sessions the panel started. Their transcripts land in the usual place,
      so the graph endpoints already cover them; only the conversation needs
@@ -525,6 +650,10 @@ async function handle(req, res) {
     return sendJson(res, out.ok ? 200 : 400, out);
   }
 
+  // Every open conversation on ONE connection (lib/owned-stream.js). Reading, so it sits beside /events, not
+  // behind the write gate.
+  if (url.pathname === '/api/owned-events') return streamOwned(req, res, url, { getSession, stateAfter: STATE_AFTER });
+
   const ownedMatch = url.pathname.match(/^\/api\/owned\/([^/]+)(?:\/(message|stop|events|mode))?$/);
   if (ownedMatch) {
     const s = getSession(decodeURIComponent(ownedMatch[1]));
@@ -655,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
@@ -830,6 +959,28 @@ async function selftest() {
     fleet.measured ? `${fleet.sessions.length} session(s)` : `not measured: ${fleet.reason}`,
   );
 
+  // The Map view: its files are installed, and the reader takes a crew map and refuses one of another schema. On a
+  // scratch map of its own, so the verdict does not depend on whether this project has one; this project's own map,
+  // when there is one, is reported beside it.
+  check('map view installed', ['map.js', 'map-plan.js', 'viewport.js'].every((f) => fs.existsSync(path.join(WEB_ROOT, f))), null);
+  {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'crew-studio-map-'));
+    try {
+      fs.mkdirSync(path.join(dir, '.crewforth'));
+      const doc = { schema: 'crewforth.crew-map/1', nodes: [{ id: 'mod:x:a', kind: 'module', name: 'a' }], edges: [], findings: [], notMeasured: [] };
+      fs.writeFileSync(path.join(dir, MAP_FILE), JSON.stringify(doc));
+      const read = readMap(dir);
+      // A different size, not only a different schema: the reader caches on mtime and size, and on Windows both writes
+      // land on one timestamp, so a same-size rewrite read back the first map (seen on a CI runner).
+      fs.writeFileSync(path.join(dir, MAP_FILE), JSON.stringify({ ...doc, schema: 'crewforth.crew-map/99' }));
+      const other = readMap(dir);
+      check('map read', read.measured === true && read.doc.nodes.length === 1 && other.measured === false,
+        read.measured ? `a scratch map read; one of another schema refused (${other.reason ?? 'read'})` : read.reason);
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+    const own = readMap(process.cwd());
+    process.stdout.write(`INFO this project's map — ${own.measured ? `${own.doc.nodes.length} node(s), ${own.doc.findings.length} finding(s)` : own.reason}\n`);
+  }
+
   const cost = await measureSpawnCost(3);
   if (cost === null) skip('spawn cost measured', 'claude CLI absent');
   else check('spawn cost measured', true, `min ${cost.minMs}ms · median ${cost.medianMs}ms · max ${cost.maxMs}ms`);
@@ -877,6 +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 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' +
@@ -893,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,
@@ -979,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/code-stamp.js

@@ -0,0 +1,35 @@
+// code-stamp.js — is the code this server runs still the code on disk?
+//
+// A server keeps the code it started with. An update replaces the files on disk, the page is served fresh from
+// them, and the two disagree: measured in a real project, a server started before 3.2.0 answered the new Map
+// view's /api/map with 404, which the view showed as "Not read — HTTP 404". The stamp is the size and mtime of
+// every file of the server, taken at start and again when asked; when they differ, the page says to restart.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Size and mtime of every .js/.mjs/.sh file under `dir` (the server's own code), as one string. */
+export function codeStamp(dir) {
+  const parts = [];
+  const walk = (d) => {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) { if (e.name !== 'node_modules') walk(p); continue; }
+      if (!/\.(m?js|sh)$/.test(e.name)) continue;
+      try { const st = fs.statSync(p); parts.push(`${path.relative(dir, p)}:${st.size}:${Math.round(st.mtimeMs)}`); } catch { /* gone */ }
+    }
+  };
+  walk(dir);
+  return parts.join('|');
+}
+
+/** Stamp the code now, and answer later whether it has changed on disk (re-read at most every `everyMs`). */
+export function stampAtStart(dir, { everyMs = 5000, now = () => Date.now() } = {}) {
+  const boot = codeStamp(dir);
+  let last = boot; let at = now();
+  return () => {
+    if (now() - at >= everyMs) { last = codeStamp(dir); at = now(); }
+    return { changed: last !== boot };
+  };
+}

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/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