crewforth 0.0.1 → 3.0.0-rc.1

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

@@ -0,0 +1,150 @@
+// The permission bridge.
+//
+// A PreToolUse hook injected through --settings parks each tool call, writes a
+// request into a spool, and waits for an answer file. The panel reads the spool
+// and writes the answer. The hook's exit code carries the decision: 0 allows,
+// 2 blocks.
+//
+// Why not simply let the hook time out on a "no": measured on this machine, a
+// hook killed at its configured timeout emits nothing and the tool PROCEEDS —
+// permission_denials came back 0 and the command ran. So the hook decides for
+// itself well inside that limit, and a hook the harness never has to kill fails
+// closed. The panel being shut is a denial, not an opening.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const HOOK = path.resolve(HERE, '..', 'hooks', 'studio-gate.sh');
+
+// The hook answers at HOOK_WAIT; the harness is told a larger number, so the
+// two never race and the harness has nothing to kill.
+const HOOK_WAIT_S = 45;
+const HARNESS_TIMEOUT_S = 90;
+const POLL_MS = 250;
+
+const ROOT = path.join(os.tmpdir(), 'crew-studio-gate');
+
+export function spoolFor(sessionId) {
+  if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) throw new Error('bad session id');
+  return path.join(ROOT, sessionId);
+}
+
+/**
+ * Write the settings file a session is spawned with.
+ *
+ * It is the panel's own file in the panel's own directory: the user's settings
+ * are never read, written, or merged. Returns null when the hook is missing, so
+ * the caller can say "no gate" instead of quietly running without one.
+ */
+export function prepare(sessionId) {
+  if (!fs.existsSync(HOOK)) return null;
+
+  const spool = spoolFor(sessionId);
+  for (const d of ['req', 'ans', 'always']) fs.mkdirSync(path.join(spool, d), { recursive: true });
+
+  const settingsPath = path.join(spool, 'settings.json');
+  const settings = {
+    hooks: {
+      PreToolUse: [{
+        // Every tool, not a chosen few: the panel cannot claim to gate a session
+        // while quietly exempting whichever tool it forgot to list.
+        matcher: '*',
+        hooks: [{
+          type: 'command',
+          command: `CREW_GATE_WAIT=${HOOK_WAIT_S} bash ${JSON.stringify(HOOK)} ${JSON.stringify(spool)}`,
+          timeout: HARNESS_TIMEOUT_S,
+        }],
+      }],
+    },
+  };
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  return { settingsPath, spool, waitSeconds: HOOK_WAIT_S };
+}
+
+/** One pending request, as the panel needs to show it. */
+function readRequest(spool, file) {
+  const toolUseId = file.replace(/\.json$/, '');
+  let raw;
+  try { raw = fs.readFileSync(path.join(spool, 'req', file), 'utf8'); } catch { return null; }
+
+  let payload = {};
+  try { payload = JSON.parse(raw); } catch { /* the hook writes it verbatim; keep going */ }
+
+  const input = payload.tool_input ?? {};
+  return {
+    toolUseId,
+    toolName: payload.tool_name ?? 'unknown',
+    // The most identifying field each tool has. Showing "Bash" alone would ask
+    // someone to approve a command they cannot see.
+    detail: input.command ?? input.file_path ?? input.pattern ?? input.query ?? input.description ?? null,
+    input,
+    cwd: payload.cwd ?? null,
+    askedAt: (() => {
+      try { return fs.statSync(path.join(spool, 'req', file)).mtimeMs; } catch { return Date.now(); }
+    })(),
+  };
+}
+
+export function pending(sessionId) {
+  const spool = spoolFor(sessionId);
+  let files;
+  try { files = fs.readdirSync(path.join(spool, 'req')); } catch { return []; }
+  return files
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => readRequest(spool, f))
+    .filter(Boolean)
+    .sort((a, b) => a.askedAt - b.askedAt);
+}
+
+export function alwaysList(sessionId) {
+  try { return fs.readdirSync(path.join(spoolFor(sessionId), 'always')); } catch { return []; }
+}
+
+/**
+ * Answer one request. `always` also allows that tool for the rest of the
+ * session, which is the user widening their own gate deliberately — it is
+ * scoped to one session and disappears with it.
+ */
+export function decide(sessionId, toolUseId, verdict) {
+  if (!/^[A-Za-z0-9_-]+$/.test(toolUseId)) return { ok: false, reason: 'bad tool use id' };
+  if (!['allow', 'deny', 'always'].includes(verdict)) return { ok: false, reason: `unknown verdict: ${verdict}` };
+
+  const spool = spoolFor(sessionId);
+  const req = pending(sessionId).find((r) => r.toolUseId === toolUseId);
+
+  if (verdict === 'always') {
+    const tool = req?.toolName;
+    if (tool && /^[A-Za-z0-9_-]+$/.test(tool)) {
+      try { fs.writeFileSync(path.join(spool, 'always', tool), ''); } catch { /* best effort */ }
+    }
+  }
+
+  try {
+    fs.writeFileSync(path.join(spool, 'ans', toolUseId), `${verdict}\n`);
+  } catch (e) {
+    return { ok: false, reason: String(e?.message ?? e) };
+  }
+  return { ok: true, verdict, toolName: req?.toolName ?? null };
+}
+
+/** Watch a session's spool and call back whenever the pending set changes. */
+export function watch(sessionId, onChange) {
+  let last = '';
+  const tick = () => {
+    const now = pending(sessionId);
+    const sig = now.map((r) => r.toolUseId).join(',');
+    if (sig !== last) { last = sig; onChange(now); }
+  };
+  tick();
+  const timer = setInterval(tick, POLL_MS);
+  return () => clearInterval(timer);
+}
+
+export function cleanup(sessionId) {
+  try { fs.rmSync(spoolFor(sessionId), { recursive: true, force: true }); } catch { /* already gone */ }
+}
+
+export const _internals = { HOOK, HOOK_WAIT_S, HARNESS_TIMEOUT_S, ROOT };

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

