crewforth 3.2.0-rc.1 → 3.2.0-rc.3

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

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

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

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

package/kit/studio/README.md

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

package/kit/studio/server/index.js

@@ -21,6 +21,8 @@ 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 { 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';
 
@@ -29,19 +31,24 @@ import { palette } from './lib/palette.js';
 import { latestVersion, latestVersionCached, kitStatus } from './lib/kit.js';
 import { parsePeers, askAll, ask } from './lib/peers.js';
 import {
-  createSession, getSession, listSessionsOwned, reap, stopAll, dropSpools, ALLOWED_MODES,
+  createSession, getSession, listSessionsOwned, reap, stopAll, dropSpools, ALLOWED_MODES, isHeldOpen,
 } from './lib/session.js';
 import { decide, pending, alwaysList, revoke, sweepLeft } from './lib/permissions.js';
-import { open as openTerminal, plan as terminalPlan } from './lib/terminal.js';
+import { open as openTerminal, plan as terminalPlan, desktopLine } from './lib/terminal.js';
 import { gateLog, gateReport, sessionStats, board } from './lib/kit-telemetry.js';
 import { writeState, clearStateSync, findRunning } from './lib/instance.js';
 import { remoteRoster } from './lib/roster.js';
-import { addViewer, listViewers, viewerByToken, revokeViewer, noteRequest, viewerMay, MAX_VIEWERS } from './lib/remote.js';
+import { addViewer, listViewers, viewerByToken, revokeViewer, noteRequest, noteRefusal, viewerMay, MAX_VIEWERS, VIEWER_TTL_MS,
+  liveCount, remoteLog, sweep as sweepViewers, onViewersChange, onLog } from './lib/remote.js';
+import { redact, transcriptOnly } from './lib/redact.js';
+import { lanListener } from './lib/lan.js';
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 
 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 = {
@@ -94,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',
   });
 }
