crewforth 0.0.1 → 3.0.0-rc.1

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

@@ -0,0 +1,135 @@
+// instance.js — let a second session find the panel that is already running.
+//
+// WHY THIS EXISTS. The panel printed its tokenised URL once, to the stdout of whoever started it, and kept the
+// token nowhere else. So a second session that wanted the SAME panel had no way in: it could see the port was
+// taken, but not that the holder was our own panel, and not what URL would open it. Measured in the field —
+// port 7777 was held by another session's crewforth-studio, the user asked for the panel, and the answer was a dead
+// end. The server said "try --port 7778", 7778 was held by something unrelated, and the command's own rule is
+// to retry once. Two ports, no panel, and a running instance nobody could reach.
+//
+// WHAT IT WRITES. One small JSON file per listening port, 0600, under the same runtime directory ensure-node.sh
+// already owns. It holds the token, which is the part that matters and the part that decides the mode: this is
+// a credential, so it is written to $HOME and never into the repo, where a stray `git add -A` would publish it.
+//
+// A STATE FILE IS A CLAIM, NOT A FACT. Processes are killed, machines lose power, and a file outlives both, so
+// nothing here trusts what it reads. A record is believed only when the port answers /api/health with the token
+// it names AND reports the pid it names. Anything else is treated as stale and removed, which also means a
+// crashed panel cleans itself up the next time anyone looks.
+import fs from 'node:fs';
+import http from 'node:http';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+// Deliberately the same directory ensure-node.sh uses, and overridden by the same variable: one place under
+// $HOME that the panel owns, that a user can delete wholesale, and that no installer has to know about.
+export function runtimeDir() {
+  return process.env.CREW_STUDIO_RUNTIME || path.join(os.homedir(), '.claude', 'studio-runtime');
+}
+
+export function statePath(port) {
+  return path.join(runtimeDir(), `instance-${port}.json`);
+}
+
+// 0600 twice: in the open flags, and again with chmod. The flag alone loses to a permissive umask on some
+// systems, and chmod alone leaves a window where the token sits world-readable.
+//
+// ON WINDOWS THIS IS NOT 0600 AND SHOULD NOT BE CALLED IT. POSIX mode bits are advisory there; what actually
+// protects the file is the ACL it inherits from the user's profile directory. Measured with icacls on Windows
+// 11: the record carries SYSTEM, Administrators and the owning user, all inherited, and no Everyone or Users
+// entry — so another standard user cannot read it, and a local administrator can. That is weaker than 0600,
+// which is why it is written down rather than rounded off, and why it is not the only defence: the panel
+// listens on loopback and the token is regenerated every run.
+export async function writeState(port, { token, name, pid = process.pid } = {}) {
+  const dir = runtimeDir();
+  await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+  const body = JSON.stringify({ pid, port, token, name, startedAt: new Date().toISOString() }, null, 2);
+  const file = statePath(port);
+  await fsp.writeFile(file, body, { mode: 0o600, flag: 'w' });
+  await fsp.chmod(file, 0o600).catch(() => {});
+  return file;
+}
+
+export async function readState(port) {
+  try {
+    const raw = await fsp.readFile(statePath(port), 'utf8');
+    const s = JSON.parse(raw);
+    if (!s || typeof s.token !== 'string' || !s.token) return null;
+    if (Number(s.port) !== Number(port)) return null;   // a file renamed by hand is not a record of this port
+    return s;
+  } catch {
+    return null;
+  }
+}
+
+export async function clearState(port) {
+  await fsp.rm(statePath(port), { force: true }).catch(() => {});
+}
+
+// Synchronous twin, for process exit. `process.on('exit')` runs no promises — an async unlink there is queued
+// and then dropped when the event loop stops, which would leave exactly the stale file this module refuses to
+// trust. Learned by leaving one behind.
+export function clearStateSync(port) {
+  try { fs.rmSync(statePath(port), { force: true }); } catch { /* exiting anyway */ }
+}
+
+// Ask the port whether it is ours. A short timeout because this sits between the user and an error message:
+// the interesting answers (a live local server, or nothing at all) both arrive in milliseconds, and anything
+// slower is not something to wait on while someone is watching a prompt.
+//
+// node:http rather than fetch, and that is not style. fetch is a GLOBAL, and a global can be replaced: the
+// panel's own offline suite installs a DOM stub so the browser modules can be exercised under Node, and that
+// stub owns `fetch`. The first version of this function used it and the suite reported a live panel as
+// unreachable -- the harness was wrong, not the code, which is the failure this repo has been bitten by
+// before. A module that reaches for a global is a module whose behaviour depends on who else is loaded.
+export function probe(port, token, { timeoutMs = 1500, host = '127.0.0.1' } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    const req = http.request(
+      { host, port, path: `/api/health?token=${encodeURIComponent(token)}`, method: 'GET', timeout: timeoutMs },
+      (res) => {
+        if (res.statusCode !== 200) { res.resume(); return done(null); }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (c) => { body += c; if (body.length > 64 * 1024) req.destroy(); });
+        res.on('end', () => {
+          try {
+            const j = JSON.parse(body);
+            done(j && j.ok ? j : null);
+          } catch { done(null); }
+        });
+      },
+    );
+    req.on('timeout', () => { req.destroy(); done(null); });
+    req.on('error', () => done(null));
+    req.end();
+  });
+}
+
+// The whole point, in one call: "port N is busy — is it us?"
+//
+// Returns { url, pid, name } when a panel we recorded is genuinely answering there, and null otherwise. Null
+// covers both shapes the caller has to tell the user apart from success, and they are NOT the same thing:
+// no record at all means something else owns the port, while a record that fails to answer means our own panel
+// died without cleaning up. The second case removes the file, so the next start is not misled by it.
+export async function findRunning(port) {
+  const s = await readState(port);
+  if (!s) return null;
+  const health = await probe(port, s.token);
+  if (!health) {
+    await clearState(port);
+    return null;
+  }
+  // The pid is the last check rather than the first: a port can be recycled to a different process quickly
+  // enough that a health answer alone is not proof of identity, and /api/health reports its own pid precisely
+  // so this comparison is possible. A mismatch means the record describes a process that no longer owns this
+  // port, so the record is stale even though something answered.
+  if (Number(health.pid) !== Number(s.pid)) {
+    await clearState(port);
+    return null;
+  }
+  return { url: `http://127.0.0.1:${port}/?token=${s.token}`, pid: s.pid, name: s.name, startedAt: s.startedAt };
+}
+
+export const _internals = { runtimeDir, statePath };

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

