@mmerterden/multi-agent-pipeline 20.29.0 → 20.30.0

package/pipeline/scripts/activity-snapshot.mjs

@@ -0,0 +1,1027 @@
+#!/usr/bin/env node
+/**
+ * @file activity-snapshot.mjs  -  what every agent on this machine is doing
+ * right now, as one document the office view draws: a room per repository, a
+ * table per run (its team), a seat per agent at that table.
+ *
+ * Two sources, both on disk, read on every call:
+ *
+ *   1. the run index (runs-index.mjs buildIndex): which runs exist, their
+ *      phase, `meta.Now`, the question they wait on, their tracker tokens;
+ *   2. the host transcripts that changed within the recent window (10 minutes
+ *      by default): `~/.claude/projects/<slug>/<session>.jsonl` for the
+ *      session's own desk and `<session>/subagents/agent-<id>.jsonl` with its
+ *      `.meta.json` sidecar (agentType, description, finished) for each
+ *      subagent; Copilot CLI and Codex sessions as a single limited desk,
+ *      since neither host writes subagent detail.
+ *
+ * A session is tied to a run by the session id the run recorded, else by its
+ * working directory and branch. Two runs that both fit leave the session at a
+ * table of its own marked `unmatched`; nothing is written into a run on a guess.
+ * Parallel runs of one repository sit at tables in the same room; a run over
+ * several repositories (`projects[]`) is listed in `corridors`.
+ *
+ * Seats: the orchestrator (the session itself) at the head, then every
+ * subagent in the order of the phase it was spawned in, parallel ones side by
+ * side. `holder` names the seat that holds the work now and `previousHolder`
+ * the last seat of an earlier phase, so a client can draw the handoff. Table
+ * fields come from the run's own state (location, branch, phase n of last,
+ * elapsed time, tracker cost); what the state does not say is null, never
+ * guessed.
+ *
+ * The role over each desk comes from schemas/activity-roles.json and only
+ * from there: a known agentType has its label, an untyped one (general-purpose,
+ * claude, fork) takes the role of the phase the run was in when it spawned, and
+ * anything else is shown as its raw type. Agents of one role at one table are
+ * numbered (Reviewer 1, Reviewer 2) in spawn order.
+ *
+ * Privacy. Transcripts are read through _transcript-tail.mjs, which never
+ * parses api-request records and drops thinking blocks. A desk's label is
+ * built from allow-listed fields only: the tool name, a file's basename and the
+ * sidecar description; a Bash command is never shown here. Every string that
+ * reaches the document passes the transcript redactor, and the finished
+ * document is checked once more by the outbound gate. The chat page (`chat`)
+ * shows message text and tool input, redacted the same way.
+ *
+ * Read-only: no file is written. Between calls only rebuildable state is kept
+ * in memory (one byte offset and one reduced state per transcript).
+ *
+ * Usage:
+ *   activity-snapshot.mjs [--json] [--recent-minutes N]
+ *   activity-snapshot.mjs chat <sessionId> [<agentId>] [--before N] [--limit N]
+ *
+ * TRANSCRIPTS_ROOT, COPILOT_TRANSCRIPTS_ROOT and CODEX_TRANSCRIPTS_ROOT
+ * override where transcripts are read, as for transcript-index.mjs.
+ *
+ * Exit: 0 printed, 2 usage, 3 no such session or agent (chat), 4 redaction guard.
+ *
+ * @module pipeline/scripts/activity-snapshot
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { scan } from "../lib/outbound-gate.mjs";
+import { listSessions, sessionLiveness } from "../lib/claude-sessions.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { ACTIVITY_TYPES, CHAT_TYPES, createFollower, readTailPage } from "./_transcript-tail.mjs";
+import { createAdapter, detectFormat, sessionCwd } from "./_transcript-hosts.mjs";
+import {
+  assertClean,
+  createRedactor,
+  defaultCodexRoot,
+  defaultCopilotRoot,
+  defaultProjectsRoot,
+} from "./transcript-index.mjs";
+import { buildIndex } from "./runs-index.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const RECENT_MS = 10 * 60_000;
+
+export const ROLES = JSON.parse(
+  readFileSync(new URL("../schemas/activity-roles.json", import.meta.url), "utf8"),
+);
+const PHASE_NAMES = Object.fromEntries(
+  JSON.parse(readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8")).phases.map(
+    (p) => [String(p.id), p.name],
+  ),
+);
+
+const TERMINAL = new Set(["complete", "completed", "done", "abandoned", "cancelled", "failed"]);
+const READ_TOOLS = new Set([
+  "Read",
+  "Grep",
+  "Glob",
+  "LS",
+  "WebFetch",
+  "WebSearch",
+  "NotebookRead",
+  "ToolSearch",
+  "view",
+  "read_file",
+]);
+const READ_MCP = /(?:^|_)(get|list|read|search|fetch|query|find|status|describe)(?:_|$)/i;
+const SPAWN_TOOLS = new Set(["Agent", "Task", "task", "spawn_agent"]);
+const WAIT_TOOLS = new Set(["AskUserQuestion"]);
+const SAFE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const SAFE_AGENT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const DESCRIPTION_LIMIT = 56;
+
+// ---------------------------------------------------------------------------
+// Roles, models, tools
+
+/**
+ * The role label for an agent type. `phaseId` is the run phase the agent was
+ * spawned in; it decides the role of an untyped agent and nothing else.
+ *
+ * @param {string|null} agentType  null for a session's own desk
+ * @param {number|string|null} phaseId
+ * @returns {{role: string, known: boolean}}
+ */
+export function roleFor(agentType, phaseId) {
+  if (!agentType) return { role: ROLES.orchestrator, known: true };
+  const named = ROLES.agentTypes[agentType];
+  if (named) return { role: named, known: true };
+  if (ROLES.untyped.includes(agentType)) {
+    const byPhase =
+      phaseId === null || phaseId === undefined ? null : ROLES.phaseRoles[String(phaseId)];
+    if (byPhase) return { role: byPhase, known: true };
+  }
+  return { role: agentType, known: false };
+}
+
+/** The fixed sprite and color of a role; an unknown role gets the neutral one. */
+export function styleFor(role) {
+  return ROLES.styles[role] ?? ROLES.unknownStyle;
+}
+
+/** "Opus" for claude-opus-5-5; any other id as it is. */
+export function modelLabel(id) {
+  if (typeof id !== "string" || !id) return null;
+  const m = /(fable|opus|sonnet|haiku)/i.exec(id);
+  return m ? m[1][0].toUpperCase() + m[1].slice(1).toLowerCase() : id;
+}
+
+function toolState(name) {
+  if (SPAWN_TOOLS.has(name)) return "spawning";
+  if (WAIT_TOOLS.has(name)) return "waiting";
+  if (READ_TOOLS.has(name)) return "reading";
+  if (name.startsWith("mcp__") && READ_MCP.test(name.split("__").pop())) return "reading";
+  return "writing";
+}
+
+/** The one allow-listed detail of a tool call: a file's basename, or the spawned type. */
+function toolDetail(name, input) {
+  if (!input || typeof input !== "object") return null;
+  if (SPAWN_TOOLS.has(name)) {
+    const t = input.subagent_type ?? input.agent_type;
+    return typeof t === "string" && t ? t : null;
+  }
+  for (const k of ["file_path", "notebook_path", "path"]) {
+    if (typeof input[k] === "string" && input[k]) return basename(input[k]);
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// One transcript, reduced to what a desk shows
+
+function emptyState() {
+  return {
+    firstAt: null,
+    lastAt: null,
+    model: null,
+    cwd: null,
+    gitBranch: null,
+    title: null,
+    last: null,
+    pending: new Map(),
+  };
+}
+
+const tsOf = (rec) => {
+  const t = Date.parse(rec?.timestamp ?? "");
+  return Number.isFinite(t) ? t : null;
+};
+
+/** Fold one Claude-shaped record into a desk state. */
+export function reduceRecord(s, rec) {
+  const t = tsOf(rec);
+  if (t !== null) {
+    s.firstAt = s.firstAt === null ? t : Math.min(s.firstAt, t);
+    s.lastAt = s.lastAt === null ? t : Math.max(s.lastAt, t);
+  }
+  if (typeof rec.cwd === "string" && rec.cwd) s.cwd = rec.cwd;
+  if (typeof rec.gitBranch === "string" && rec.gitBranch) s.gitBranch = rec.gitBranch;
+  if (rec.type === "ai-title" && typeof rec.aiTitle === "string") s.title = rec.aiTitle;
+  if (rec.type === "system" && rec.subtype === "turn_duration") s.pending.clear();
+  const msg = rec.message;
+  if (!msg || typeof msg !== "object") return s;
+  const content = Array.isArray(msg.content) ? msg.content : null;
+  if (rec.type === "assistant") {
+    if (typeof msg.model === "string" && msg.model && !msg.model.startsWith("<")) {
+      s.model = msg.model;
+    }
+    for (const b of content ?? []) {
+      if (b?.type === "tool_use" && typeof b.name === "string") {
+        const entry = { tool: b.name, detail: toolDetail(b.name, b.input) };
+        s.pending.set(String(b.id ?? s.pending.size), entry);
+        s.last = entry;
+      }
+    }
+    if (msg.stop_reason === "end_turn" || msg.stop_reason === "stop_sequence") s.pending.clear();
+  } else if (rec.type === "user") {
+    const results = (content ?? []).filter((b) => b?.type === "tool_result");
+    for (const b of results) s.pending.delete(String(b.tool_use_id));
+    if (!results.length && !rec.isMeta) s.pending.clear();
+  }
+  return s;
+}
+
+/** The state a desk shows for a reduced transcript. */
+function deskActivity(s, finished) {
+  if (finished)
+    return { state: "done", tool: s.last?.tool ?? null, detail: s.last?.detail ?? null };
+  const running = [...s.pending.values()].at(-1);
+  if (running)
+    return { state: toolState(running.tool), tool: running.tool, detail: running.detail };
+  return { state: "idle", tool: s.last?.tool ?? null, detail: s.last?.detail ?? null };
+}
+
+/**
+ * Rebuildable per-file state between snapshots: a follower (offsets) and the
+ * reduced state of each transcript it has read.
+ */
+export function createActivityCache() {
+  return { follower: createFollower({ allow: null }), states: new Map(), heads: new Map() };
+}
+const defaultCache = createActivityCache();
+
+/**
+ * The reduced state of one transcript, advanced by whatever was appended since
+ * the previous call. `format` is detected from the first record seen.
+ */
+function stateOf(cache, path) {
+  const got = cache.follower.read(path);
+  let entry = cache.states.get(path);
+  if (!entry || got.reset) {
+    entry = { state: emptyState(), format: null, adapter: null };
+    cache.states.set(path, entry);
+  }
+  for (const { record } of got.records) {
+    if (!entry.format) {
+      entry.format = detectFormat(record);
+      entry.adapter = createAdapter(entry.format);
+    }
+    for (const rec of entry.adapter(record)) {
+      if (entry.format === "claude" && !ACTIVITY_TYPES.has(rec.type)) continue;
+      reduceRecord(entry.state, rec);
+    }
+  }
+  entry.touched = true;
+  return entry;
+}
+
+/** The working directory a Copilot CLI or Codex session started in (its opening record). */
+function hostHead(cache, path) {
+  if (cache.heads.has(path)) return cache.heads.get(path);
+  let cwd = null;
+  try {
+    const text = readFileSync(path, { encoding: "utf8", flag: "r" }).slice(0, 256 * 1024);
+    for (const line of text.split("\n").slice(0, 16)) {
+      try {
+        cwd = sessionCwd(JSON.parse(line)) ?? cwd;
+      } catch {
+        // A partial first line says nothing; the next one may.
+      }
+      if (cwd) break;
+    }
+  } catch {
+    cwd = null;
+  }
+  cache.heads.set(path, cwd);
+  return cwd;
+}
+
+// ---------------------------------------------------------------------------
+// Disk walking
+
+const mtimeOf = (p) => {
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+};
+
+const listDir = (dir) => {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+};
+
+/** Claude Code session files changed since `since`, plus the ones runs name. */
+function claudeSessions(projectsRoot, since, wanted) {
+  const out = new Map();
+  for (const slug of listDir(projectsRoot)) {
+    const dir = join(projectsRoot, slug);
+    for (const f of listDir(dir)) {
+      if (!f.endsWith(".jsonl")) continue;
+      const sessionId = f.slice(0, -6);
+      if (!SAFE_SESSION_ID.test(sessionId)) continue;
+      const path = join(dir, f);
+      const m = mtimeOf(path);
+      if (m === null) continue;
+      if (m >= since || wanted.has(sessionId)) out.set(sessionId, { path, dir, mtime: m });
+    }
+  }
+  return out;
+}
+
+function subagentsOf(sessionDir, sessionId, since) {
+  const dir = join(sessionDir, sessionId, "subagents");
+  const out = [];
+  for (const f of listDir(dir)) {
+    const m = /^agent-([A-Za-z0-9_-]{1,64})\.jsonl$/.exec(f);
+    if (!m) continue;
+    const path = join(dir, f);
+    const mtime = mtimeOf(path);
+    if (mtime === null || mtime < since) continue;
+    const meta = readRegularJson(join(dir, `agent-${m[1]}.meta.json`), null) ?? {};
+    out.push({ agentId: m[1], path, meta });
+  }
+  return out.sort((a, b) => (a.agentId < b.agentId ? -1 : 1));
+}
+
+function copilotSessions(root, since) {
+  const out = [];
+  for (const d of listDir(root)) {
+    const path = join(root, d, "events.jsonl");
+    const m = mtimeOf(path);
+    if (m !== null && m >= since && SAFE_SESSION_ID.test(d))
+      out.push({ path, sessionId: d, host: "copilot" });
+  }
+  return out;
+}
+
+function codexSessions(root, since, depth = 0) {
+  const out = [];
+  for (const name of listDir(root)) {
+    const p = join(root, name);
+    if (depth < 3 && !name.endsWith(".jsonl")) {
+      out.push(...codexSessions(p, since, depth + 1));
+      continue;
+    }
+    const m = /^rollout-.*-([0-9a-f-]{36})\.jsonl$/i.exec(name);
+    const mt = m ? mtimeOf(p) : null;
+    if (m && mt !== null && mt >= since) out.push({ path: p, sessionId: m[1], host: "codex" });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Runs
+
+const samePath = (p) => String(p ?? "").replace(/\/+$/, "");
+const inside = (path, root) =>
+  Boolean(root) &&
+  (samePath(path) === samePath(root) || samePath(path).startsWith(samePath(root) + "/"));
+
+/** The repository a working directory belongs to: the checkout, not the worktree. */
+export function repoName(path) {
+  if (typeof path !== "string" || !path) return null;
+  const root = path.replace(/\/\.(?:claude\/)?worktrees\/.*$/, "").replace(/\/+$/, "");
+  return basename(root) || null;
+}
+
+/** The fields of agent-state.json the index does not carry. */
+export function runExtras(run) {
+  if (!run.dir) return {};
+  for (const p of [
+    join(run.dir, "agent-state.json"),
+    join(run.dir, "artifacts", "agent-state.json"),
+  ]) {
+    if (!existsSync(p)) continue;
+    const doc = readRegularJson(p, null);
+    if (doc && typeof doc === "object") {
+      return {
+        projectRoot: typeof doc.projectRoot === "string" ? doc.projectRoot : null,
+        projects: Array.isArray(doc.projects) ? doc.projects : [],
+      };
+    }
+  }
+  return {};
+}
+
+/**
+ * The run a session belongs to: the one that recorded its id, else the one
+ * whose worktree holds its working directory, or whose checkout and branch it
+ * shares. More than one such run is `ambiguous`.
+ *
+ * @returns {{run: object|null, matchedBy: "session"|"cwd-branch"|null, ambiguous: boolean}}
+ */
+export function matchRun(sessionId, cwd, branch, runs) {
+  const byId = runs.find((r) => r.sessionId && r.sessionId === sessionId);
+  if (byId) return { run: byId, matchedBy: "session", ambiguous: false };
+  if (!cwd) return { run: null, matchedBy: null, ambiguous: false };
+  const hits = runs.filter((r) => {
+    const roots = [{ wt: r.worktreePath, root: r.extras?.projectRoot, branch: r.branch }];
+    for (const p of r.extras?.projects ?? []) {
+      roots.push({ wt: p?.worktreePath, root: p?.projectRoot, branch: p?.branch ?? r.branch });
+    }
+    return roots.some(
+      (x) =>
+        (x.wt && inside(cwd, x.wt)) ||
+        (x.root && samePath(cwd) === samePath(x.root) && branch && x.branch === branch),
+    );
+  });
+  if (hits.length === 1) return { run: hits[0], matchedBy: "cwd-branch", ambiguous: false };
+  return { run: null, matchedBy: null, ambiguous: hits.length > 1 };
+}
+
+/** The phase a run was in at time `t`: the latest one started before it. */
+export function phaseAt(run, t) {
+  if (!run) return null;
+  if (t !== null) {
+    let best = null;
+    for (const p of run.phases ?? []) {
+      const s = Date.parse(p.startedAt ?? "");
+      const e = Date.parse(p.completedAt ?? "");
+      if (!Number.isFinite(s) || s > t) continue;
+      if (Number.isFinite(e) && t >= e) continue;
+      if (!best || s > best.s) best = { s, id: p.id };
+    }
+    if (best) return Number(best.id);
+  }
+  return Number.isFinite(run.currentPhase) ? run.currentPhase : null;
+}
+
+const iso = (ms) => (ms === null || ms === undefined ? null : new Date(ms).toISOString());
+
+// ---------------------------------------------------------------------------
+// The snapshot
+
+/**
+ * The office document.
+ *
+ * @param {{
+ *   runs?: object[], projectsRoot?: string, copilotRoot?: string, codexRoot?: string,
+ *   sessions?: object[]|undefined|null, now?: number, recentMs?: number,
+ *   cache?: ReturnType<typeof createActivityCache>
+ * }} [opts]  `sessions` is the `claude agents --json` list; null reads it,
+ *   undefined leaves liveness unknown.
+ */
+export async function activitySnapshot(opts = {}) {
+  const now = opts.now ?? Date.now();
+  const recentMs = opts.recentMs ?? RECENT_MS;
+  const since = now - recentMs;
+  const cache = opts.cache ?? defaultCache;
+  const sessions = opts.sessions === null ? listSessions() : opts.sessions;
+  const R = createRedactor();
+  const clean = (v, limit = 160) =>
+    v === null || v === undefined || v === "" ? null : R.excerpt(v, limit);
+
+  const allRuns = opts.runs ?? buildIndex();
+  const runs = allRuns
+    .filter((r) => !TERMINAL.has(r.status))
+    .map((r) => ({ ...r, extras: runExtras(r) }));
+  const wanted = new Set(runs.map((r) => r.sessionId).filter(Boolean));
+
+  for (const e of cache.states.values()) e.touched = false;
+
+  const teams = new Map();
+  const teamForRun = (run) => {
+    const id = `run:${run.taskId}`;
+    if (!teams.has(id)) teams.set(id, { id, run, seats: [], sessions: [], hosts: new Set() });
+    return teams.get(id);
+  };
+  const liveOf = (sessionId) => {
+    if (sessions === undefined) return null;
+    return sessionLiveness(sessionId, sessions ?? undefined);
+  };
+
+  const addSession = ({ sessionId, path, dir, host, cwd: knownCwd }) => {
+    const main = stateOf(cache, path);
+    const s = main.state;
+    const cwd = knownCwd ?? s.cwd;
+    const hit = matchRun(sessionId, cwd, s.gitBranch, runs);
+    let team;
+    if (hit.run) {
+      team = teamForRun(hit.run);
+      team.matchedBy ??= hit.matchedBy;
+    } else {
+      const id = `session:${sessionId}`;
+      team = {
+        id,
+        run: null,
+        kind: hit.ambiguous ? "unmatched" : "session",
+        seats: [],
+        sessions: [],
+        hosts: new Set(),
+      };
+      teams.set(id, team);
+    }
+    team.sessions.push({ sessionId, cwd, branch: s.gitBranch, title: s.title, lastAt: s.lastAt });
+    team.hosts.add(host);
+    const live = liveOf(sessionId);
+    team.seats.push(
+      seat({ sessionId, agentId: null, agentType: null, s, finished: false, live, phase: null }),
+    );
+    if (host !== "claude" || !dir) return;
+    for (const sub of subagentsOf(dir, sessionId, since)) {
+      const st = stateOf(cache, sub.path).state;
+      const agentType = typeof sub.meta.agentType === "string" ? sub.meta.agentType : null;
+      const finished = sub.meta.finished === true;
+      team.seats.push(
+        seat({
+          sessionId,
+          agentId: sub.agentId,
+          agentType,
+          description: sub.meta.description,
+          s: st,
+          finished,
+          live: finished ? false : live,
+          phase: phaseAt(hit.run, st.firstAt),
+        }),
+      );
+    }
+  };
+
+  const seat = ({ sessionId, agentId, agentType, description, s, finished, live, phase }) => {
+    const { role, known } = roleFor(agentType ?? (agentId ? "unknown" : null), phase);
+    const style = styleFor(role);
+    const act = deskActivity(s, finished);
+    const detail = clean(act.detail, 80);
+    return {
+      id: `${sessionId}:${agentId ?? "main"}`,
+      sessionId,
+      agentId,
+      agentType,
+      role,
+      label: role,
+      known,
+      phase: agentId === null ? null : phase,
+      sprite: style.sprite,
+      color: style.color,
+      model: s.model,
+      modelLabel: modelLabel(s.model),
+      description: clean(description, DESCRIPTION_LIMIT),
+      state: act.state,
+      status: act.state === "done" ? "done" : act.state === "idle" ? "idle" : "working",
+      tool: act.tool,
+      detail,
+      doing: doingText(act.state, act.tool, detail),
+      live,
+      startedAt: iso(s.firstAt),
+      lastAt: iso(s.lastAt),
+    };
+  };
+
+  const projectsRoot = opts.projectsRoot ?? defaultProjectsRoot();
+  for (const [sessionId, f] of claudeSessions(projectsRoot, since, wanted)) {
+    addSession({ sessionId, path: f.path, dir: f.dir, host: "claude" });
+  }
+  for (const f of [
+    ...copilotSessions(opts.copilotRoot ?? defaultCopilotRoot(), since),
+    ...codexSessions(opts.codexRoot ?? defaultCodexRoot(), since),
+  ]) {
+    addSession({ ...f, dir: null, cwd: hostHead(cache, f.path) });
+  }
+
+  // A run waiting on you, or whose session is alive, has a table even when no
+  // transcript of it changed in the window.
+  for (const run of runs) {
+    const waiting =
+      Boolean(run.pendingQuestion) || run.status === "awaiting_input" || Boolean(run.waitingFor);
+    if (waiting || run.processAlive === true) teamForRun(run);
+  }
+
+  for (const [path, e] of cache.states) {
+    if (!e.touched) {
+      cache.states.delete(path);
+      cache.follower.forget(path);
+      cache.heads.delete(path);
+    }
+  }
+
+  const rooms = new Map();
+  const corridors = [];
+  for (const team of teams.values()) {
+    const table = renderTable(team, clean, now);
+    if (!rooms.has(table.repo)) rooms.set(table.repo, []);
+    rooms.get(table.repo).push(table);
+    if (table.repos.length > 1) corridors.push({ tableId: table.id, repos: table.repos });
+  }
+  const doc = {
+    contractVersion: CONTRACT_VERSION,
+    generatedAt: new Date(now).toISOString(),
+    recentMinutes: recentMs / 60_000,
+    rooms: [...rooms.entries()]
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+      .map(([repo, list]) => ({ repo, tables: list.sort(tableOrder) })),
+    corridors,
+    counts: { rooms: 0, tables: 0, seats: 0, live: 0, waiting: 0 },
+  };
+  for (const room of doc.rooms) {
+    doc.counts.rooms++;
+    for (const t of room.tables) {
+      doc.counts.tables++;
+      if (t.waitingForYou) doc.counts.waiting++;
+      for (const s of t.seats) {
+        doc.counts.seats++;
+        if (s.live === true && s.state !== "done") doc.counts.live++;
+      }
+    }
+  }
+  assertClean(JSON.stringify(doc));
+  return doc;
+}
+
+/** What a seat is doing, in a few plain words; the raw tool name when there is no phrase. */
+export function doingText(state, tool, detail) {
+  if (state === "done") return "Done";
+  if (!tool || state === "idle") return state === "idle" ? "Idle" : "Working";
+  const on = detail ? ` ${detail}` : "";
+  const phrase = TOOL_PHRASES[tool];
+  if (phrase) return `${phrase}${on}`;
+  if (tool.startsWith("mcp__")) {
+    const [, server, name] = tool.split("__");
+    return `Using ${name ?? tool} (${server})`;
+  }
+  return `${tool}${on}`;
+}
+
+const TOOL_PHRASES = {
+  Read: "Reading",
+  Edit: "Editing",
+  MultiEdit: "Editing",
+  Write: "Writing",
+  NotebookEdit: "Editing",
+  Grep: "Searching the code",
+  Glob: "Listing files",
+  LS: "Listing files",
+  Bash: "Running a command",
+  WebFetch: "Reading a web page",
+  WebSearch: "Searching the web",
+  Agent: "Spawning",
+  Task: "Spawning",
+  AskUserQuestion: "Asking you",
+  TodoWrite: "Updating the task list",
+  TaskCreate: "Updating the task list",
+  TaskUpdate: "Updating the task list",
+  Skill: "Running a skill",
+  ToolSearch: "Looking up a tool",
+};
+
+const tableOrder = (a, b) => {
+  const ka = a.kind === "run" ? `0${a.taskId}` : `1${a.seats[0]?.lastAt ?? ""}`;
+  const kb = b.kind === "run" ? `0${b.taskId}` : `1${b.seats[0]?.lastAt ?? ""}`;
+  return ka < kb ? -1 : ka > kb ? 1 : 0;
+};
+
+/** Number the seats of a role that appears more than once, in spawn order. */
+function numberParallel(seats) {
+  const byRole = new Map();
+  for (const d of seats) {
+    if (d.agentId === null) continue;
+    if (!byRole.has(d.role)) byRole.set(d.role, []);
+    byRole.get(d.role).push(d);
+  }
+  for (const group of byRole.values()) {
+    if (group.length < 2) continue;
+    group.sort(bySpawn).forEach((d, i) => (d.label = `${d.role} ${i + 1}`));
+  }
+}
+
+const bySpawn = (a, b) =>
+  (a.startedAt ?? "") < (b.startedAt ?? "")
+    ? -1
+    : (a.startedAt ?? "") > (b.startedAt ?? "")
+      ? 1
+      : (a.agentId ?? "") < (b.agentId ?? "")
+        ? -1
+        : 1;
+
+/**
+ * Orchestrator at the head, then the seats in the order of the phase each
+ * was spawned in, parallel agents of one phase side by side in spawn order.
+ */
+function seatOrder(a, b) {
+  if (a.agentId === null && b.agentId !== null) return -1;
+  if (b.agentId === null && a.agentId !== null) return 1;
+  const pa = a.phase ?? Infinity;
+  const pb = b.phase ?? Infinity;
+  return pa !== pb ? pa - pb : bySpawn(a, b);
+}
+
+/**
+ * Who holds the work now: the latest-started seat still working, else the
+ * orchestrator. `previousHolder` is the latest seat of an earlier phase, so a
+ * client can draw the handoff from it.
+ */
+function holders(seats, phaseId) {
+  const working = seats.filter((s) => s.agentId !== null && s.status === "working");
+  const holder = working.sort(bySpawn).at(-1) ?? seats.find((s) => s.agentId === null) ?? null;
+  const earlier = seats
+    .filter((s) => s.agentId !== null && s.phase !== null && phaseId !== null && s.phase < phaseId)
+    .sort(bySpawn)
+    .at(-1);
+  return { holder: holder?.id ?? null, previousHolder: earlier?.id ?? null };
+}
+
+const LAST_PHASE = Math.max(...Object.keys(PHASE_NAMES).map(Number));
+
+function renderTable(team, clean, now) {
+  const run = team.run;
+  const seats = team.seats.sort(seatOrder);
+  numberParallel(seats);
+  const hosts = [...team.hosts];
+  const host = hosts.find((h) => h !== "claude") ?? "claude";
+  const first = team.sessions[0] ?? null;
+  if (!run) {
+    const repo = repoName(first?.cwd) ?? "unknown";
+    return {
+      id: team.id,
+      kind: team.kind,
+      taskId: null,
+      title: clean(first?.title, 120),
+      host,
+      limited: host !== "claude",
+      sessionId: first?.sessionId ?? null,
+      matchedBy: null,
+      repo,
+      repos: [repo],
+      location: first?.cwd
+        ? /\/\.(?:claude\/)?worktrees\//.test(first.cwd)
+          ? "worktree"
+          : "local"
+        : "unknown",
+      branch: clean(first?.branch, 120),
+      phase: null,
+      phaseHistory: [],
+      startedAt: seats[0]?.startedAt ?? null,
+      elapsedSeconds: null,
+      now: null,
+      status: null,
+      waitingForYou: false,
+      pendingQuestion: null,
+      tokens: null,
+      estUsd: null,
+      costSource: "not-measured",
+      ...holders(seats, null),
+      seats,
+    };
+  }
+  const repo =
+    run.project ?? repoName(run.extras?.projectRoot) ?? repoName(first?.cwd) ?? "unknown";
+  const repos = [repo];
+  for (const p of run.extras?.projects ?? []) {
+    const name = repoName(p?.projectRoot ?? p?.worktreePath);
+    if (name && !repos.includes(name)) repos.push(name);
+  }
+  const phaseId = Number.isFinite(run.currentPhase) ? run.currentPhase : null;
+  const phaseRow =
+    (run.phases ?? []).find((p) => p.status === "in_progress") ??
+    (phaseId === null ? null : (run.phases ?? []).find((p) => p.id === String(phaseId)));
+  const shownPhase = phaseRow ? Number(phaseRow.id) : phaseId;
+  const measured = run.tokens && run.tokens.in + run.tokens.out + run.tokens.cached > 0;
+  const q = run.pendingQuestion;
+  const started = Date.parse(run.startedAt ?? "");
+  const location = run.worktreePath ? "worktree" : run.extras?.projectRoot ? "local" : "unknown";
+  return {
+    id: team.id,
+    kind: "run",
+    taskId: run.taskId,
+    title: clean(run.title, 120),
+    host,
+    limited: host !== "claude",
+    sessionId: run.sessionId ?? first?.sessionId ?? null,
+    matchedBy: team.matchedBy ?? null,
+    repo,
+    repos,
+    location,
+    branch: clean(run.branch, 120),
+    phase:
+      shownPhase === null || !Number.isFinite(shownPhase)
+        ? null
+        : {
+            id: shownPhase,
+            name: phaseRow?.name || PHASE_NAMES[String(shownPhase)] || String(shownPhase),
+            last: LAST_PHASE,
+          },
+    phaseHistory: (run.phases ?? []).map((p) => ({
+      id: Number.isFinite(Number(p.id)) ? Number(p.id) : null,
+      name: clean(p.name, 60) ?? "",
+      status: String(p.status ?? "pending"),
+      startedAt: p.startedAt ?? null,
+      completedAt: p.completedAt ?? null,
+    })),
+    startedAt: Number.isFinite(started) ? new Date(started).toISOString() : null,
+    elapsedSeconds: Number.isFinite(started)
+      ? Math.max(0, Math.round((now - started) / 1000))
+      : null,
+    now: clean(phaseRow?.now, 160),
+    status: run.status ?? null,
+    waitingForYou: Boolean(q) || run.status === "awaiting_input" || Boolean(run.waitingFor),
+    pendingQuestion: q
+      ? {
+          id: q.id,
+          text: clean(q.text, 400) ?? "",
+          kind: q.kind === "multi-select" ? "multi-select" : "single-select",
+          options: q.options.map((o) => ({ id: o.id, label: clean(o.label, 120) ?? "" })),
+        }
+      : null,
+    tokens: measured ? { ...run.tokens } : null,
+    estUsd: measured ? run.estUsd : null,
+    costSource: measured ? "tracker-state" : "not-measured",
+    ...holders(seats, shownPhase),
+    seats,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Chat
+
+/** The transcript of one desk on disk, or null. `agentId` null is the session itself. */
+export function transcriptPath(projectsRoot, sessionId, agentId) {
+  if (typeof sessionId !== "string" || !SAFE_SESSION_ID.test(sessionId)) return null;
+  if (agentId !== null && (typeof agentId !== "string" || !SAFE_AGENT_ID.test(agentId)))
+    return null;
+  for (const slug of listDir(projectsRoot)) {
+    const dir = join(projectsRoot, slug);
+    const p = agentId
+      ? join(dir, sessionId, "subagents", `agent-${agentId}.jsonl`)
+      : join(dir, `${sessionId}.jsonl`);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+const MAX_TEXT = 20_000;
+const MAX_RESULT = 2_000;
+const WITHHELD = "[withheld: the outbound gate still found a credential here]";
+
+const contentText = (c) => {
+  if (typeof c === "string") return c;
+  if (!Array.isArray(c)) return "";
+  return c
+    .map((b) =>
+      typeof b === "string"
+        ? b
+        : b?.type === "text"
+          ? (b.text ?? "")
+          : b?.type
+            ? `[${b.type}]`
+            : "",
+    )
+    .filter(Boolean)
+    .join("\n");
+};
+
+function toolSummary(input) {
+  if (!input || typeof input !== "object") return "";
+  for (const k of [
+    "command",
+    "file_path",
+    "path",
+    "pattern",
+    "url",
+    "query",
+    "description",
+    "skill",
+  ]) {
+    if (typeof input[k] === "string" && input[k]) return input[k];
+  }
+  return JSON.stringify(input);
+}
+
+/**
+ * One page of a desk's transcript, newest page first, messages oldest first
+ * within it.
+ *
+ * @param {{projectsRoot?: string, sessionId: string, agentId: string|null,
+ *   before?: number|null, limit?: number}} opts
+ * @returns {Promise<object|null>} null when the transcript is not on disk
+ */
+export async function agentChat({
+  projectsRoot = defaultProjectsRoot(),
+  sessionId,
+  agentId = null,
+  before = null,
+  limit = 200,
+}) {
+  const path = transcriptPath(projectsRoot, sessionId, agentId);
+  if (!path) return null;
+  const page = readTailPage(path, { before, limit, allow: CHAT_TYPES });
+  const R = createRedactor();
+  const guard = (text) => (scan(text).some((f) => f.certain) ? WITHHELD : text);
+  const text = (v, limit = MAX_TEXT) =>
+    guard(R.clean(String(v ?? "").slice(0, limit * 2)).slice(0, limit));
+  const messages = [];
+  for (const { offset, record } of page.records) {
+    if (record.isMeta) continue;
+    const c = record.message?.content;
+    const blocks = [];
+    if (typeof c === "string") {
+      if (c.trim()) blocks.push({ kind: "text", text: text(c) });
+    } else if (Array.isArray(c)) {
+      for (const b of c) {
+        if (b?.type === "text" && b.text?.trim()) blocks.push({ kind: "text", text: text(b.text) });
+        else if (b?.type === "tool_use") {
+          blocks.push({
+            kind: "tool",
+            name: String(b.name ?? "tool"),
+            summary: guard(R.excerpt(toolSummary(b.input), 240)),
+            toolUseId: typeof b.id === "string" ? b.id : null,
+          });
+        } else if (b?.type === "tool_result") {
+          blocks.push({
+            kind: "result",
+            toolUseId: typeof b.tool_use_id === "string" ? b.tool_use_id : null,
+            text: text(contentText(b.content), MAX_RESULT),
+            isError: b.is_error === true,
+          });
+        } else if (b?.type === "image") blocks.push({ kind: "text", text: "[image]" });
+      }
+    }
+    if (!blocks.length) continue;
+    messages.push({
+      offset,
+      role: record.type === "assistant" ? "assistant" : "user",
+      at: typeof record.timestamp === "string" ? record.timestamp : null,
+      blocks,
+    });
+  }
+  const out = {
+    contractVersion: CONTRACT_VERSION,
+    sessionId,
+    agentId,
+    messages,
+    before: page.before,
+    redacted: R.total(),
+  };
+  assertClean(JSON.stringify(out));
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+function renderHuman(doc) {
+  const L = [];
+  for (const room of doc.rooms) {
+    L.push(room.repo);
+    for (const t of room.tables) {
+      const head = t.taskId ?? t.sessionId ?? t.id;
+      const phase = t.phase ? ` Phase ${t.phase.id}/${t.phase.last} ${t.phase.name}` : "";
+      L.push(`  ${head}${phase}${t.waitingForYou ? "  (waiting for you)" : ""}`);
+      for (const s of t.seats) {
+        L.push(`    ${s.label}${s.modelLabel ? ` - ${s.modelLabel}` : ""}: ${s.doing}`);
+      }
+    }
+  }
+  if (!L.length) L.push("No agent activity in the recent window.");
+  return L.join("\n") + "\n";
+}
+
+function intArg(v, name) {
+  if (!/^[0-9]{1,12}$/.test(String(v ?? ""))) throw new Error(`${name} must be a whole number`);
+  return Number(v);
+}
+
+async function main(argv) {
+  if (argv[0] === "chat") {
+    const [, sessionId, maybeAgent, ...rest] = argv;
+    let agentId = null;
+    const flags = [...rest];
+    if (maybeAgent && !maybeAgent.startsWith("--")) agentId = maybeAgent;
+    else if (maybeAgent) flags.unshift(maybeAgent);
+    let before = null;
+    let limit = 200;
+    for (let i = 0; i < flags.length; i++) {
+      if (flags[i] === "--before") before = intArg(flags[++i], "--before");
+      else if (flags[i] === "--limit") limit = intArg(flags[++i], "--limit");
+      else throw new Error(`unknown argument ${flags[i]}`);
+    }
+    const page = await agentChat({ sessionId, agentId, before, limit });
+    if (!page) {
+      process.stderr.write("activity-snapshot: no such session or agent\n");
+      return 3;
+    }
+    process.stdout.write(JSON.stringify(page, null, 2) + "\n");
+    return 0;
+  }
+  let json = false;
+  let recentMs = RECENT_MS;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--json") json = true;
+    else if (argv[i] === "--recent-minutes")
+      recentMs = intArg(argv[++i], "--recent-minutes") * 60_000;
+    else throw new Error(`unknown argument ${argv[i]}`);
+  }
+  const doc = await activitySnapshot({ recentMs, sessions: null });
+  process.stdout.write(json ? JSON.stringify(doc, null, 2) + "\n" : renderHuman(doc));
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain(
+    "activity-snapshot",
+    async () => {
+      try {
+        process.exitCode = await main(process.argv.slice(2));
+      } catch (err) {
+        if (err?.code === "REDACTION") {
+          process.stderr.write(`activity-snapshot: ${err.message}; nothing was printed\n`);
+          process.exitCode = 4;
+          return;
+        }
+        throw err;
+      }
+    },
+    { code: 2 },
+  );
+}