@@ -0,0 +1,294 @@
+// Locating a project's transcripts on disk.
+//
+// Claude Code stores them under ~/.claude/projects/<encoded-cwd>/, where the
+// encoding folds `: \ / . _` all down to `-`. That is lossy: two different
+// directories can encode to the same name, so this asks the filesystem rather
+// than trusting the spelling.
+//
+// Crewforth already solves this in bash (utilization.sh, context-usage.sh,
+// session-stats.sh share one byte-identical block that smoke-test §6i3 pins).
+// This is a re-implementation in another language on purpose — a fourth bash
+// copy would break that pin.
+
+// EVERY filesystem call here is async, and that is the point rather than a style
+// choice. On a Windows machine a single synchronous 128 KiB tail read once took
+// 31,209 ms, and because it blocked the event loop other requests waited with it:
+// `/api/projects` took 33,391 ms and a separate `/api/health` on its own connection
+// went unanswered for 312 of 324 pings. Measured later on the same machine with no
+// kit code running, a plain `tail -c 131072` of a freshly copied 25 MB transcript
+// waited 63-65 s right after the copy, 0.04 s warm, and 0.044 s when it waited 90 s
+// first. What holds the file was not identified, and the wait could not be produced
+// on demand. Async does not make the read faster; it keeps the wait inside the one
+// request that hit it while the rest of the panel stays up.
+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');
+
+/** Fold a working directory into the directory name Claude Code uses. */
+export function encodeCwd(cwd) {
+  return cwd.replace(/[:\\/._]/g, '-');
+}
+
+/** Candidate directory names for a cwd, best first. */
+export function candidateDirs(cwd) {
+  const seen = new Set();
+  const out = [];
+  for (const c of [encodeCwd(cwd), cwd.replace(/[/.]/g, '-'), cwd.replace(/\//g, '-')]) {
+    if (c && !seen.has(c)) { seen.add(c); out.push(c); }
+  }
+  return out;
+}
+
+/** The project directory for a cwd, or null when nothing was recorded yet. */
+export async function projectDir(cwd) {
+  for (const name of candidateDirs(cwd)) {
+    const p = path.join(PROJECTS_ROOT, name);
+    try { if ((await fsp.stat(p)).isDirectory()) return p; } catch { /* next */ }
+  }
+  return null;
+}
+
+/** Every project directory on this machine. */
+export async function allProjectDirs() {
+  try {
+    const entries = await fsp.readdir(PROJECTS_ROOT, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => path.join(PROJECTS_ROOT, e.name));
+  } catch {
+    return [];
+  }
+}
+
+// Sessions carry three kinds of name, in descending order of intent:
+// a custom title the person typed, the agent name, and an AI-written topic.
+// Reading them means scanning the transcript, and the sidebar refreshes on a
+// timer over every session in the project — so only the tail is read (the
+// latest record wins anyway) and the result is cached against size+mtime.
+const TITLE_TAIL_BYTES = 131072;
+const titleCache = new Map(); // file -> { sig, title }
+
+export async function sessionTitle(file, size, mtimeMs) {
+  const sig = `${size}:${mtimeMs}`;
+  const hit = titleCache.get(file);
+  if (hit && hit.sig === sig) return hit.title;
+
+  let title = null;
+  let fh;
+  try {
+    fh = await fsp.open(file, 'r');
+    const len = Math.min(size, TITLE_TAIL_BYTES);
+    const buf = Buffer.allocUnsafe(len);
+    await fh.read(buf, 0, len, Math.max(0, size - len));
+    const text = buf.toString('utf8');
+
+    // Cheap prefilter: most sessions carry none of these, and parsing every
+    // line of a 128 KiB tail for all of them is wasted work.
+    const found = { custom: null, agent: null, ai: null };
+    if (/"(custom-title|agent-name|ai-title)"/.test(text)) {
+      for (const line of text.split('\n')) {
+        if (!line.startsWith('{')) continue;                 // tail cut mid-record
+        if (!line.includes('-title"') && !line.includes('agent-name"')) continue;
+        let r;
+        try { r = JSON.parse(line); } catch { continue; }
+        if (r.type === 'custom-title' && r.customTitle) found.custom = r.customTitle;
+        else if (r.type === 'agent-name' && r.agentName) found.agent = r.agentName;
+        else if (r.type === 'ai-title' && r.aiTitle) found.ai = r.aiTitle;
+      }
+    }
+    title = found.custom ?? found.agent ?? found.ai ?? null;
+  } catch {
+    title = null;
+  } finally {
+    if (fh !== undefined) try { await fh.close(); } catch { /* already gone */ }
+  }
+
+  if (titleCache.size > 500) titleCache.clear();
+  titleCache.set(file, { sig, title });
+  return title;
+}
+
+// The working directory a session ran in. The encoded folder name cannot be
+// decoded back — the fold is lossy — so it is read from the first record,
+// which carries `cwd`. Head, not tail: the value never changes mid-session.
+const cwdCache = new Map();
+
+export async function sessionCwd(file, size) {
+  const hit = cwdCache.get(file);
+  if (hit && hit.size === size) return hit.cwd;
+
+  let cwd = null;
+  let fh;
+  try {
+    fh = await fsp.open(file, 'r');
+    const len = Math.min(size, 8192);
+    const buf = Buffer.allocUnsafe(len);
+    await fh.read(buf, 0, len, 0);
+    cwd = buf.toString('utf8').match(/"cwd"\s*:\s*"((?:[^"\\]|\\.)*)"/)?.[1] ?? null;
+    if (cwd) cwd = cwd.replace(/\\\\/g, '\\').replace(/\\"/g, '"');
+  } catch {
+    cwd = null;
+  } finally {
+    if (fh !== undefined) try { await fh.close(); } catch { /* already gone */ }
+  }
+
+  if (cwdCache.size > 500) cwdCache.clear();
+  cwdCache.set(file, { size, cwd });
+  return cwd;
+}
+
+/**
+ * Sessions inside one project directory.
+ * The tree is `<sid>.jsonl` at the top and a `<sid>/subagents/` directory
+ * beside it — counting only the top level is how you end up reporting that
+ * nothing ever delegated.
+ */
+export async function listSessions(dir) {
+  let entries;
+  try { entries = await fsp.readdir(dir, { withFileTypes: true }); } catch { return []; }
+
+  // One transcript's reads do not depend on another's, so they run together.
+  // Sequential awaits cost 12 ms here where the synchronous version cost 7 —
+  // measured, 10 runs each — and that gap grows with the number of sessions.
+  // The order is irrelevant: the list is sorted by mtime below.
+  const settled = await Promise.all(entries.map(async (e) => {
+    if (!e.isFile() || !e.name.endsWith('.jsonl')) return null;
+    const sessionId = e.name.slice(0, -'.jsonl'.length);
+    const file = path.join(dir, e.name);
+    let st;
+    try { st = await fsp.stat(file); } catch { return null; }
+
+    const subagentsDir = path.join(dir, sessionId, 'subagents');
+    const [agentCount, title, cwd] = await Promise.all([
+      countAgentMetas(subagentsDir),
+      sessionTitle(file, st.size, st.mtimeMs),
+      sessionCwd(file, st.size),
+    ]);
+
+    return { sessionId, file, subagentsDir, bytes: st.size, modifiedAt: st.mtimeMs, agentCount, title, cwd };
+  }));
+
+  const out = settled.filter(Boolean);
+  out.sort((a, b) => b.modifiedAt - a.modifiedAt);
+  return out;
+}
+
+/** Find one session anywhere on this machine, by id. */
+export async function findSession(sessionId) {
+  if (!/^[A-Za-z0-9._-]+$/.test(sessionId)) return null; // it becomes a path
+  for (const dir of await allProjectDirs()) {
+    const file = path.join(dir, `${sessionId}.jsonl`);
+    try {
+      const st = await fsp.stat(file);
+      return {
+        sessionId,
+        file,
+        dir,
+        subagentsDir: path.join(dir, sessionId, 'subagents'),
+        bytes: st.size,
+        modifiedAt: st.mtimeMs,
+      };
+    } catch { /* next project */ }
+  }
+  return null;
+}
+
+/**
+ * How many agents a session spawned.
+ *
+ * Agents land in two places: directly in `subagents/`, and one level deeper
+ * under `subagents/workflows/<id>/` when a workflow ran. Measured on this
+ * machine, 324 of 596 metas — 54% — were in the nested form, so a flat read
+ * silently reported a busy session as having delegated nothing.
+ */
+export async function countAgentMetas(subagentsDir) {
+  return (await agentMetaFiles(subagentsDir)).length;
+}
+
+/** Every agent meta file under a subagents directory, nesting included. */
+export async function agentMetaFiles(subagentsDir, depth = 0) {
+  const out = [];
+  if (depth > 3) return out;                    // workflows nest one level; this is slack
+  let entries;
+  try { entries = await fsp.readdir(subagentsDir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const p = path.join(subagentsDir, e.name);
+    if (e.isDirectory()) out.push(...await agentMetaFiles(p, depth + 1));
+    else if (e.name.endsWith('.meta.json')) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Every session on this machine, grouped by the project it ran in.
+ *
+ * Grouping is by the recorded `cwd` rather than by transcript folder: a folder
+ * name is a lossy fold of the path, so two different projects can share one.
+ * The folder is only the fallback when no record carried a cwd.
+ */
+export async function listProjects({ currentCwd = null, limitPerProject = 60, kitOf = null } = {}) {
+  const groups = new Map();
+
+  const dirs = await allProjectDirs();
+  const perDir = await Promise.all(dirs.map(async (dir) => [dir, await listSessions(dir)]));
+
+  for (const [dir, sessions] of perDir) {
+    for (const s of sessions) {
+      const key = s.cwd ?? `dir:${path.basename(dir)}`;
+      if (!groups.has(key)) {
+        groups.set(key, { key, cwd: s.cwd, dir, label: labelFor(s.cwd, dir), sessions: [] });
+      }
+      groups.get(key).sessions.push(s);
+    }
+  }
+
+  const out = [];
+  for (const g of groups.values()) {
+    g.sessions.sort((a, b) => b.modifiedAt - a.modifiedAt);
+    const kit = kitOf ? await kitOf(g.cwd) : null;
+    out.push({
+      ...g,
+      kit,
+      // Most transcript folders on a busy machine point at directories that no
+      // longer exist — test scratch dirs, moved checkouts. They are counted,
+      // not deleted: the panel says how many it is holding back rather than
+      // quietly shortening the list.
+      exists: kit?.dirExists ?? (g.cwd ? await existsCached(g.cwd) : false),
+      total: g.sessions.length,
+      agentTotal: g.sessions.reduce((n, s) => n + s.agentCount, 0),
+      modifiedAt: g.sessions[0]?.modifiedAt ?? 0,
+      current: currentCwd != null && g.cwd === currentCwd,
+      // Long histories are truncated rather than silently dropped, and the
+      // count above still reports the whole.
+      sessions: g.sessions.slice(0, limitPerProject),
+    });
+  }
+
+  // Standing-in first, then live directories, then an outdated kit ahead of a
+  // current one — the rows that need a decision float up.
+  out.sort((a, b) =>
+    Number(b.current) - Number(a.current) ||
+    Number(b.exists) - Number(a.exists) ||
+    Number(Boolean(b.kit?.outdated)) - Number(Boolean(a.kit?.outdated)) ||
+    b.modifiedAt - a.modifiedAt);
+  return out;
+}
+
+function labelFor(cwd, dir) {
+  if (!cwd) return path.basename(dir);
+  const parts = cwd.split(/[/\\]/).filter(Boolean);
+  return parts[parts.length - 1] || cwd;
+}
+
+const existsMemo = new Map();
+async function existsCached(p) {
+  if (existsMemo.has(p)) return existsMemo.get(p);
+  let v = false;
+  try { await fsp.stat(p); v = true; } catch { v = false; }
+  if (existsMemo.size > 2000) existsMemo.clear();
+  existsMemo.set(p, v);
+  return v;
+}

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

@@ -0,0 +1,191 @@
+// Sessions reachable elsewhere.
+//
+// A peer on another machine is visible only to a session connected to Remote
+// Control — measured: a headless session's ListAgents returns three local peers
+// where a connected one returns eight, and passing --remote-control to a
+// headless session does not change that, because the flag starts an
+// INTERACTIVE session.
+//
+// So the panel does not try to be that session. It reads what one already
+// wrote: an interactive session's ListAgents result lands in its transcript as
+// a tool_result, which is structured text on disk rather than a screen to
+// scrape. That makes this a SNAPSHOT — the roster as it stood when some
+// connected session last asked — and it is labelled that way everywhere,
+// because a stale list drawn as a live one is the kind of lie this panel is
+// built to avoid.
+
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { allProjectDirs } from './projects.js';
+
+const SCAN_FILES = 60;          // most recently written transcripts
+// The few newest files are read whole; the rest only from the tail. A live
+// session's transcript grows past any fixed tail, and the note this looks for
+// was written once — it scrolls out of a 2 MB window within an hour of work,
+// which is how the roster went from five machines to none while nothing about
+// the machines had changed.
+const DEEP_FILES = 6;
+const DEEP_BYTES = 24 * 1024 * 1024;
+const TAIL_BYTES = 2 * 1024 * 1024;
+// The transcript holding a roster ages out of the scan as new sessions are
+// written, and the peers do not disappear when it does — the panel just stops
+// being able to see the note. The last one found is kept, with the time it was
+// found, so a stale answer stays a stale answer instead of becoming "none".
+const CACHE_FILE = path.join(os.tmpdir(), 'crew-studio-roster.json');
+
+/** Parse the block ListAgents prints. */
+export function parseRoster(text) {
+  if (!text || !text.includes('Peer sessions')) return null;
+
+  const self = text.match(/This session is (\S+) \[([0-9a-f]+)\]/);
+  const peers = [];
+  // "  name [hash]  ·  kind  ·  status  ·  started 3h ago"
+  const re = /^\s{2,}(\S+)\s+\[([0-9a-f]+)\]\s+·\s+(.+)$/gm;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const parts = m[3].split('·').map((x) => x.trim()).filter(Boolean);
+    peers.push({
+      name: m[1],
+      ref: m[2],
+      kind: parts[0] ?? null,
+      status: parts[1] ?? null,
+      // Everything after is free text ("started 3h ago"); kept, not parsed into
+      // a time it might not be.
+      note: parts.slice(2).join(' · ') || null,
+      remote: /remote control/i.test(parts[0] ?? ''),
+    });
+  }
+  if (!peers.length) return null;
+  return { self: self ? { name: self[1], ref: self[2] } : null, peers };
+}
+
+// Async for the reason projects.js gives: this reads transcript tails too (TAIL_BYTES, and
+// DEEP_BYTES for the newest few), and it runs on the `/api/fleet` path the panel polls every 2 s.
+async function readTail(file, size, limit = TAIL_BYTES) {
+  let fh;
+  try {
+    fh = await fsp.open(file, 'r');
+    const len = Math.min(size, limit);
+    const buf = Buffer.allocUnsafe(len);
+    await fh.read(buf, 0, len, Math.max(0, size - len));
+    return buf.toString('utf8');
+  } catch {
+    return '';
+  } finally {
+    if (fh !== undefined) try { await fh.close(); } catch { /* gone */ }
+  }
+}
+
+/**
+ * The most recent roster any session recorded.
+ *
+ * Returns not-measured rather than an empty list when nothing has asked yet:
+ * "no session has run ListAgents" and "you have no peers" are different facts.
+ */
+export async function remoteRoster() {
+  const files = [];
+  for (const dir of await allProjectDirs()) {
+    let entries;
+    try { entries = await fsp.readdir(dir); } catch { continue; }
+    const stats = await Promise.all(entries.map(async (e) => {
+      if (!e.endsWith('.jsonl')) return null;
+      const p = path.join(dir, e);
+      try {
+        const st = await fsp.stat(p);
+        return { path: p, mtime: st.mtimeMs, size: st.size, sessionId: e.slice(0, -6) };
+      } catch { return null; }        // raced
+    }));
+    for (const s of stats) if (s) files.push(s);
+  }
+  files.sort((a, b) => b.mtime - a.mtime);
+
+  let best = null;
+  for (const [i, f] of files.slice(0, SCAN_FILES).entries()) {
+    const text = await readTail(f.path, f.size, i < DEEP_FILES ? DEEP_BYTES : TAIL_BYTES);
+    if (!text.includes('Peer sessions')) continue;
+
+    // The block lives INSIDE a JSON string, so its line breaks are the two
+    // characters \\n rather than real ones. Reading the raw tail with a
+    // line-anchored regex found nothing at all, which is how this was caught:
+    // the records have to be parsed, not grepped.
+    for (const line of text.split('\n')) {
+      if (!line.includes('Peer sessions') || !line.startsWith('{')) continue;
+      let rec;
+      try { rec = JSON.parse(line); } catch { continue; }
+
+      const chunks = [];
+      const content = rec?.message?.content;
+      if (typeof content === 'string') chunks.push(content);
+      else if (Array.isArray(content)) {
+        for (const c of content) {
+          if (typeof c?.text === 'string') chunks.push(c.text);
+          const inner = c?.content;
+          if (typeof inner === 'string') chunks.push(inner);
+          else if (Array.isArray(inner)) for (const x of inner) if (typeof x?.text === 'string') chunks.push(x.text);
+        }
+      }
+
+      for (const chunk of chunks) {
+        const parsed = parseRoster(chunk);
+        if (!parsed) continue;
+        // Prefer the roster that actually saw remote machines: a local-only one
+        // is a session that was not connected, and reporting it as the answer
+        // would say the peers had gone away.
+        const remotes = parsed.peers.filter((p) => p.remote).length;
+        const cand = { ...parsed, sessionId: f.sessionId, at: f.mtime, remotes };
+        if (!best || remotes > best.remotes || (remotes === best.remotes && cand.at > best.at)) best = cand;
+      }
+    }
+  }
+
+  const cached = await readCache();
+
+  if (!best) {
+    if (cached) return { ...cached, fromCache: true };
+    return {
+      measured: false,
+      reason: 'no session on this machine has recorded a peer list yet — run /list-agents in a session connected to Remote Control',
+      peers: [],
+    };
+  }
+
+  const found = {
+    measured: true,
+    // Said plainly: this is when a session last looked, not now.
+    seenAt: best.at,
+    seenBy: best.sessionId,
+    self: best.self,
+    peers: best.peers,
+    remotes: best.remotes,
+    live: false,
+  };
+
+  // A fresh scan that saw no remote machines does not overrule a remembered one
+  // that did: the newest note is usually from a headless session, which cannot
+  // see them at all.
+  if (cached && cached.remotes > found.remotes && cached.seenAt > Date.now() - CACHE_MAX_AGE_MS) {
+    return { ...cached, fromCache: true };
+  }
+
+  await writeCache(found);
+  return found;
+}
+
+const CACHE_MAX_AGE_MS = 12 * 60 * 60 * 1000;
+
+async function readCache() {
+  try {
+    const c = JSON.parse(await fsp.readFile(CACHE_FILE, 'utf8'));
+    if (!c?.measured || !Array.isArray(c.peers)) return null;
+    if (typeof c.seenAt !== 'number' || c.seenAt < Date.now() - CACHE_MAX_AGE_MS) return null;
+    return c;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(roster) {
+  try { await fsp.writeFile(CACHE_FILE, JSON.stringify(roster)); } catch { /* best effort */ }
+}