@@ -110,8 +121,12 @@ function sendJson(res, status, value) {
 const TOKEN = process.env.CREW_STUDIO_TOKEN || randomUUID();
 const TOKEN_GENERATED = !process.env.CREW_STUDIO_TOKEN;
 
+// The Wi-Fi listener (lib/lan.js): set by main() once the port is known, and opened and closed with the number of
+// live viewers. Null in the self-check unless it makes one.
+let LAN = null;
+
 /** For the self-check, which asks a real server as the owner and as a viewer. */
-export const _internals = { token: TOKEN };
+export const _internals = { token: TOKEN, setLan: (l) => { LAN = l; } };
 
 // Peers are other machines running Studio, reached over a forwarded port. This
 // server still listens on loopback only; a peer never widens that.
@@ -126,9 +141,12 @@ function whoAsks(req, url) {
   const header = req.headers['authorization'];
   const bearer = typeof header === 'string' && header.startsWith('Bearer ') ? header.slice(7) : null;
   const given = [bearer, url.searchParams.get('token')].filter(Boolean);
-  if (given.includes(TOKEN)) return { role: 'owner' };
+  // The panel's own token is accepted on loopback only. From the Wi-Fi it is not a token at all: a phone holding it
+  // would hold the panel, and nothing on the network should.
+  if (!req.crewLan && given.includes(TOKEN)) return { role: 'owner' };
   for (const t of given) {
     const viewer = viewerByToken(t);
+    if (viewer?.expired) return { role: 'expired', label: viewer.expired };
     if (viewer) return { role: 'viewer', viewer };
   }
   return null;
@@ -243,14 +261,30 @@ export async function handle(req, res) {
   // it for /style.css served an unstyled page and protected nothing: the shell
   // holds no secrets, and every /api/ path below is still gated.
   const who = url.pathname.startsWith('/api/') ? whoAsks(req, url) : null;
+  // From the Wi-Fi, no token (or the panel's own) is 401: the network is asked who it is. On loopback the answer
+  // stays 403, as it always was.
   if (url.pathname.startsWith('/api/') && !who) {
-    return sendJson(res, 403, { ok: false, reason: 'token required' });
+    if (req.crewLan) noteRefusal(req, { status: 401, reason: 'no viewer token' });
+    return sendJson(res, req.crewLan ? 401 : 403, { ok: false, reason: 'token required' });
+  }
+  if (who?.role === 'expired') {
+    noteRefusal(req, { viewer: who.label, status: 401, reason: 'expired' });
+    return sendJson(res, 401, { ok: false, expired: true, reason: 'this link has expired: viewer links last eight hours' });
   }
   // A viewer is refused HERE, before any handler: no route below has to remember that a viewer exists, and a
-  // route added tomorrow is read-only for a viewer without anyone writing a line for it.
+  // route added tomorrow is read-only for a viewer without anyone writing a line for it. The same holds for a
+  // link that hides transcripts: the routes that are nothing but transcript are refused here, and every other
+  // answer is filtered on its way out (REDACTED).
   if (who?.role === 'viewer') {
     const may = viewerMay(req.method, url.pathname);
-    if (!may.ok) return sendJson(res, 403, { ok: false, reason: may.reason });
+    if (!may.ok) { noteRefusal(req, { viewer: who.viewer.label, status: 403, reason: may.reason }); return sendJson(res, 403, { ok: false, reason: may.reason }); }
+    if (!who.viewer.transcripts) {
+      if (transcriptOnly(url.pathname)) {
+        noteRefusal(req, { viewer: who.viewer.label, status: 403, reason: 'transcripts hidden' });
+        return sendJson(res, 403, { ok: false, transcriptsHidden: true, reason: 'transcripts are hidden on this link' });
+      }
+      REDACTED.add(res);
+    }
     noteRequest(who.viewer, req, res);
   }
 
@@ -258,9 +292,13 @@ export async function handle(req, res) {
     return sendJson(res, 200, {
       ok: true,
       role: who.role,
+      ...(who.role === 'viewer' ? { transcripts: who.viewer.transcripts, expiresAt: who.viewer.expiresAt } : {}),
       node: process.version,
       pid: process.pid,
       uptimeMs: Math.round(process.uptime() * 1000),
+      // `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(),
     });
   }
 
@@ -495,8 +533,12 @@ export async function handle(req, res) {
     const cwd = url.searchParams.get('cwd') || (session ? await sessionCwd(session.file, session.bytes) : null);
 
     if (req.method === 'GET') {
-      // What WOULD run, so the panel can show it before anything is launched.
-      return sendJson(res, 200, { measured: true, cwd, plan: cwd ? terminalPlan({ cwd, sessionId: id }) : null });
+      // What WOULD run, so the panel can show it before anything is launched; and, before Continue here is pressed,
+      // what it will do: continue this same session (nothing else holds it), or start a copy (something does). The
+      // answer is the one createSession acts on, asked the same way.
+      const held = await isHeldOpen(id);
+      return sendJson(res, 200, { measured: true, cwd, plan: cwd ? terminalPlan({ cwd, sessionId: id }) : null,
+        continueAs: held ? 'copy' : 'same', desktop: cwd ? desktopLine({ cwd, sessionId: id }) : null });
     }
 
     const gate = writeAllowed(req);
@@ -508,7 +550,6 @@ export async function handle(req, res) {
     const out = openTerminal({
       cwd: typeof body.cwd === 'string' ? body.cwd : cwd,
       sessionId: id,
-      command: typeof body.command === 'string' ? body.command : undefined,
     });
     return sendJson(res, out.ok ? 200 : 400, out);
   }
@@ -522,7 +563,8 @@ export async function handle(req, res) {
      the owner reaches this far; a viewer was refused above. */
 
   if (url.pathname === '/api/remote' && req.method === 'GET') {
-    return sendJson(res, 200, { measured: true, viewers: listViewers(), max: MAX_VIEWERS, now: Date.now() });
+    return sendJson(res, 200, { measured: true, viewers: listViewers(), max: MAX_VIEWERS, ttlMs: VIEWER_TTL_MS, now: Date.now(),
+      lan: LAN ? LAN.state() : { listening: false, addresses: [], errors: [] }, log: remoteLog(30) });
   }
 
   const remoteMatch = url.pathname.match(/^\/api\/remote(?:\/([^/]+))?$/);
@@ -532,11 +574,16 @@ export async function handle(req, res) {
     if (req.method === 'POST' && !remoteMatch[1]) {
       const body = await readBody(req);
       if (!body) return sendJson(res, 400, { ok: false, reason: 'body was not JSON' });
-      const made = addViewer(body.label);
-      return sendJson(res, made.ok ? 201 : 409, { ...made, viewers: listViewers() });
+      const made = addViewer(body.label, { transcripts: body.transcripts === true });
+      // The Wi-Fi listener opens with the first viewer; its links are known once it listens.
+      if (made.ok && LAN) await LAN.sync(liveCount());
+      const lanUrls = made.ok && LAN ? LAN.urls(made.viewer.token) : [];
+      return sendJson(res, made.ok ? 201 : 409, { ...made, lanUrls, lan: LAN ? LAN.state() : null, viewers: listViewers() });
     }
     if (req.method === 'DELETE' && remoteMatch[1]) {
-      return sendJson(res, 200, { ...revokeViewer(decodeURIComponent(remoteMatch[1])), viewers: listViewers() });
+      const out = revokeViewer(decodeURIComponent(remoteMatch[1]));
+      if (LAN) await LAN.sync(liveCount());
+      return sendJson(res, 200, { ...out, lan: LAN ? LAN.state() : null, viewers: listViewers() });
     }
     return sendJson(res, 405, { ok: false, reason: 'POST to add a viewer, or DELETE a viewer id' });
   }
@@ -603,6 +650,10 @@ export 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]));
@@ -733,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
@@ -977,9 +1028,11 @@ async function main() {
         '  --help       this text\n\n' +
         'Set CREW_STUDIO_TOKEN to require a bearer token, CREW_STUDIO_PEERS for a\n' +
         'comma-separated peer list.\n\n' +
-        'To watch from another device, add a viewer under Machines in the panel\n' +
-        'and open its link through a tunnel of your own. A viewer reads and\n' +
-        'changes nothing, and the server stays on loopback.\n\n' +
+        'To watch from a phone on the same Wi-Fi, add a viewer under Machines in\n' +
+        'the panel and scan its QR code. A viewer reads and changes nothing, its\n' +
+        'link lasts eight hours, and transcripts stay hidden unless you show them.\n' +
+        'While a viewer is live the server also listens on this machine\'s Wi-Fi\n' +
+        'address, for viewer links only; with none it is on loopback alone.\n\n' +
         'Peers are normally reached over a forwarded port, which keeps every\n' +
         'Studio on loopback:\n' +
         '  ssh -N -L 7778:127.0.0.1:7777 other-machine\n' +
@@ -996,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,
@@ -1082,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/graph.js

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

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

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

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

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

package/kit/studio/server/lib/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/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) {