@@ -0,0 +1,182 @@
+// What Crewforth already measures about itself.
+//
+// The panel does not recompute any of it. Each of these shells out to Crewforth's
+// own tool and reports what it said, including when it said it could not
+// answer — `gate-report.sh` exits 4 in a checkout that has no installed hooks,
+// and that is a real answer, not an empty one.
+//
+// One distinction runs through the whole file. A gate event from an owned
+// session's stream carries the moment it happened; a line in gate-log.tsv does
+// not, because the format has no timestamp. Those are labelled differently all
+// the way to the screen, because drawing an observation as an event would be
+// the first thing here that is not true.
+
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const EXEC_TIMEOUT_MS = 10000;
+const MAX_BUFFER = 8 * 1024 * 1024;
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: EXEC_TIMEOUT_MS, maxBuffer: MAX_BUFFER, windowsHide: true, ...opts },
+      (err, stdout, stderr) => resolve({
+        code: err?.code ?? 0,
+        stdout: stdout ?? '',
+        stderr: stderr ?? '',
+        failed: Boolean(err),
+      }));
+  });
+}
+
+/** Where Crewforth's own scripts live for a given project, if they do. */
+function kitPaths(cwd) {
+  const installed = path.join(cwd, '.claude');
+  const source = path.join(cwd, 'kit');
+  if (fs.existsSync(path.join(installed, 'hooks', 'guard-bash.sh'))) {
+    return { kind: 'installed', hooks: path.join(installed, 'hooks'), evalDir: path.join(installed, 'eval') };
+  }
+  if (fs.existsSync(path.join(source, 'hooks', 'guard-bash.sh'))) {
+    return { kind: 'source', hooks: path.join(source, 'hooks'), evalDir: path.join(source, 'eval') };
+  }
+  return null;
+}
+
+/* --------------------------------------------------------------- gate log */
+
+/**
+ * The gate decisions recorded on disk.
+ *
+ * Four tab-separated columns: verdict, section, rule, command. The command is
+ * empty unless CREW_GATE_LOG_CMD=1 was set, and there is no timestamp at all —
+ * both facts are returned rather than papered over.
+ */
+export function gateLog(cwd, { limit = 200 } = {}) {
+  const file = path.join(cwd, '.claude', 'gate-log.tsv');
+  let st;
+  try { st = fs.statSync(file); } catch {
+    return { measured: false, reason: 'no .claude/gate-log.tsv in this project', entries: [] };
+  }
+
+  // Only the tail: this file reached 21,730 lines in Crewforth's own checkout and
+  // the panel wants the recent end of it.
+  const TAIL = 256 * 1024;
+  let text = '';
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+    const len = Math.min(st.size, TAIL);
+    const buf = Buffer.allocUnsafe(len);
+    fs.readSync(fd, buf, 0, len, Math.max(0, st.size - len));
+    text = buf.toString('utf8');
+  } catch {
+    return { measured: false, reason: 'gate log could not be read', entries: [] };
+  } finally {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch { /* gone */ }
+  }
+
+  const lines = text.split('\n');
+  if (st.size > TAIL) lines.shift();          // the first line was cut mid-record
+  const entries = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const [verdict, section, rule, command] = line.split('\t');
+    if (!verdict) continue;
+    entries.push({ verdict, section: section ?? null, rule: rule ?? null, command: command || null });
+  }
+
+  const counts = {};
+  for (const e of entries) counts[e.verdict] = (counts[e.verdict] ?? 0) + 1;
+
+  return {
+    measured: true,
+    file,
+    total: entries.length,
+    truncated: st.size > TAIL,
+    counts,
+    // Stated, not implied. The panel renders these as "observed", never as
+    // something that happened at a known time.
+    timestamped: false,
+    commandsRecorded: entries.some((e) => e.command),
+    entries: entries.slice(-limit).reverse(),
+  };
+}
+
+/* ------------------------------------------------------------ gate report */
+
+/** Crewforth's own inventory of gates, via gate-report.sh --json. */
+export async function gateReport(cwd) {
+  const kit = kitPaths(cwd);
+  if (!kit) return { measured: false, reason: 'Crewforth is not installed in this project' };
+
+  const script = path.join(kit.evalDir, 'gate-report.sh');
+  if (!fs.existsSync(script)) return { measured: false, reason: 'gate-report.sh is not present' };
+
+  // The script finds the hooks relative to where it is run: `./.claude/hooks`
+  // in an installed project, `./hooks` otherwise. In Crewforth's own checkout
+  // that second shape only resolves from inside kit/, and the log it
+  // 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 env = { ...process.env };
+  if (kit.kind !== 'installed' && fs.existsSync(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
+  // means it could not find the hooks. Both are answers.
+  if (r.code === 3) return { measured: false, reason: 'no gate log to report on' };
+  if (r.code === 4) return { measured: false, reason: 'gate-report could not find the hooks from here' };
+  try {
+    return { measured: true, ...JSON.parse(r.stdout) };
+  } catch {
+    return { measured: false, reason: r.stderr.trim().slice(0, 200) || 'gate-report produced no JSON' };
+  }
+}
+
+/* --------------------------------------------------------- session stats */
+
+/** session-stats.sh --raw: fifteen key=value metrics about one transcript. */
+export async function sessionStats(cwd, transcriptFile) {
+  const kit = kitPaths(cwd);
+  if (!kit) return { measured: false, reason: 'Crewforth is not installed in this project' };
+
+  const script = path.join(kit.hooks, 'session-stats.sh');
+  if (!fs.existsSync(script)) return { measured: false, reason: 'session-stats.sh is not present' };
+  if (!transcriptFile || !fs.existsSync(transcriptFile)) {
+    return { measured: false, reason: 'no transcript to read' };
+  }
+
+  const r = await run('bash', [script, '--raw', transcriptFile], { cwd });
+  const metrics = {};
+  for (const line of r.stdout.split('\n')) {
+    const m = line.match(/^([a-z_]+)=(-?\d+)$/);
+    if (m) metrics[m[1]] = Number(m[2]);
+  }
+  if (!Object.keys(metrics).length) {
+    return { measured: false, reason: r.stderr.trim().slice(0, 200) || 'session-stats produced no metrics' };
+  }
+  return { measured: true, metrics };
+}
+
+/* ----------------------------------------------------------------- board */
+
+/** The team board, if this repo has one. */
+export async function board(cwd) {
+  const kit = kitPaths(cwd);
+  if (!kit) return { measured: false, reason: 'Crewforth is not installed in this project' };
+
+  const script = path.join(kit.hooks, 'board.sh');
+  if (!fs.existsSync(script)) return { measured: false, reason: 'board.sh is not present' };
+
+  const r = await run('bash', [script, 'status'], { cwd });
+  const text = r.stdout.trim();
+  // "No board in this repo yet" is a state, not a failure — a project that
+  // never opened one should read as exactly that.
+  if (/no board/i.test(text)) return { measured: true, present: false, text };
+  if (!text) return { measured: false, reason: r.stderr.trim().slice(0, 200) || 'board.sh said nothing' };
+  return { measured: true, present: true, text };
+}
+
+export const _internals = { kitPaths };

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

@@ -0,0 +1,158 @@
+// Which projects run Crewforth, and which of them are behind.
+//
+// An installed project records its version in `.claude/VERSION` and its
+// install shape in `.claude/kit.conf`. The published version comes from the
+// same npm dist-tags feed Crewforth's own SessionStart hook reads, so the panel
+// and the hook can never disagree about what "latest" means.
+//
+// Read-only. Detecting that a project is behind and updating it are different
+// acts, and only the first one happens here.
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+const FEED = process.env.CREW_UPDATE_URL
+  ?? 'https://registry.npmjs.org/-/package/crewforth/dist-tags';
+const FEED_TTL_MS = 60 * 60 * 1000;   // the hook uses a day; a panel refreshes hourly
+const FETCH_TIMEOUT_MS = 8000;
+
+let latestCache = null;   // { at, value }
+let inflight = null;
+
+/**
+ * The published version WITHOUT waiting for the network.
+ *
+ * Returns whatever is cached, and starts a refresh if the cache is cold or stale — but never
+ * awaits it. Measured on a corporate machine: with the feed hanging, /api/projects took 8.37 s
+ * because it awaited this, which is the whole FETCH_TIMEOUT_MS. The project list is local data;
+ * it has no business waiting on a registry, and a user watching a 12-second blank reads it as a
+ * hung panel rather than as a slow lookup they never asked for.
+ *
+ * The honesty rule is unchanged: an unfetched answer says so with a reason. It never renders as
+ * "up to date". The reason simply becomes "not fetched yet" until the first refresh lands, and
+ * the next request serves the real answer.
+ */
+export function latestVersionCached() {
+  const fresh = latestCache && Date.now() - latestCache.at < FEED_TTL_MS;
+  // Deferred to a later tick, not merely un-awaited, so the request path does no work of its own.
+  //
+  // The panel stall once pinned on this feed was never the feed: a run with the feed disabled
+  // entirely stalled the same way. It was a synchronous transcript read on one Windows machine: one
+  // 128 KiB tail took 31,209 ms, and the event loop waited with it. projects.js has the panel's
+  // numbers and, kept apart from them, what was measured on that machine later. The reads are async
+  // now, so such a wait stays inside one request. This line stays because starting work on a request
+  // path is wrong regardless.
+  if (!fresh && !inflight) {
+    setTimeout(() => { latestVersion().catch(() => {}); }, 0).unref();
+  }
+  if (latestCache) return latestCache.value;
+  return { measured: false, reason: 'not fetched yet', at: Date.now(), pending: true };
+}
+
+/** The published version, or a stated reason it could not be read. Awaits the network. */
+export async function latestVersion({ force = false } = {}) {
+  if (!force && latestCache && Date.now() - latestCache.at < FEED_TTL_MS) return latestCache.value;
+  if (inflight) return inflight;
+
+  inflight = (async () => {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await fetch(FEED, { signal: ctl.signal });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const body = await res.json();
+      const v = sane(body?.latest ?? body?.version);
+      if (!v) throw new Error('feed carried no version');
+      return { measured: true, version: v, at: Date.now() };
+    } catch (e) {
+      // Offline is a legitimate answer. It is reported, never rendered as
+      // "everything is up to date".
+      return { measured: false, reason: String(e?.message ?? e), at: Date.now() };
+    } finally {
+      clearTimeout(timer);
+    }
+  })()
+    .then((value) => { latestCache = { at: Date.now(), value }; return value; })
+    .finally(() => { inflight = null; });
+
+  return inflight;
+}
+
+function sane(v) {
+  if (typeof v !== 'string') return null;
+  const m = v.trim().match(/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/);
+  return m ? m[0] : null;
+}
+
+/** Numeric-segment comparison. Returns <0, 0, >0. A pre-release sorts below its release. */
+export function compareVersions(a, b) {
+  const split = (v) => {
+    const [core, pre] = String(v).split(/[-+]/, 2);
+    return { nums: core.split('.').map((n) => parseInt(n, 10) || 0), pre: pre ?? null };
+  };
+  const x = split(a);
+  const y = split(b);
+  for (let i = 0; i < Math.max(x.nums.length, y.nums.length); i += 1) {
+    const d = (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  if (x.pre && !y.pre) return -1;
+  if (!x.pre && y.pre) return 1;
+  if (x.pre && y.pre) return x.pre < y.pre ? -1 : x.pre > y.pre ? 1 : 0;
+  return 0;
+}
+
+/** What Crewforth looks like inside one working directory.
+ *
+ * Async because it runs once per project on the `/api/projects` path, and a
+ * synchronous read there blocks the whole panel when one read stalls —
+ * see the note at the top of projects.js for the measurement.
+ */
+export async function kitStatus(cwd, latest) {
+  if (!cwd) return { installed: false, reason: 'no working directory recorded' };
+
+  const claude = path.join(cwd, '.claude');
+  let version = null;
+  try { version = sane(await fsp.readFile(path.join(claude, 'VERSION'), 'utf8')); } catch { /* not installed */ }
+
+  if (!version) {
+    // Distinguish "no kit here" from "the directory is gone" — one is a choice,
+    // the other is a dead path.
+    let present = false;
+    try { await fsp.stat(cwd); present = true; } catch { present = false; }
+    return { installed: false, dirExists: present, reason: present ? 'Crewforth not installed' : 'directory no longer exists' };
+  }
+
+  const conf = {};
+  try {
+    for (const line of (await fsp.readFile(path.join(claude, 'kit.conf'), 'utf8')).split('\n')) {
+      const m = line.match(/^\s*([A-Za-z_]+)\s*=\s*(.*)$/);
+      if (m) conf[m[1]] = m[2].trim();
+    }
+  } catch { /* older installs have no kit.conf */ }
+
+  const out = {
+    installed: true,
+    dirExists: true,
+    version,
+    stack: conf.stack ?? null,
+    installer: conf.installer ?? null,
+  };
+
+  if (!latest?.measured) {
+    // Not measured is not "current". Saying a project is up to date because
+    // the network was down is the one answer worse than saying nothing.
+    out.compared = false;
+    out.reason = latest?.reason ?? 'latest version not read';
+    return out;
+  }
+
+  const d = compareVersions(version, latest.version);
+  out.compared = true;
+  out.latest = latest.version;
+  out.outdated = d < 0;
+  out.ahead = d > 0;                 // a dev machine can legitimately run ahead of npm
+  return out;
+}
+
+export const _internals = { sane, FEED };

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

@@ -0,0 +1,118 @@
+// Node colours.
+//
+// Crewforth's agents already declare a colour in their frontmatter; the hex
+// values below give each of those names one shade, so an agent keeps the same
+// colour in every session the panel draws.
+//
+// An agent type nobody declared gets a neutral grey and a marked flag. Guessing
+// a colour would make an unknown agent look like a known one, which is the
+// visual form of the thing this project refuses to do.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Where Crewforth's agents sit, relative to this file.
+ *
+ * One rule, no candidate list: the panel lives inside the component tree it
+ * reads, so `<studio>/../agents` is the answer in the repo (`kit/`),
+ * in an install (`.claude/`) and in a plugin root alike. A two-candidate
+ * resolver would be a branch exercised in one layout and rotting in the other.
+ *
+ * `here` is a parameter rather than a closed-over constant so the rule can be
+ * measured against a synthetic tree instead of only against this checkout.
+ * Returns null when the directory is not there — the caller must report that,
+ * never render it as "no kit agents".
+ */
+function agentsDirFor(here) {
+  const dir = path.resolve(here, '..', '..', '..', 'agents');
+  try { return fs.statSync(dir).isDirectory() ? dir : null; } catch { return null; }
+}
+
+const AGENTS_DIR = agentsDirFor(HERE);
+
+// The names agents declare, mapped onto hex values.
+const NAMED = {
+  green: '#35c874',
+  cyan: '#26c6e6',
+  blue: '#5b8cff',
+  orange: '#f2a65a',
+  purple: '#b07cf6',
+  red: '#ff8a4d',
+  pink: '#ffbc8a',
+  yellow: '#db5f1c',
+};
+
+// Claude Code's built-in agent types are not kit components and declare
+// nothing, so they take the diagram's "core" tones.
+const BUILTIN = {
+  Explore: '#26c6e6',
+  Plan: '#a874f5',
+  'general-purpose': '#c79bff',
+  claude: '#5b8cff',
+  'code-simplifier': '#84e6b0',
+  'statusline-setup': '#94a3c8',
+  'claude-code-guide': '#8659ee',
+};
+
+const UNKNOWN = '#94a3c8';
+
+let cached = null;
+
+function readKitAgents() {
+  const out = {};
+  if (!AGENTS_DIR) return null;
+  let files;
+  // null, not {}: an empty map and an unreadable directory are the same picture
+  // on screen — twelve grey rings — and only one of them is the truth.
+  try { files = fs.readdirSync(AGENTS_DIR); } catch { return null; }
+
+  for (const f of files) {
+    if (!f.endsWith('.md')) continue;
+    let src;
+    try { src = fs.readFileSync(path.join(AGENTS_DIR, f), 'utf8'); } catch { continue; }
+    // Frontmatter only: stop at the closing fence so a colon in the body cannot
+    // masquerade as a field.
+    const fm = src.split(/^---$/m)[1] ?? '';
+    const name = fm.match(/^name:\s*(.+)$/m)?.[1]?.trim();
+    const color = fm.match(/^color:\s*(.+)$/m)?.[1]?.trim();
+    if (name) out[name] = { color: color ?? null, hex: color ? (NAMED[color] ?? null) : null, source: 'kit' };
+  }
+  return out;
+}
+
+export function palette() {
+  if (cached) return cached;
+  const kit = readKitAgents();
+  const measured = kit !== null;
+  const map = {};
+  for (const [name, v] of Object.entries(kit ?? {})) {
+    map[name] = { hex: v.hex ?? UNKNOWN, declared: v.color, known: Boolean(v.hex), source: 'kit' };
+  }
+  for (const [name, hex] of Object.entries(BUILTIN)) {
+    if (!map[name]) map[name] = { hex, declared: null, known: true, source: 'builtin' };
+  }
+  cached = {
+    map,
+    unknown: UNKNOWN,
+    named: NAMED,
+    kitAgents: measured ? Object.keys(kit).length : 0,
+    agentsDir: AGENTS_DIR ?? path.resolve(HERE, '..', '..', '..', 'agents'),
+    measured,
+    reason: measured ? null : `no agents directory beside the panel at ${path.resolve(HERE, '..', '..', '..', 'agents')}`,
+  };
+  return cached;
+}
+
+export function colorFor(agentType) {
+  const p = palette();
+  return p.map[agentType]?.hex ?? p.unknown;
+}
+
+// The resolver, exported for measurement: the pin drives it against synthetic
+// trees, which is the only way to prove the "one rule, every layout" claim
+// without three checkouts.
+export const _internals = { agentsDirFor };

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

@@ -0,0 +1,72 @@
+// Other machines.
+//
+// Transcripts are local files. `claude agents --json` reports only the machine
+// it runs on, and no CLI lists another machine's sessions — measured, not
+// assumed. So the only way to see a second machine is to run Studio there too
+// and have this one read it.
+//
+// The server still binds to loopback, and that is not negotiable: it serves a
+// developer's transcripts. A peer is therefore normally a forwarded port —
+//
+//     ssh -N -L 7778:127.0.0.1:7777 other-machine
+//     node studio/server/index.js --peer http://127.0.0.1:7778
+//
+// which needs no listening socket on any network and no new credentials. A
+// peer that is unreachable is reported as unreachable, never as empty.
+
+const PEER_TIMEOUT_MS = 6000;
+
+export function parsePeers(list) {
+  const out = [];
+  for (const raw of list) {
+    const spec = String(raw).trim();
+    if (!spec) continue;
+    let url;
+    try {
+      url = new URL(spec.includes('://') ? spec : `http://${spec}`);
+    } catch {
+      out.push({ spec, error: 'not a URL' });
+      continue;
+    }
+    // A token may ride along as ?token=… or as the URL's password field.
+    const token = url.searchParams.get('token') || url.password || null;
+    url.search = '';
+    url.username = '';
+    url.password = '';
+    const name = url.port ? `${url.hostname}:${url.port}` : url.hostname;
+    out.push({ spec, base: url.origin, token, name });
+  }
+  return out;
+}
+
+async function ask(peer, path) {
+  if (peer.error) return { ok: false, reason: peer.error };
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), PEER_TIMEOUT_MS);
+  try {
+    const headers = peer.token ? { authorization: `Bearer ${peer.token}` } : {};
+    const res = await fetch(`${peer.base}${path}`, { headers, signal: ctl.signal });
+    if (!res.ok) return { ok: false, reason: `HTTP ${res.status}` };
+    return { ok: true, body: await res.json() };
+  } catch (e) {
+    return { ok: false, reason: e?.name === 'AbortError' ? 'timed out' : String(e?.message ?? e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Ask every peer the same question, in parallel. Never throws. */
+export async function askAll(peers, path) {
+  return Promise.all(peers.map(async (p) => ({ peer: p, ...(await ask(p, path)) })));
+}
+
+/** Find which peer holds a session, so graph and detail reads can be routed. */
+export async function locateSession(peers, sessionId) {
+  for (const p of peers) {
+    const r = await ask(p, `/api/session/${encodeURIComponent(sessionId)}/graph`);
+    if (r.ok && r.body?.measured) return p;
+  }
+  return null;
+}
+
+export { ask };