local-commander-agent 0.3.48 → 0.3.49

package/bin/monitor.mjs

@@ -1,530 +1,530 @@
-import { lstat, open, readFile, readdir } from "node:fs/promises";
-import { lifetimeSavingsView, formatLifetimeSavings } from "./monitor-savings.mjs";
-import path from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
-import { readAgentActivity } from "./monitor-agents.mjs";
-import { readMcpActivity, readMcpHealth, contextView } from "./monitor-mcp.mjs";
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-const STATES = new Set(["starting", "connecting", "connected", "disconnected", "stopped", "failed"]);
-const EVENTS = new Set([...STATES, "execute", "prepare", "status", "output", "cancel", "finished", "cancelled", "unknown", "result", "request_failed", "rejected", "connection_error", "compacted", "passthrough"]);
-const iso = value => typeof value === "string" && /^\d{4}-\d\d-\d\dT[\d:.]+Z$/.test(value) && Number.isFinite(Date.parse(value));
-const invalid = () => { throw Error("MONITOR_DATA_INVALID"); };
-const count = value => Number.isSafeInteger(value) && value >= 0 && value <= 1_000_000_000_000;
-const label = value => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,79}$/.test(value);
-const EXECUTION_STATES = new Set(["requested", "prepared", "accepted", "running", "finished", "failed", "cancelled", "rejected", "unknown", "missing"]);
-const PROCESS_NAMES = new Set(["node", "npm", "npx", "git", "rg", "powershell", "pwsh", "cmd", "tsc", "python", "dotnet", "command",
-  "fs_list", "fs_read", "fs_search", "fs_write", "fs_replace", "git_status", "git_diff", "git_log", "project_snapshot", "localhost_request"]);
-const COMMANDS = new Set(["node --test", ...["status", "diff", "log", "show", "fetch", "pull", "push", "commit"].map(value => "git " + value),
-  ...["test", "install", "ci", "pack", "publish"].map(value => "npm " + value),
-  ...["test", "build", "typecheck", "lint", "dev", "start"].map(value => "npm run " + value),
-  ...[...PROCESS_NAMES].flatMap(value => [value, value + " [args]"])]);
-function profileView(raw) {
-  if (raw === null) return null;
-  if (!raw || !label(raw.model)) invalid();
-  return { model: raw.model };
-}
-function efficiencyView(raw) {
-  if (raw === undefined) return null; // Older agents did not measure monitor savings.
-  if (!raw || raw.scope !== "this_run" || !count(raw.calls) || !count(raw.polls?.status) || !count(raw.polls?.output) ||
-      !Array.isArray(raw.models) || raw.models.length > 32) invalid();
-  const models = raw.models.map(group => {
-    if (!group || (group.model !== null && !label(group.model)) || !count(group.calls) || !count(group.savedBytes) || !count(group.sentBytes)) invalid();
-    return { model: group.model, calls: group.calls, savedBytes: group.savedBytes,
-      sentBytes: group.sentBytes, estimatedSavedTokens: Math.round(group.savedBytes / 4) };
-  });
-  if (models.reduce((sum, group) => sum + group.calls, 0) !== raw.calls) invalid();
-  const savedBytes = models.reduce((sum, group) => sum + group.savedBytes, 0);
-  return { scope: "this_run", calls: raw.calls, polls: { status: raw.polls.status, output: raw.polls.output }, models,
-    savedBytes, estimatedSavedTokens: Math.round(savedBytes / 4),
-    unclassifiedSavedBytes: models.filter(group => group.model === null).reduce((sum, group) => sum + group.savedBytes, 0) };
-}
-function pidAlive(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch (error) { return error?.code === "EPERM"; }
-}
-
-// Explicit allowlist projection: never print extra fields from a local file.
-export function monitorView(raw, now = Date.now(), alive = pidAlive, transport = null) {
-  if (!raw || raw.schemaVersion !== 1 || !UUID.test(raw.instanceId) || !Number.isSafeInteger(raw.pid) || raw.pid <= 0 ||
-      typeof raw.agentVersion !== "string" || !/^[A-Za-z0-9._+-]{1,64}$/.test(raw.agentVersion) || !iso(raw.updatedAt) ||
-      !STATES.has(raw.connection?.state) || !Array.isArray(raw.sessions) || raw.sessions.length > 32 ||
-      !Array.isArray(raw.events) || raw.events.length > 100) invalid();
-  let origin = null;
-  if (raw.connection.origin !== null) {
-    const url = new URL(raw.connection.origin);
-    if (url.origin !== raw.connection.origin || url.username || url.password ||
-        !(url.protocol === "https:" || (url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))) invalid();
-    origin = url.origin;
-  }
-  const sessions = raw.sessions.map(session => {
-    if (!session || !UUID.test(session.sessionId) || !UUID.test(session.workspaceGrantId) || !iso(session.lastSeenAt)) invalid();
-    return { sessionId: session.sessionId, workspaceGrantId: session.workspaceGrantId, lastSeenAt: session.lastSeenAt, model: null };
-  });
-  const events = raw.events.map(event => {
-    if (!event || !Number.isSafeInteger(event.seq) || event.seq < 1 || !iso(event.at) || !EVENTS.has(event.event) ||
-        (event.sessionId !== undefined && !UUID.test(event.sessionId)) || (event.executionId !== undefined && !UUID.test(event.executionId)) ||
-        (event.tool !== undefined && (typeof event.tool !== "string" || !/^[a-z_]{1,64}$/.test(event.tool))) ||
-        (event.code !== undefined && (typeof event.code !== "string" || !/^[A-Z0-9_]{1,64}$/.test(event.code)))) invalid();
-    return { seq: event.seq, at: event.at, event: event.event,
-      ...(event.sessionId ? { sessionId: event.sessionId } : {}), ...(event.executionId ? { executionId: event.executionId } : {}),
-      ...(event.tool ? { tool: event.tool } : {}), ...(event.code ? { code: event.code } : {}) };
-  });
-  const running = alive(raw.pid);
-  if (raw.transportAt !== undefined && !iso(raw.transportAt)) invalid();
-  // A heartbeat file counts only for this snapshot's instance and connection (#31).
-  const heartbeat = raw.transportAt !== undefined && transport?.instanceId === raw.instanceId && transport.epoch === raw.connection.epoch &&
-    iso(transport.transportAt) && Date.parse(transport.transportAt) > Date.parse(raw.transportAt) ? transport.transportAt : raw.transportAt;
-  const age = now - Date.parse(raw.connection.state === "connected" ? heartbeat ?? raw.updatedAt : raw.updatedAt);
-  const freshnessMs = raw.freshnessMs ?? 10_000;
-  if (!Number.isInteger(freshnessMs) || freshnessMs < 1000 || freshnessMs > 180_000) invalid();
-  const connection = !running ? "stopped" : age < -5000 || age > freshnessMs ? "stale" : raw.connection.state;
-  if (raw.computer !== undefined && (typeof raw.computer !== "string" || !/^[A-Za-z0-9._-]{1,64}$/.test(raw.computer))) invalid();
-  if (raw.processName !== undefined && raw.processName !== "lc-agent") invalid();
-  if (raw.executions !== undefined && (!Array.isArray(raw.executions) || raw.executions.length > 64)) invalid();
-  const executions = (raw.executions ?? []).map(execution => {
-    if (!execution || !UUID.test(execution.executionId) || !UUID.test(execution.sessionId) || !PROCESS_NAMES.has(execution.name) ||
-        !COMMANDS.has(execution.command) || !EXECUTION_STATES.has(execution.state) ||
-        (execution.pid !== null && (!Number.isSafeInteger(execution.pid) || execution.pid <= 0)) ||
-        ![execution.originalBytes, execution.sentBytes, execution.savedBytes].every(value => value === null || count(value)) ||
-        (execution.reason !== null && (typeof execution.reason !== "string" || !/^[a-z_]{1,80}$/.test(execution.reason)))) invalid();
-    const measured = execution.originalBytes !== null;
-    if (measured ? execution.sentBytes === null || execution.savedBytes === null || execution.sentBytes > execution.originalBytes ||
-        execution.savedBytes !== execution.originalBytes - execution.sentBytes : execution.sentBytes !== null || execution.savedBytes !== null) invalid();
-    if (execution.preview !== undefined && (typeof execution.preview !== "string" || execution.preview.length > 240 || /[\u0000-\u001f\u007f-\u009f]/u.test(execution.preview))) invalid();
-    for (const field of ["startedAt", "endedAt"]) if (execution[field] !== undefined && execution[field] !== null && (!Number.isSafeInteger(execution[field]) || execution[field] < 0 || execution[field] > now + 5000)) invalid();
-    if (execution.exitCode !== undefined && execution.exitCode !== null && (!Number.isInteger(execution.exitCode) || Math.abs(execution.exitCode) > 2147483648)) invalid();
-    const profile = profileView(execution.profile);
-    const active = ["requested", "prepared", "accepted", "running"].includes(execution.state);
-    const state = active && connection !== "connected" ? connection === "stale" ? "stale" : "unknown" : execution.state;
-    return { executionId: execution.executionId, sessionId: execution.sessionId, name: execution.name, command: execution.command, preview: execution.preview ?? execution.command,
-      startedAt: execution.startedAt ?? null, endedAt: execution.endedAt ?? null, exitCode: execution.exitCode ?? null, timedOut: execution.timedOut === true, state, pid: execution.pid, profile, context: execution.context === undefined ? null : contextView(execution.context), originalBytes: execution.originalBytes, sentBytes: execution.sentBytes,
-      savedBytes: execution.savedBytes, reason: execution.reason, estimatedSavedTokens: measured ? Math.round(execution.savedBytes / 4) : null };
-  });
-  return { instanceId: raw.instanceId, pid: raw.pid, agentVersion: raw.agentVersion, updatedAt: raw.updatedAt,
-    running, connection, origin, sessions, events, computer: raw.computer ?? null, processName: "lc-agent", executions,
-    efficiency: efficiencyView(raw.efficiency),
-    savingsSourceId: typeof raw.savingsSourceId === "string" && /^[a-f0-9]{64}$/.test(raw.savingsSourceId) ? raw.savingsSourceId : null,
-    lifetimeSavings: lifetimeSavingsView(raw.lifetimeSavings) };
-}
-
-// Relay heartbeats refresh this tiny sibling file instead of rewriting the snapshot (#31). It is advisory.
-async function readTransport(file) {
-  try {
-    const stat = await lstat(file);
-    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024) return null;
-    return JSON.parse(await readFile(file, "utf8"));
-  } catch { return null; }
-}
-
-export async function readMonitors(directory) {
-  let entries;
-  try {
-    const stat = await lstat(directory);
-    if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
-    entries = (await readdir(directory)).filter(name => /^[a-f0-9]{64}\.json$/.test(name));
-  } catch (error) {
-    if (error?.code === "ENOENT") return { instances: [], unavailable: 0 };
-    return { instances: [], unavailable: 1 };
-  }
-  const instances = [];
-  let unavailable = Math.max(0, entries.length - 32);
-  for (const name of entries.slice(0, 32)) {
-    try {
-      const file = path.join(directory, name);
-      const stat = await lstat(file);
-      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024) invalid();
-      const handle = await open(file, "r");
-      let contents;
-      try {
-        const buffer = Buffer.alloc(128 * 1024 + 1);
-        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
-        if (bytesRead > 128 * 1024) invalid();
-        contents = buffer.subarray(0, bytesRead).toString("utf8");
-      } finally { await handle.close(); }
-      instances.push(monitorView(JSON.parse(contents), Date.now(), pidAlive, await readTransport(file.replace(/\.json$/, ".transport"))));
-    } catch { unavailable++; }
-  }
-  instances.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-  return { instances, unavailable };
-}
-
-function logLine(instance, event) {
-  const execution = instance.executions.find(row => row.executionId === event.executionId);
-  return [event.at, "pc=" + (instance.computer ?? "unknown"), "pid=" + instance.pid, event.event, event.tool, event.code,
-    execution && "cmd=" + (execution.preview ?? execution.command),
-    execution?.profile && "model=" + execution.profile.model,
-    execution && ["compacted", "passthrough"].includes(event.event) && "saved=~" + compact(execution.estimatedSavedTokens) +
-      "tok sent=" + execution.sentBytes + "B reason=" + execution.reason,
-    execution?.exitCode !== null && execution?.exitCode !== undefined && "exit=" + execution.exitCode,
-    execution?.timedOut && "timeout=true",
-    execution?.endedAt && execution.startedAt && "elapsed=" + (execution.endedAt - execution.startedAt) + "ms",
-    execution?.context?.directory && "dir=" + execution.context.directory, execution?.context?.taskId && "task=" + execution.context.taskId,
-    event.sessionId && "session=" + event.sessionId.slice(0, 8), event.executionId && "execution=" + event.executionId.slice(0, 8)].filter(Boolean).join(" ");
-}
-
-const compact = value => value === null ? "n/a" : value >= 1e6 ? (value / 1e6).toFixed(1) + "M" : value >= 1000 ? (value / 1000).toFixed(1) + "k" : String(value);
-const graphemes = new Intl.Segmenter("en", { granularity: "grapheme" });
-const cellWidth = text => /^\p{Mark}+$/u.test(text) ? 0 :
-  /[\u1100-\u115f\u2329\u232a\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe10-\ufe19\ufe30-\ufe6f\uff00-\uff60\uffe0-\uffe6\u{20000}-\u{3fffd}]|\p{Emoji_Presentation}|\ufe0f/u.test(text) ? 2 : 1;
-const fit = (value, width, right = false) => {
-  width = Math.max(0, width);
-  const parts = [...graphemes.segment(String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, " "))].map(part => part.segment);
-  const length = parts.reduce((sum, part) => sum + cellWidth(part), 0);
-  const clipped = length > width, limit = clipped && width >= 4 ? width - 3 : width;
-  let text = "", used = 0;
-  for (const part of parts) {
-    const cells = cellWidth(part);
-    if (used + cells > limit) break;
-    text += part; used += cells;
-  }
-  if (clipped && width >= 4) { text += "..."; used += 3; }
-  const padding = " ".repeat(width - used);
-  return right ? padding + text : text + padding;
-};
-
-function storyLines(result, computer) {
-  const personal = (result.mcp?.instances ?? []).filter(i => i.running && (!computer || i.computer === computer));
-  const native = result.instances.filter(i => i.running && (!computer || i.computer === computer));
-  const current = personal.flatMap(i => i.calls).find(c => c.state === "running") ?? personal.flatMap(i => i.calls)[0];
-  const history = [
-    ...personal.flatMap(i => [...(i.transitions ?? []), ...i.events].map(e => ({ ...e, computer: i.computer }))),
-    ...native.flatMap(i => i.events.filter(e => ["execute", "finished", "failed", "cancelled", "unknown"].includes(e.event)).map(e => {
-      const work = i.executions.find(x => x.executionId === e.executionId);
-      return { ...e, computer: i.computer, state: e.event, preview: work?.preview ?? work?.command ?? e.tool,
-        name: work?.executionId.slice(0, 8), context: work?.context, durationMs: work?.endedAt && work.startedAt ? work.endedAt - work.startedAt : null };
-    }))
-  ].sort((a,b) => a.at.localeCompare(b.at));
-  const latest = history.at(-1), context = current?.context ?? latest?.context;
-  const lines = [
-    "INVESTIGATION  " + (computer ?? "all PCs") + (result.paused ? "  [VIEW FROZEN; work continues]" : "  [LIVE]"),
-    "  Task: " + (context?.taskId ?? context?.project ?? "not reported") + (context?.pr ? " | PR #" + context.pr : "") +
-      " | Where: " + (context?.directory ?? "not reported"),
-    "  " + (current ? "Now: " + (current.agent?.name ?? "unbound caller") + " " + (current.preview ?? current.command) + " [" + current.state + "]" :
-      latest ? "Latest: " + (latest.name ?? "unbound caller") + " " + (latest.preview ?? latest.command ?? latest.state) + " [" + latest.state + "]" : "Waiting for the first reported operation.")
-  ];
-  for (const event of history.slice(-(result.storyDepth ?? 2))) lines.push("  " + event.at.slice(11,19) + "Z  " +
-    (event.name ?? "unbound") + " > " + (event.preview ?? event.command ?? event.state) + " > " + event.state.toUpperCase() +
-    (event.durationMs != null ? " (" + event.durationMs + "ms)" : "") + (event.code ? " " + event.code : ""));
-  return lines;
-}
-
-export function formatMonitor(result, columns = process.stdout.columns ?? 120, height = 40, color = false) {
-  const width = Math.max(1, Math.min(160, Number.isFinite(columns) ? Math.floor(columns) : 120));
-  height = Math.max(1, Number.isFinite(height) ? Math.floor(height) : 40);
-  const live = result.instances.filter(instance => instance.running && ["starting", "connecting", "connected"].includes(instance.connection));
-  const pcs = new Map();
-  const mcp = (result.mcp?.instances ?? []).filter(instance => instance.running);
-  const mcpMetrics = mcp.flatMap(instance => instance.metrics);
-  const mcpCalls = mcp.flatMap(instance => instance.calls);
-  const queued = mcp.reduce((sum, instance) => sum + (instance.queue ?? 0), 0);
-  const errors = mcpMetrics.reduce((sum, item) => sum + item.errors, 0);
-  for (const instance of result.instances.filter(item => item.running && (item.computer || item.connection !== "stale")).sort((a, b) => a.instanceId.localeCompare(b.instanceId))) {
-    const name = instance.computer ?? "unknown";
-    if (!pcs.has(name)) pcs.set(name, []);
-    pcs.get(name).push(instance);
-  }
-  // An unused registration or empty idle slot is not a reported agent at work.
-  const agents = (result.activity?.rows ?? []).filter(row => row.kind === "host" ||
-    row.state !== "REGISTERED" && !!row.activity?.trim() &&
-    !(row.phase === "idle" && row.activity === "presence reported; no activity supplied"));
-  for (const agent of agents) if (!pcs.has(agent.computer)) pcs.set(agent.computer, []);
-  for (const instance of mcp) if (!pcs.has(instance.computer)) pcs.set(instance.computer, []);
-  const agentCount = agents.filter(row => row.kind === "agent").length;
-  const hostCount = agents.filter(row => row.kind === "host").length;
-  const agentUnavailable = result.activity?.unavailable.some(source => ["presence", "workers", "state_directory"].includes(source));
-  const agentSummary = agentUnavailable ? agentCount ? agentCount + " known agent records" : "agent records unavailable" : agentCount + " agent records";
-  const hostSummary = result.activity?.unavailable.some(source => source.startsWith("hosts")) ? "hosts unavailable" : hostCount + " observed hosts";
-  const active = instance => instance.executions.filter(row => ["requested", "prepared", "accepted", "running"].includes(row.state));
-  const jobs = live.reduce((sum, instance) => sum + active(instance).length, 0) + mcpCalls.filter(row => row.state === "running").length + mcp.reduce((sum, instance) => sum + instance.processes.length, 0);
-  const stats = live.map(instance => instance.efficiency).filter(Boolean);
-  const saved = stats.reduce((sum, item) => sum + item.savedBytes, 0);
-  const sent = stats.reduce((sum, item) => sum + item.models.reduce((bytes, group) => bytes + group.sentBytes, 0), 0);
-  const tokens = bytes => "~" + Math.round(bytes / 4).toLocaleString("en-US");
-  const usageSummary = rows => {
-    const sum = field => rows.reduce((total, row) => total + row[field], 0), calls = sum("calls");
-    return calls + " calls | avg " + (calls ? Math.round(sum("durationMs") / calls) + "ms" : "n/a") +
-      " | output " + compact(sum("outputBytes")) + "B | sent " + compact(sum("sentBytes")) + "B | errors " + sum("errors");
-  };
-  const pair = (left, right) => fit(left, Math.max(0, width - right.length - 1)) + " " + right;
-  const lines = [pair("LC >_  Local Commander MCP", "LIVE MONITOR"), "-".repeat(width), "> fleet status", ""];
-  const connected = [...pcs].filter(([name, instances]) => instances.some(instance => instance.connection === "connected") || mcp.some(instance => instance.computer === name)).length;
-  if (height >= 36 && width >= 60) lines.push(
-    "+-------------+   " + connected + " PCs reporting",
-    "| >_ " + fit(jobs ? "RUNNING" : agents.length ? "OBSERVING" : connected ? "READY" : "WAITING", 9) + "|   " + jobs + " active commands",
-    "| LC >_       |   " + agentSummary + " | " + hostSummary,
-    "+-------------+   Queue: " + (mcp.length ? queued : "n/a") + " | MCP errors: " + (mcp.length ? errors : "n/a"),
-    "      ||",
-    "   ___||___", "");
-  else lines.push(connected + " PCs connected | " + jobs + " calls | queue " + (mcp.length ? queued : "n/a") + " | errors " + (mcp.length ? errors : "n/a"), "");
-
-  const body = [];
-  let shown = 0, shownPcs = 0, shownAgents = 0;
-  const footer = [
-    "-".repeat(width),
-    ...formatLifetimeSavings(result),
-    stats.length ? "Native this run - Raw: " + tokens(saved + sent) + " tokens   Sent: " + tokens(sent) + "   Saved: " + tokens(saved) +
-      "  " + (saved + sent ? Math.round(100 * saved / (saved + sent)) : 0) + "%" + (stats.length < live.length ? " (partial)" : "") :
-      "Native this run - Raw: n/a   Sent: n/a   Saved: n/a",
-    mcp.length ? "MCP this run: " + usageSummary(mcpMetrics) + " | saved stdout " + tokens(mcpMetrics.reduce((sum, row) => sum + row.savedBytes, 0)) + " tok" :
-      "~ Tokens: bytes / 4, this run | model: declared or not reported",
-    mcpMetrics.length ? "Review: " + [...mcpMetrics].sort((a, b) => b.sentBytes - a.sentBytes).slice(0, 2)
-      .map(row => row.tool + " " + compact(row.sentBytes) + "B / " + row.calls + " calls / " + Math.round(row.durationMs / Math.max(1, row.calls)) + "ms avg").join(" | ") :
-      "Server: " + ([...new Set(live.map(instance => instance.origin).filter(Boolean))].join(", ") || "not connected"),
-    "Space freeze/resume | Tab focus PC | A all PCs | L timeline | Ctrl+C exit" +
-      (result.mcp?.unavailable ? " | MCP snapshots unavailable: " + result.mcp.unavailable : "") +
-      (result.activity?.unavailable.length ? " | unavailable: " + result.activity.unavailable.join(",") : "")
-  ];
-  if (height >= 30 && width >= 60) footer.unshift(...storyLines(result, result.focusComputer));
-  const capacity = Math.max(0, height - lines.length - footer.length - 1);
-  for (const [name, instances] of [...pcs].filter(([name]) => !result.focusComputer || name === result.focusComputer).sort(([a], [b]) => a.localeCompare(b))) {
-    const pcStats = instances.filter(instance => live.includes(instance)).map(instance => instance.efficiency).filter(Boolean);
-    const pcMcp = mcp.filter(instance => instance.computer === name);
-    const pcSaved = pcStats.length || pcMcp.length ? tokens(pcStats.reduce((sum, item) => sum + item.savedBytes, 0) + pcMcp.flatMap(instance => instance.metrics).reduce((sum, row) => sum + row.savedBytes, 0)) : "n/a";
-    const executions = new Map(instances.flatMap(instance => instance.executions).map(row => [row.executionId, row]));
-    const latest = instances.flatMap(instance => instance.events.filter(event => ["finished", "failed", "cancelled", "unknown"].includes(event.event)))
-      .sort((a, b) => b.at.localeCompare(a.at))[0];
-    const recent = latest && executions.get(latest.executionId);
-    const pcUsage = pcMcp.flatMap(instance => instance.agents);
-    const usageFor = runtimeId => pcUsage.filter(row => row.runtimeId === runtimeId);
-    const savingsFor = runtimeId => {
-      const rows = usageFor(runtimeId);
-      return rows.length ? Math.round(rows.reduce((sum, row) => sum + row.savedBytes, 0) / 4) : null;
-    };
-    const mcpRecent = pcMcp.flatMap(instance => instance.events).sort((a, b) => b.at.localeCompare(a.at))[0];
-    const mcpError = pcMcp.flatMap(instance => instance.events).filter(event => event.state === "failed").sort((a, b) => b.at.localeCompare(a.at))[0];
-    const mcpMessage = pcMcp.flatMap(instance => instance.events).filter(event => event.tool === "agent_message").sort((a, b) => b.at.localeCompare(a.at))[0];
-    const statusLines = [
-      "  Health: " + (instances.map(i => "relay " + i.connection.toUpperCase()).join(", ") || "relay not observed") +
-        (result.health ? " | MCP " + result.health.state + (result.health.status ? " HTTP " + result.health.status : "") + " @ " + result.health.at.slice(11, 19) + "Z" : " | MCP probe not run"),
-      ...(pcStats.length ? ["  Native: " + pcStats.reduce((sum, item) => sum + item.calls, 0) +
-        " measured calls | status polls " + pcStats.reduce((sum, item) => sum + item.polls.status, 0) +
-        " | output polls " + pcStats.reduce((sum, item) => sum + item.polls.output, 0) +
-        " | sessions " + instances.filter(instance => live.includes(instance)).reduce((sum, item) => sum + item.sessions.length, 0)] : []),
-      ...(pcMcp.length ? ["  Diagnostics: queue " + pcMcp.reduce((s,i) => s + (i.queue ?? 0), 0) + " | write errors " +
-        pcMcp.reduce((s,i) => s + i.writeErrors, 0) + " | dropped " + pcMcp.reduce((s,i) => s + i.dropped, 0)] : []),
-      ...(recent ? ["  Last: " + latest.at.slice(11, 19) + "Z " + recent.executionId.slice(0, 8) + " " + (recent.preview ?? recent.command) + " " + recent.state.toUpperCase()] : []),
-      ...(mcpRecent ? ["  MCP last: " + mcpRecent.at.slice(11, 19) + "Z " + (mcpRecent.name ?? "unbound") + " " + (mcpRecent.preview ?? mcpRecent.command) + " " + mcpRecent.state.toUpperCase()] : []),
-      ...(mcpError ? [ "  Last error: " + mcpError.at.slice(11, 19) + "Z " + (mcpError.preview ?? mcpError.command) + " " + mcpError.code] : []),
-      ...(mcpMessage && mcpMessage !== mcpRecent ? ["  Message: " + (mcpMessage.name ?? "unbound") + " " + mcpMessage.command + " | task " + (mcpMessage.context.taskId ?? "unreported")] : [])
-    ];
-    const rowCapacity = capacity - statusLines.length;
-    const pcAgents = agents.filter(agent => agent.computer === name);
-    const rows = [
-      ...pcMcp.flatMap(instance => instance.processes.map(row => ({ executionId: "process:" + row.id,
-        displayId: row.agent?.name ?? row.id.slice(0, 8), kind: "call", pid: row.pid, order: "0:process:" + row.id,
-        command: row.preview ?? row.command, context: row.context, state: "running", profile: row.agent?.model ? { model: row.agent.model } : null, estimatedSavedTokens: null }))),
-      ...pcMcp.flatMap(instance => instance.calls.map(call => ({ executionId: "mcp:" + instance.instanceId + ":" + call.id,
-        displayId: call.agent?.name ?? ("mcp" + call.id).slice(0, 8).padEnd(8), kind: "call", pid: instance.pid,
-        order: "0:" + String(call.id).padStart(12, "0"), command: (call.agent ? "" : "unbound: ") + (call.preview ?? call.command),
-        state: call.state, profile: call.agent?.model ? { model: call.agent.model } : null, estimatedSavedTokens: call.agent ? savingsFor(call.agent.runtimeId) : null,
-        detail: [call.context.taskId && "task " + call.context.taskId, call.context.pr && "PR #" + call.context.pr + (call.context.inferred ? " (path)" : ""),
-          call.context.project && "project " + call.context.project, call.agent?.phase === "analysis" && "analysis (reported)",
-          "queue " + (instance.queue ?? "n/a"), call.context.directory && "dir " + call.context.directory].filter(Boolean).join(" | ") }))),
-      ...pcAgents.flatMap(agent => {
-        const measured = agent.executionIds.map(id => executions.get(id)).filter(row => row?.estimatedSavedTokens !== null && row?.estimatedSavedTokens !== undefined);
-        const linked = agent.executionIds.map(id => executions.get(id)).filter(Boolean);
-        const running = linked.find(row => ["requested", "prepared", "accepted", "running"].includes(row.state));
-        const usage = usageFor(agent.id);
-        return [{ executionId: agent.id, displayId: agent.name, kind: agent.kind, pid: agent.pid,
-          order: (agent.kind === "host" ? "3:" : "2:") + agent.id,
-          command: (agent.phase === "analysis" ? "analysis (reported): " : "") + agent.activity,
-          detail: [agent.context?.taskId && "task " + agent.context.taskId,
-            agent.context?.pr && "PR #" + agent.context.pr, agent.unread > 0 && "messages " + agent.unread,
-            usage.length && usageSummary(usage), agent.context?.directory && "dir " + agent.context.directory].filter(Boolean).join(" | "),
-          state: running?.state ?? (agent.state === "RUNNING" ? "REPORTED" : agent.state),
-          profile: agent.model ? { model: agent.model } : null,
-          estimatedSavedTokens: measured.length || usage.length ? Math.round((measured.reduce((sum, row) => sum + row.savedBytes, 0) + usage.reduce((sum, row) => sum + row.savedBytes, 0)) / 4) : null,
-          partial: measured.length > 0 && measured.length < agent.executionIds.length },
-          ...linked.filter(row => ["requested", "prepared", "accepted", "running"].includes(row.state))
-            .map(row => ({ ...row, command: "-> " + (row.preview ?? row.command), order: "1:" + agent.id + ":work:" + row.executionId }))];
-      }),
-      ...instances.flatMap(active).filter(row => !pcAgents.some(agent => agent.executionIds.includes(row.executionId))).map(row => ({ ...row, command: row.preview ?? row.command }))
-    ];
-    const state = instances.some(instance => active(instance).length) || pcMcp.some(instance => instance.calls.length) ? "RUNNING" : pcAgents.length || pcMcp.length ? "OBSERVING" :
-      instances.some(instance => instance.connection === "connected") ? "READY" : instances[0]?.connection.toUpperCase() ?? "OBSERVING";
-    // Keep each process with its PC heading, including in a short terminal.
-    if (rowCapacity - body.length < (rows.length ? width < 60 ? 5 : 4 : 3)) break;
-    body.push(pair("PC " + name + "  |  saved " + pcSaved + " tokens", state));
-    shownPcs++;
-    if (rows.length) {
-      if (width >= 100) body.push("  " + fit("AGENT/ID", 8) + "  " + fit("PID", 7) + "  " + fit("DOING", width - 71) +
-        "  " + fit("MODEL", 24) + "  " + fit("SAVED TOK", 10, true) + "  STATE");
-      for (const row of rows.sort((a, b) => (a.order ?? "1:" + a.executionId).localeCompare(b.order ?? "1:" + b.executionId))) {
-        const id = row.displayId ?? row.executionId.slice(0, 8), model = row.profile?.model ?? (row.kind === "host" ? "process only" : "not reported");
-        const saving = row.estimatedSavedTokens === null ? "n/a" : "~" + compact(row.estimatedSavedTokens) + (row.partial ? "+" : "");
-        const entry = width >= 100 ? ["  " + fit(id, 8) + "  " + fit(row.pid ?? "-", 7, true) + "  " + fit(row.command, width - 71) +
-          "  " + fit(model, 24) + "  " + fit(saving, 10, true) + "  " + fit(row.state.toUpperCase(), 10)] : [
-          pair("  " + id + "  " + row.command, row.state.toUpperCase()),
-          ...(width >= 60 ? ["    PID " + (row.pid ?? "-") + " | model " + fit(model, width - 51).trimEnd() + " | saved " + saving + " tok"] :
-            ["    model " + model, "    PID " + (row.pid ?? "-") + " | saved " + saving + " tok"])
-        ];
-        const context = row.context;
-        const detail = row.detail || (context ? [context.taskId && "task " + context.taskId,
-          context.pr && "PR #" + context.pr, context.directory && "dir " + context.directory].filter(Boolean).join(" | ") : "");
-        if (detail) entry.push("    " + detail);
-        if (body.length + entry.length + 1 > rowCapacity) break;
-        body.push(...entry);
-        if (row.kind && row.kind !== "call") shownAgents++;
-        else shown++;
-      }
-    } else body.push("  Waiting for work");
-    for (const line of statusLines) if (body.length + 2 <= capacity) body.push(line);
-    body.push("");
-  }
-  if (!pcs.size) body.push(result.instances.length ? "No live PC reported. See logs for completed work and connection history." :
-    "No monitoring snapshots. Update/start a monitoring-capable agent.");
-  lines.push(...body.slice(0, capacity));
-  while (lines.length < height - footer.length - 1) lines.push("");
-  lines.push((jobs > shown ? (jobs - shown) + " more active commands | " : "") +
-    (agents.length > shownAgents ? (agents.length - shownAgents) + " more agents/hosts | " : "") +
-    (pcs.size > shownPcs ? (pcs.size - shownPcs) + " more PCs | " : "") +
-    "Unavailable/stale/stopped snapshots: " + (result.unavailable + result.instances.length - live.length));
-  lines.push(...footer);
-  // Paint after clipping so ANSI sequences never count toward the terminal width.
-  return lines.slice(0, height).map(line => {
-    const text = fit(line, width);
-    if (!color) return text.trimEnd();
-    const cyan = /^LC |^> |^PC |^[+|]|^\s+[_|]/.test(line);
-    return "\x1b[48;2;15;23;42m\x1b[38;2;" + (cyan ? "0;255;213" : "191;219;254") + "m" +
-      text.replace(/\b(RUNNING|READY|CONNECTED|OBSERVING|OBSERVED|REPORTING|QUEUED|FAILED)\b|Saved:.*$/g, value =>
-        "\x1b[38;2;" + (value === "FAILED" ? "248;113;113" : value === "QUEUED" ? "251;191;36" : "0;255;213") + "m" + value + "\x1b[38;2;191;219;254m") + "\x1b[0m";
-  }).join("\n") + "\n";
-}
-
-export function formatInsights(result) {
-  const lines = ["OUTPUT TO REVIEW (recent measured bytes; potential savings unproven):"];
-  const candidates = result.instances.flatMap(instance => instance.executions.filter(row => row.sentBytes > 0)
-    .map(row => ({ ...row, computer: instance.computer ?? "unknown" })))
-    .sort((a, b) => b.sentBytes - a.sentBytes).slice(0, 5);
-  if (!candidates.length) lines.push("  No measured output candidates yet.");
-  for (const row of candidates) lines.push("  " + row.computer + " " + row.executionId.slice(0, 8) + " " + row.command + " | " + compact(row.sentBytes) +
-    " B sent | " + (row.reason ?? "unknown") + " | " +
-    (row.reason === "validated_compact" ? "already compacted; review remaining detail" :
-      row.name === "fs_read" ? "request a focused line range" : row.name === "fs_search" ? "narrow query and maxResults" :
-        "review command verbosity; preserve failures/warnings"));
-  for (const instance of result.instances) {
-    const stats = instance.efficiency;
-    if (stats && stats.polls.status + stats.polls.output >= 10) lines.push("POLLING: " + stats.polls.status + " status / " + stats.polls.output +
-      " output calls on " + (instance.computer ?? "unknown") + "; wait between polls and fetch final output once when practical.");
-  }
-  for (const instance of (result.mcp?.instances ?? []).filter(item => item.running)) {
-    lines.push("MCP " + instance.computer + " | queue " + (instance.queue ?? "n/a") + " | diagnostics writes " + instance.writes +
-      " | write errors " + instance.writeErrors + " | dropped observations " + instance.dropped);
-    for (const row of [...instance.metrics].sort((a, b) => b.sentBytes - a.sentBytes).slice(0, 5)) {
-      lines.push("  " + row.tool + ": " + row.calls + " calls | " + row.errors + " errors | " + row.sentBytes + "B responses | " + row.outputBytes +
-        "B output | saved stdout ~" + Math.round(row.savedBytes / 4) + " tok | " + Math.round(row.durationMs / Math.max(1, row.calls)) + "ms avg");
-      if (["process_output", "scheduler_status", "agent_monitor"].includes(row.tool) && row.calls >= 10) lines.push("    Repeated polling: wait between polls; fetch the final result once when practical.");
-      if (row.sentBytes > 16_384) lines.push("    Review " + (row.tool === "fs_read" ? "line range" : row.tool === "fs_search" ? "query/maxResults" : "verbosity") + "; preserve exit status, errors, warnings and required detail.");
-    }
-  }
-  return lines.join("\n") + "\n";
-}
-
-// Fixed cursor positions: rewrite changed lines only, with no clear/redraw or scrolling.
-export function monitorFrame(previous, next, maxRows = Infinity) {
-  const before = previous ? previous.trimEnd().split("\n") : [];
-  const after = next.trimEnd().split("\n");
-  let output = "";
-  for (let index = 0; index < Math.min(maxRows, Math.max(before.length, after.length)); index++) {
-    if (before[index] !== after[index]) output += "\x1b[" + (index + 1) + ";1H\x1b[2K" + (after[index] ?? "");
-  }
-  return output;
-}
-
-export async function runMonitor(directory, command, args) {
-  const allowed = command === "logs" ? ["--follow"] : ["--watch", "--json"];
-  if (new Set(args).size !== args.length || args.some(arg => !allowed.includes(arg))) throw Error("ARGUMENT_INVALID");
-  const repeat = args.includes("--watch") || args.includes("--follow");
-  const stop = new AbortController();
-  const abort = () => stop.abort();
-  process.once("SIGINT", abort);
-  process.once("SIGTERM", abort);
-  const seen = new Map();
-  const previousHosts = new Map();
-  const fixedScreen = command === "monitor" && repeat && process.stdout.isTTY && !args.includes("--json");
-  let previous = "", previousSize = "", initial = true, insightCheckpoint = "";
-  let paused = false, latestResult, focusComputer = null, storyDepth = 2;
-  const interactive = fixedScreen && process.stdin.isTTY && typeof process.stdin.setRawMode === "function";
-  const wasRaw = process.stdin.isRaw, wasPaused = process.stdin.isPaused();
-  const input = chunk => {
-    const key = chunk.toString().toLowerCase();
-    if (key === "\u0003" || key === "q") stop.abort();
-    else if (key === " ") paused = !paused;
-    else if (key === "a") focusComputer = null;
-    else if (key === "l") storyDepth = storyDepth === 2 ? 5 : 2;
-    else if (key === "\t" && latestResult) {
-      const computers = [...new Set([...latestResult.instances.map(i => i.computer),
-        ...latestResult.mcp.instances.map(i => i.computer), ...(latestResult.activity?.rows ?? []).map(i => i.computer)].filter(Boolean))].sort();
-      focusComputer = computers[(computers.indexOf(focusComputer) + 1) % computers.length] ?? null;
-    }
-  };
-  if (interactive) { process.stdin.setRawMode(true); process.stdin.on("data", input); process.stdin.resume(); }
-  if (fixedScreen) process.stdout.write("\x1b[?1049h\x1b[?25l");
-  try {
-    do {
-      const result = paused && latestResult ? latestResult : await readMonitors(directory);
-      if (!(paused && latestResult)) {
-        result.mcp = await readMcpActivity();
-        result.health = await readMcpHealth();
-        if (command === "monitor") result.activity = await readAgentActivity(directory, { previousHosts, signal: stop.signal });
-        latestResult = result;
-      }
-      result.paused = paused; result.focusComputer = focusComputer; result.storyDepth = storyDepth;
-      if (command === "logs" && (result.instances.length || result.mcp.instances.length)) {
-        const checkpoint = result.mcp.instances.map(instance => instance.instanceId + ":" + Math.floor(instance.metrics.reduce((sum, row) => sum + row.calls, 0) / 5)).join(",");
-        if (initial || checkpoint !== insightCheckpoint) { process.stdout.write(formatInsights(result)); insightCheckpoint = checkpoint; }
-        for (const instance of result.instances) {
-          const after = seen.get(instance.instanceId) ?? 0;
-          if (after && instance.events[0]?.seq > after + 1) process.stdout.write("Earlier events were overwritten in the 100-event buffer.\n");
-          for (const event of instance.events) if (event.seq > after && !["status", "output"].includes(event.event)) process.stdout.write(logLine(instance, event) + "\n");
-          seen.set(instance.instanceId, instance.events.at(-1)?.seq ?? after);
-        }
-        for (const instance of result.mcp.instances) {
-          const key = "mcp:" + instance.instanceId;
-          const transitionsKey = key + ":starts";
-          const afterStart = seen.get(transitionsKey) ?? 0;
-          for (const event of instance.transitions ?? []) if (event.seq > afterStart) {
-            process.stdout.write([event.at, "pc=" + instance.computer, "agent=" + (event.name ?? "unbound"), event.preview, "RUNNING",
-              "model=" + (event.model ?? "not_reported"), event.context.directory && "dir=" + event.context.directory,
-              event.context.taskId && "task=" + event.context.taskId].filter(Boolean).join(" ") + "\n");
-          }
-          seen.set(transitionsKey, instance.transitions?.at(-1)?.seq ?? afterStart);
-          // Request IDs finish out of order: a per-event key tracks actual completions, not numeric high-water IDs.
-          for (const event of instance.events) {
-            const eventKey = key + ":" + event.id;
-            if (seen.has(eventKey)) continue;
-            process.stdout.write([event.at, "pc=" + instance.computer, "agent=" + (event.name ?? "unbound"), event.preview ?? event.command, event.state, "model=" + (event.model ?? "not_reported"),
-              "elapsed=" + event.durationMs + "ms", event.exitCode !== null && "exit=" + event.exitCode, event.timedOut && "timeout=true",
-              event.code, event.context.directory && "dir=" + event.context.directory, event.context.taskId && "task=" + event.context.taskId,
-              event.context.pr && "PR=" + event.context.pr, "sent=" + event.sentBytes + "B", "saved=~" + Math.round(event.savedBytes / 4) + "tok"].filter(Boolean).join(" ") + "\n");
-            seen.set(eventKey, 1);
-          }
-          for (const seenKey of seen.keys()) if (seenKey.startsWith(key + ":") && seenKey !== transitionsKey && !instance.events.some(event => seenKey === key + ":" + event.id)) seen.delete(seenKey);
-        }
-        for (const key of seen.keys()) if (!result.instances.some(instance => instance.instanceId === key) &&
-          !result.mcp.instances.some(instance => key.startsWith("mcp:" + instance.instanceId + ":"))) seen.delete(key);
-        if (result.unavailable) process.stderr.write("Some monitoring snapshots are unavailable.\n");
-      } else {
-        const columns = Math.max(1, (process.stdout.columns ?? 120) - 1);
-        const rows = Math.max(1, (process.stdout.rows ?? 40) - 1);
-        const size = columns + "x" + rows;
-        // A resized terminal must repaint even when the snapshot is unchanged.
-        if (fixedScreen && size !== previousSize) previous = "";
-        const next = args.includes("--json") ? JSON.stringify(result) + "\n" :
-          formatMonitor(result, fixedScreen ? columns : undefined, fixedScreen ? rows : undefined,
-            process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb");
-        process.stdout.write(fixedScreen ? monitorFrame(previous, next, Math.max(1, (process.stdout.rows ?? 40) - 1)) : next);
-        previous = next;
-        previousSize = size;
-      }
-      initial = false;
-      if (repeat) await delay(2000, undefined, { signal: stop.signal }).catch(error => { if (error.name !== "AbortError") throw error; });
-    } while (repeat && !stop.signal.aborted);
-  } finally {
-    if (interactive) { process.stdin.removeListener("data", input); process.stdin.setRawMode(!!wasRaw); if (wasPaused) process.stdin.pause(); }
-    if (fixedScreen) process.stdout.write("\x1b[0m\x1b[?25h\x1b[?1049l");
-    process.removeListener("SIGINT", abort);
-    process.removeListener("SIGTERM", abort);
-  }
-}
+import { lstat, open, readFile, readdir } from "node:fs/promises";
+import { lifetimeSavingsView, formatLifetimeSavings } from "./monitor-savings.mjs";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { readAgentActivity } from "./monitor-agents.mjs";
+import { readMcpActivity, readMcpHealth, contextView } from "./monitor-mcp.mjs";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const STATES = new Set(["starting", "connecting", "connected", "disconnected", "stopped", "failed"]);
+const EVENTS = new Set([...STATES, "execute", "prepare", "status", "output", "cancel", "finished", "cancelled", "unknown", "result", "request_failed", "rejected", "connection_error", "compacted", "passthrough"]);
+const iso = value => typeof value === "string" && /^\d{4}-\d\d-\d\dT[\d:.]+Z$/.test(value) && Number.isFinite(Date.parse(value));
+const invalid = () => { throw Error("MONITOR_DATA_INVALID"); };
+const count = value => Number.isSafeInteger(value) && value >= 0 && value <= 1_000_000_000_000;
+const label = value => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,79}$/.test(value);
+const EXECUTION_STATES = new Set(["requested", "prepared", "accepted", "running", "finished", "failed", "cancelled", "rejected", "unknown", "missing"]);
+const PROCESS_NAMES = new Set(["node", "npm", "npx", "git", "rg", "powershell", "pwsh", "cmd", "tsc", "python", "dotnet", "command",
+  "fs_list", "fs_read", "fs_search", "fs_write", "fs_replace", "git_status", "git_diff", "git_log", "project_snapshot", "localhost_request"]);
+const COMMANDS = new Set(["node --test", ...["status", "diff", "log", "show", "fetch", "pull", "push", "commit"].map(value => "git " + value),
+  ...["test", "install", "ci", "pack", "publish"].map(value => "npm " + value),
+  ...["test", "build", "typecheck", "lint", "dev", "start"].map(value => "npm run " + value),
+  ...[...PROCESS_NAMES].flatMap(value => [value, value + " [args]"])]);
+function profileView(raw) {
+  if (raw === null) return null;
+  if (!raw || !label(raw.model)) invalid();
+  return { model: raw.model };
+}
+function efficiencyView(raw) {
+  if (raw === undefined) return null; // Older agents did not measure monitor savings.
+  if (!raw || raw.scope !== "this_run" || !count(raw.calls) || !count(raw.polls?.status) || !count(raw.polls?.output) ||
+      !Array.isArray(raw.models) || raw.models.length > 32) invalid();
+  const models = raw.models.map(group => {
+    if (!group || (group.model !== null && !label(group.model)) || !count(group.calls) || !count(group.savedBytes) || !count(group.sentBytes)) invalid();
+    return { model: group.model, calls: group.calls, savedBytes: group.savedBytes,
+      sentBytes: group.sentBytes, estimatedSavedTokens: Math.round(group.savedBytes / 4) };
+  });
+  if (models.reduce((sum, group) => sum + group.calls, 0) !== raw.calls) invalid();
+  const savedBytes = models.reduce((sum, group) => sum + group.savedBytes, 0);
+  return { scope: "this_run", calls: raw.calls, polls: { status: raw.polls.status, output: raw.polls.output }, models,
+    savedBytes, estimatedSavedTokens: Math.round(savedBytes / 4),
+    unclassifiedSavedBytes: models.filter(group => group.model === null).reduce((sum, group) => sum + group.savedBytes, 0) };
+}
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code === "EPERM"; }
+}
+
+// Explicit allowlist projection: never print extra fields from a local file.
+export function monitorView(raw, now = Date.now(), alive = pidAlive, transport = null) {
+  if (!raw || raw.schemaVersion !== 1 || !UUID.test(raw.instanceId) || !Number.isSafeInteger(raw.pid) || raw.pid <= 0 ||
+      typeof raw.agentVersion !== "string" || !/^[A-Za-z0-9._+-]{1,64}$/.test(raw.agentVersion) || !iso(raw.updatedAt) ||
+      !STATES.has(raw.connection?.state) || !Array.isArray(raw.sessions) || raw.sessions.length > 32 ||
+      !Array.isArray(raw.events) || raw.events.length > 100) invalid();
+  let origin = null;
+  if (raw.connection.origin !== null) {
+    const url = new URL(raw.connection.origin);
+    if (url.origin !== raw.connection.origin || url.username || url.password ||
+        !(url.protocol === "https:" || (url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname)))) invalid();
+    origin = url.origin;
+  }
+  const sessions = raw.sessions.map(session => {
+    if (!session || !UUID.test(session.sessionId) || !UUID.test(session.workspaceGrantId) || !iso(session.lastSeenAt)) invalid();
+    return { sessionId: session.sessionId, workspaceGrantId: session.workspaceGrantId, lastSeenAt: session.lastSeenAt, model: null };
+  });
+  const events = raw.events.map(event => {
+    if (!event || !Number.isSafeInteger(event.seq) || event.seq < 1 || !iso(event.at) || !EVENTS.has(event.event) ||
+        (event.sessionId !== undefined && !UUID.test(event.sessionId)) || (event.executionId !== undefined && !UUID.test(event.executionId)) ||
+        (event.tool !== undefined && (typeof event.tool !== "string" || !/^[a-z_]{1,64}$/.test(event.tool))) ||
+        (event.code !== undefined && (typeof event.code !== "string" || !/^[A-Z0-9_]{1,64}$/.test(event.code)))) invalid();
+    return { seq: event.seq, at: event.at, event: event.event,
+      ...(event.sessionId ? { sessionId: event.sessionId } : {}), ...(event.executionId ? { executionId: event.executionId } : {}),
+      ...(event.tool ? { tool: event.tool } : {}), ...(event.code ? { code: event.code } : {}) };
+  });
+  const running = alive(raw.pid);
+  if (raw.transportAt !== undefined && !iso(raw.transportAt)) invalid();
+  // A heartbeat file counts only for this snapshot's instance and connection (#31).
+  const heartbeat = raw.transportAt !== undefined && transport?.instanceId === raw.instanceId && transport.epoch === raw.connection.epoch &&
+    iso(transport.transportAt) && Date.parse(transport.transportAt) > Date.parse(raw.transportAt) ? transport.transportAt : raw.transportAt;
+  const age = now - Date.parse(raw.connection.state === "connected" ? heartbeat ?? raw.updatedAt : raw.updatedAt);
+  const freshnessMs = raw.freshnessMs ?? 10_000;
+  if (!Number.isInteger(freshnessMs) || freshnessMs < 1000 || freshnessMs > 180_000) invalid();
+  const connection = !running ? "stopped" : age < -5000 || age > freshnessMs ? "stale" : raw.connection.state;
+  if (raw.computer !== undefined && (typeof raw.computer !== "string" || !/^[A-Za-z0-9._-]{1,64}$/.test(raw.computer))) invalid();
+  if (raw.processName !== undefined && raw.processName !== "lc-agent") invalid();
+  if (raw.executions !== undefined && (!Array.isArray(raw.executions) || raw.executions.length > 64)) invalid();
+  const executions = (raw.executions ?? []).map(execution => {
+    if (!execution || !UUID.test(execution.executionId) || !UUID.test(execution.sessionId) || !PROCESS_NAMES.has(execution.name) ||
+        !COMMANDS.has(execution.command) || !EXECUTION_STATES.has(execution.state) ||
+        (execution.pid !== null && (!Number.isSafeInteger(execution.pid) || execution.pid <= 0)) ||
+        ![execution.originalBytes, execution.sentBytes, execution.savedBytes].every(value => value === null || count(value)) ||
+        (execution.reason !== null && (typeof execution.reason !== "string" || !/^[a-z_]{1,80}$/.test(execution.reason)))) invalid();
+    const measured = execution.originalBytes !== null;
+    if (measured ? execution.sentBytes === null || execution.savedBytes === null || execution.sentBytes > execution.originalBytes ||
+        execution.savedBytes !== execution.originalBytes - execution.sentBytes : execution.sentBytes !== null || execution.savedBytes !== null) invalid();
+    if (execution.preview !== undefined && (typeof execution.preview !== "string" || execution.preview.length > 240 || /[\u0000-\u001f\u007f-\u009f]/u.test(execution.preview))) invalid();
+    for (const field of ["startedAt", "endedAt"]) if (execution[field] !== undefined && execution[field] !== null && (!Number.isSafeInteger(execution[field]) || execution[field] < 0 || execution[field] > now + 5000)) invalid();
+    if (execution.exitCode !== undefined && execution.exitCode !== null && (!Number.isInteger(execution.exitCode) || Math.abs(execution.exitCode) > 2147483648)) invalid();
+    const profile = profileView(execution.profile);
+    const active = ["requested", "prepared", "accepted", "running"].includes(execution.state);
+    const state = active && connection !== "connected" ? connection === "stale" ? "stale" : "unknown" : execution.state;
+    return { executionId: execution.executionId, sessionId: execution.sessionId, name: execution.name, command: execution.command, preview: execution.preview ?? execution.command,
+      startedAt: execution.startedAt ?? null, endedAt: execution.endedAt ?? null, exitCode: execution.exitCode ?? null, timedOut: execution.timedOut === true, state, pid: execution.pid, profile, context: execution.context === undefined ? null : contextView(execution.context), originalBytes: execution.originalBytes, sentBytes: execution.sentBytes,
+      savedBytes: execution.savedBytes, reason: execution.reason, estimatedSavedTokens: measured ? Math.round(execution.savedBytes / 4) : null };
+  });
+  return { instanceId: raw.instanceId, pid: raw.pid, agentVersion: raw.agentVersion, updatedAt: raw.updatedAt,
+    running, connection, origin, sessions, events, computer: raw.computer ?? null, processName: "lc-agent", executions,
+    efficiency: efficiencyView(raw.efficiency),
+    savingsSourceId: typeof raw.savingsSourceId === "string" && /^[a-f0-9]{64}$/.test(raw.savingsSourceId) ? raw.savingsSourceId : null,
+    lifetimeSavings: lifetimeSavingsView(raw.lifetimeSavings) };
+}
+
+// Relay heartbeats refresh this tiny sibling file instead of rewriting the snapshot (#31). It is advisory.
+async function readTransport(file) {
+  try {
+    const stat = await lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024) return null;
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch { return null; }
+}
+
+export async function readMonitors(directory) {
+  let entries;
+  try {
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) invalid();
+    entries = (await readdir(directory)).filter(name => /^[a-f0-9]{64}\.json$/.test(name));
+  } catch (error) {
+    if (error?.code === "ENOENT") return { instances: [], unavailable: 0 };
+    return { instances: [], unavailable: 1 };
+  }
+  const instances = [];
+  let unavailable = Math.max(0, entries.length - 32);
+  for (const name of entries.slice(0, 32)) {
+    try {
+      const file = path.join(directory, name);
+      const stat = await lstat(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024) invalid();
+      const handle = await open(file, "r");
+      let contents;
+      try {
+        const buffer = Buffer.alloc(128 * 1024 + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > 128 * 1024) invalid();
+        contents = buffer.subarray(0, bytesRead).toString("utf8");
+      } finally { await handle.close(); }
+      instances.push(monitorView(JSON.parse(contents), Date.now(), pidAlive, await readTransport(file.replace(/\.json$/, ".transport"))));
+    } catch { unavailable++; }
+  }
+  instances.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+  return { instances, unavailable };
+}
+
+function logLine(instance, event) {
+  const execution = instance.executions.find(row => row.executionId === event.executionId);
+  return [event.at, "pc=" + (instance.computer ?? "unknown"), "pid=" + instance.pid, event.event, event.tool, event.code,
+    execution && "cmd=" + (execution.preview ?? execution.command),
+    execution?.profile && "model=" + execution.profile.model,
+    execution && ["compacted", "passthrough"].includes(event.event) && "saved=~" + compact(execution.estimatedSavedTokens) +
+      "tok sent=" + execution.sentBytes + "B reason=" + execution.reason,
+    execution?.exitCode !== null && execution?.exitCode !== undefined && "exit=" + execution.exitCode,
+    execution?.timedOut && "timeout=true",
+    execution?.endedAt && execution.startedAt && "elapsed=" + (execution.endedAt - execution.startedAt) + "ms",
+    execution?.context?.directory && "dir=" + execution.context.directory, execution?.context?.taskId && "task=" + execution.context.taskId,
+    event.sessionId && "session=" + event.sessionId.slice(0, 8), event.executionId && "execution=" + event.executionId.slice(0, 8)].filter(Boolean).join(" ");
+}
+
+const compact = value => value === null ? "n/a" : value >= 1e6 ? (value / 1e6).toFixed(1) + "M" : value >= 1000 ? (value / 1000).toFixed(1) + "k" : String(value);
+const graphemes = new Intl.Segmenter("en", { granularity: "grapheme" });
+const cellWidth = text => /^\p{Mark}+$/u.test(text) ? 0 :
+  /[\u1100-\u115f\u2329\u232a\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe10-\ufe19\ufe30-\ufe6f\uff00-\uff60\uffe0-\uffe6\u{20000}-\u{3fffd}]|\p{Emoji_Presentation}|\ufe0f/u.test(text) ? 2 : 1;
+const fit = (value, width, right = false) => {
+  width = Math.max(0, width);
+  const parts = [...graphemes.segment(String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, " "))].map(part => part.segment);
+  const length = parts.reduce((sum, part) => sum + cellWidth(part), 0);
+  const clipped = length > width, limit = clipped && width >= 4 ? width - 3 : width;
+  let text = "", used = 0;
+  for (const part of parts) {
+    const cells = cellWidth(part);
+    if (used + cells > limit) break;
+    text += part; used += cells;
+  }
+  if (clipped && width >= 4) { text += "..."; used += 3; }
+  const padding = " ".repeat(width - used);
+  return right ? padding + text : text + padding;
+};
+
+function storyLines(result, computer) {
+  const personal = (result.mcp?.instances ?? []).filter(i => i.running && (!computer || i.computer === computer));
+  const native = result.instances.filter(i => i.running && (!computer || i.computer === computer));
+  const current = personal.flatMap(i => i.calls).find(c => c.state === "running") ?? personal.flatMap(i => i.calls)[0];
+  const history = [
+    ...personal.flatMap(i => [...(i.transitions ?? []), ...i.events].map(e => ({ ...e, computer: i.computer }))),
+    ...native.flatMap(i => i.events.filter(e => ["execute", "finished", "failed", "cancelled", "unknown"].includes(e.event)).map(e => {
+      const work = i.executions.find(x => x.executionId === e.executionId);
+      return { ...e, computer: i.computer, state: e.event, preview: work?.preview ?? work?.command ?? e.tool,
+        name: work?.executionId.slice(0, 8), context: work?.context, durationMs: work?.endedAt && work.startedAt ? work.endedAt - work.startedAt : null };
+    }))
+  ].sort((a,b) => a.at.localeCompare(b.at));
+  const latest = history.at(-1), context = current?.context ?? latest?.context;
+  const lines = [
+    "INVESTIGATION  " + (computer ?? "all PCs") + (result.paused ? "  [VIEW FROZEN; work continues]" : "  [LIVE]"),
+    "  Task: " + (context?.taskId ?? context?.project ?? "not reported") + (context?.pr ? " | PR #" + context.pr : "") +
+      " | Where: " + (context?.directory ?? "not reported"),
+    "  " + (current ? "Now: " + (current.agent?.name ?? "unbound caller") + " " + (current.preview ?? current.command) + " [" + current.state + "]" :
+      latest ? "Latest: " + (latest.name ?? "unbound caller") + " " + (latest.preview ?? latest.command ?? latest.state) + " [" + latest.state + "]" : "Waiting for the first reported operation.")
+  ];
+  for (const event of history.slice(-(result.storyDepth ?? 2))) lines.push("  " + event.at.slice(11,19) + "Z  " +
+    (event.name ?? "unbound") + " > " + (event.preview ?? event.command ?? event.state) + " > " + event.state.toUpperCase() +
+    (event.durationMs != null ? " (" + event.durationMs + "ms)" : "") + (event.code ? " " + event.code : ""));
+  return lines;
+}
+
+export function formatMonitor(result, columns = process.stdout.columns ?? 120, height = 40, color = false) {
+  const width = Math.max(1, Math.min(160, Number.isFinite(columns) ? Math.floor(columns) : 120));
+  height = Math.max(1, Number.isFinite(height) ? Math.floor(height) : 40);
+  const live = result.instances.filter(instance => instance.running && ["starting", "connecting", "connected"].includes(instance.connection));
+  const pcs = new Map();
+  const mcp = (result.mcp?.instances ?? []).filter(instance => instance.running);
+  const mcpMetrics = mcp.flatMap(instance => instance.metrics);
+  const mcpCalls = mcp.flatMap(instance => instance.calls);
+  const queued = mcp.reduce((sum, instance) => sum + (instance.queue ?? 0), 0);
+  const errors = mcpMetrics.reduce((sum, item) => sum + item.errors, 0);
+  for (const instance of result.instances.filter(item => item.running && (item.computer || item.connection !== "stale")).sort((a, b) => a.instanceId.localeCompare(b.instanceId))) {
+    const name = instance.computer ?? "unknown";
+    if (!pcs.has(name)) pcs.set(name, []);
+    pcs.get(name).push(instance);
+  }
+  // An unused registration or empty idle slot is not a reported agent at work.
+  const agents = (result.activity?.rows ?? []).filter(row => row.kind === "host" ||
+    row.state !== "REGISTERED" && !!row.activity?.trim() &&
+    !(row.phase === "idle" && row.activity === "presence reported; no activity supplied"));
+  for (const agent of agents) if (!pcs.has(agent.computer)) pcs.set(agent.computer, []);
+  for (const instance of mcp) if (!pcs.has(instance.computer)) pcs.set(instance.computer, []);
+  const agentCount = agents.filter(row => row.kind === "agent").length;
+  const hostCount = agents.filter(row => row.kind === "host").length;
+  const agentUnavailable = result.activity?.unavailable.some(source => ["presence", "workers", "state_directory"].includes(source));
+  const agentSummary = agentUnavailable ? agentCount ? agentCount + " known agent records" : "agent records unavailable" : agentCount + " agent records";
+  const hostSummary = result.activity?.unavailable.some(source => source.startsWith("hosts")) ? "hosts unavailable" : hostCount + " observed hosts";
+  const active = instance => instance.executions.filter(row => ["requested", "prepared", "accepted", "running"].includes(row.state));
+  const jobs = live.reduce((sum, instance) => sum + active(instance).length, 0) + mcpCalls.filter(row => row.state === "running").length + mcp.reduce((sum, instance) => sum + instance.processes.length, 0);
+  const stats = live.map(instance => instance.efficiency).filter(Boolean);
+  const saved = stats.reduce((sum, item) => sum + item.savedBytes, 0);
+  const sent = stats.reduce((sum, item) => sum + item.models.reduce((bytes, group) => bytes + group.sentBytes, 0), 0);
+  const tokens = bytes => "~" + Math.round(bytes / 4).toLocaleString("en-US");
+  const usageSummary = rows => {
+    const sum = field => rows.reduce((total, row) => total + row[field], 0), calls = sum("calls");
+    return calls + " calls | avg " + (calls ? Math.round(sum("durationMs") / calls) + "ms" : "n/a") +
+      " | output " + compact(sum("outputBytes")) + "B | sent " + compact(sum("sentBytes")) + "B | errors " + sum("errors");
+  };
+  const pair = (left, right) => fit(left, Math.max(0, width - right.length - 1)) + " " + right;
+  const lines = [pair("LC >_  Local Commander MCP", "LIVE MONITOR"), "-".repeat(width), "> fleet status", ""];
+  const connected = [...pcs].filter(([name, instances]) => instances.some(instance => instance.connection === "connected") || mcp.some(instance => instance.computer === name)).length;
+  if (height >= 36 && width >= 60) lines.push(
+    "+-------------+   " + connected + " PCs reporting",
+    "| >_ " + fit(jobs ? "RUNNING" : agents.length ? "OBSERVING" : connected ? "READY" : "WAITING", 9) + "|   " + jobs + " active commands",
+    "| LC >_       |   " + agentSummary + " | " + hostSummary,
+    "+-------------+   Queue: " + (mcp.length ? queued : "n/a") + " | MCP errors: " + (mcp.length ? errors : "n/a"),
+    "      ||",
+    "   ___||___", "");
+  else lines.push(connected + " PCs connected | " + jobs + " calls | queue " + (mcp.length ? queued : "n/a") + " | errors " + (mcp.length ? errors : "n/a"), "");
+
+  const body = [];
+  let shown = 0, shownPcs = 0, shownAgents = 0;
+  const footer = [
+    "-".repeat(width),
+    ...formatLifetimeSavings(result),
+    stats.length ? "Native this run - Raw: " + tokens(saved + sent) + " tokens   Sent: " + tokens(sent) + "   Saved: " + tokens(saved) +
+      "  " + (saved + sent ? Math.round(100 * saved / (saved + sent)) : 0) + "%" + (stats.length < live.length ? " (partial)" : "") :
+      "Native this run - Raw: n/a   Sent: n/a   Saved: n/a",
+    mcp.length ? "MCP this run: " + usageSummary(mcpMetrics) + " | saved stdout " + tokens(mcpMetrics.reduce((sum, row) => sum + row.savedBytes, 0)) + " tok" :
+      "~ Tokens: bytes / 4, this run | model: declared or not reported",
+    mcpMetrics.length ? "Review: " + [...mcpMetrics].sort((a, b) => b.sentBytes - a.sentBytes).slice(0, 2)
+      .map(row => row.tool + " " + compact(row.sentBytes) + "B / " + row.calls + " calls / " + Math.round(row.durationMs / Math.max(1, row.calls)) + "ms avg").join(" | ") :
+      "Server: " + ([...new Set(live.map(instance => instance.origin).filter(Boolean))].join(", ") || "not connected"),
+    "Space freeze/resume | Tab focus PC | A all PCs | L timeline | Ctrl+C exit" +
+      (result.mcp?.unavailable ? " | MCP snapshots unavailable: " + result.mcp.unavailable : "") +
+      (result.activity?.unavailable.length ? " | unavailable: " + result.activity.unavailable.join(",") : "")
+  ];
+  if (height >= 30 && width >= 60) footer.unshift(...storyLines(result, result.focusComputer));
+  const capacity = Math.max(0, height - lines.length - footer.length - 1);
+  for (const [name, instances] of [...pcs].filter(([name]) => !result.focusComputer || name === result.focusComputer).sort(([a], [b]) => a.localeCompare(b))) {
+    const pcStats = instances.filter(instance => live.includes(instance)).map(instance => instance.efficiency).filter(Boolean);
+    const pcMcp = mcp.filter(instance => instance.computer === name);
+    const pcSaved = pcStats.length || pcMcp.length ? tokens(pcStats.reduce((sum, item) => sum + item.savedBytes, 0) + pcMcp.flatMap(instance => instance.metrics).reduce((sum, row) => sum + row.savedBytes, 0)) : "n/a";
+    const executions = new Map(instances.flatMap(instance => instance.executions).map(row => [row.executionId, row]));
+    const latest = instances.flatMap(instance => instance.events.filter(event => ["finished", "failed", "cancelled", "unknown"].includes(event.event)))
+      .sort((a, b) => b.at.localeCompare(a.at))[0];
+    const recent = latest && executions.get(latest.executionId);
+    const pcUsage = pcMcp.flatMap(instance => instance.agents);
+    const usageFor = runtimeId => pcUsage.filter(row => row.runtimeId === runtimeId);
+    const savingsFor = runtimeId => {
+      const rows = usageFor(runtimeId);
+      return rows.length ? Math.round(rows.reduce((sum, row) => sum + row.savedBytes, 0) / 4) : null;
+    };
+    const mcpRecent = pcMcp.flatMap(instance => instance.events).sort((a, b) => b.at.localeCompare(a.at))[0];
+    const mcpError = pcMcp.flatMap(instance => instance.events).filter(event => event.state === "failed").sort((a, b) => b.at.localeCompare(a.at))[0];
+    const mcpMessage = pcMcp.flatMap(instance => instance.events).filter(event => event.tool === "agent_message").sort((a, b) => b.at.localeCompare(a.at))[0];
+    const statusLines = [
+      "  Health: " + (instances.map(i => "relay " + i.connection.toUpperCase()).join(", ") || "relay not observed") +
+        (result.health ? " | MCP " + result.health.state + (result.health.status ? " HTTP " + result.health.status : "") + " @ " + result.health.at.slice(11, 19) + "Z" : " | MCP probe not run"),
+      ...(pcStats.length ? ["  Native: " + pcStats.reduce((sum, item) => sum + item.calls, 0) +
+        " measured calls | status polls " + pcStats.reduce((sum, item) => sum + item.polls.status, 0) +
+        " | output polls " + pcStats.reduce((sum, item) => sum + item.polls.output, 0) +
+        " | sessions " + instances.filter(instance => live.includes(instance)).reduce((sum, item) => sum + item.sessions.length, 0)] : []),
+      ...(pcMcp.length ? ["  Diagnostics: queue " + pcMcp.reduce((s,i) => s + (i.queue ?? 0), 0) + " | write errors " +
+        pcMcp.reduce((s,i) => s + i.writeErrors, 0) + " | dropped " + pcMcp.reduce((s,i) => s + i.dropped, 0)] : []),
+      ...(recent ? ["  Last: " + latest.at.slice(11, 19) + "Z " + recent.executionId.slice(0, 8) + " " + (recent.preview ?? recent.command) + " " + recent.state.toUpperCase()] : []),
+      ...(mcpRecent ? ["  MCP last: " + mcpRecent.at.slice(11, 19) + "Z " + (mcpRecent.name ?? "unbound") + " " + (mcpRecent.preview ?? mcpRecent.command) + " " + mcpRecent.state.toUpperCase()] : []),
+      ...(mcpError ? [ "  Last error: " + mcpError.at.slice(11, 19) + "Z " + (mcpError.preview ?? mcpError.command) + " " + mcpError.code] : []),
+      ...(mcpMessage && mcpMessage !== mcpRecent ? ["  Message: " + (mcpMessage.name ?? "unbound") + " " + mcpMessage.command + " | task " + (mcpMessage.context.taskId ?? "unreported")] : [])
+    ];
+    const rowCapacity = capacity - statusLines.length;
+    const pcAgents = agents.filter(agent => agent.computer === name);
+    const rows = [
+      ...pcMcp.flatMap(instance => instance.processes.map(row => ({ executionId: "process:" + row.id,
+        displayId: row.agent?.name ?? row.id.slice(0, 8), kind: "call", pid: row.pid, order: "0:process:" + row.id,
+        command: row.preview ?? row.command, context: row.context, state: "running", profile: row.agent?.model ? { model: row.agent.model } : null, estimatedSavedTokens: null }))),
+      ...pcMcp.flatMap(instance => instance.calls.map(call => ({ executionId: "mcp:" + instance.instanceId + ":" + call.id,
+        displayId: call.agent?.name ?? ("mcp" + call.id).slice(0, 8).padEnd(8), kind: "call", pid: instance.pid,
+        order: "0:" + String(call.id).padStart(12, "0"), command: (call.agent ? "" : "unbound: ") + (call.preview ?? call.command),
+        state: call.state, profile: call.agent?.model ? { model: call.agent.model } : null, estimatedSavedTokens: call.agent ? savingsFor(call.agent.runtimeId) : null,
+        detail: [call.context.taskId && "task " + call.context.taskId, call.context.pr && "PR #" + call.context.pr + (call.context.inferred ? " (path)" : ""),
+          call.context.project && "project " + call.context.project, call.agent?.phase === "analysis" && "analysis (reported)",
+          "queue " + (instance.queue ?? "n/a"), call.context.directory && "dir " + call.context.directory].filter(Boolean).join(" | ") }))),
+      ...pcAgents.flatMap(agent => {
+        const measured = agent.executionIds.map(id => executions.get(id)).filter(row => row?.estimatedSavedTokens !== null && row?.estimatedSavedTokens !== undefined);
+        const linked = agent.executionIds.map(id => executions.get(id)).filter(Boolean);
+        const running = linked.find(row => ["requested", "prepared", "accepted", "running"].includes(row.state));
+        const usage = usageFor(agent.id);
+        return [{ executionId: agent.id, displayId: agent.name, kind: agent.kind, pid: agent.pid,
+          order: (agent.kind === "host" ? "3:" : "2:") + agent.id,
+          command: (agent.phase === "analysis" ? "analysis (reported): " : "") + agent.activity,
+          detail: [agent.context?.taskId && "task " + agent.context.taskId,
+            agent.context?.pr && "PR #" + agent.context.pr, agent.unread > 0 && "messages " + agent.unread,
+            usage.length && usageSummary(usage), agent.context?.directory && "dir " + agent.context.directory].filter(Boolean).join(" | "),
+          state: running?.state ?? (agent.state === "RUNNING" ? "REPORTED" : agent.state),
+          profile: agent.model ? { model: agent.model } : null,
+          estimatedSavedTokens: measured.length || usage.length ? Math.round((measured.reduce((sum, row) => sum + row.savedBytes, 0) + usage.reduce((sum, row) => sum + row.savedBytes, 0)) / 4) : null,
+          partial: measured.length > 0 && measured.length < agent.executionIds.length },
+          ...linked.filter(row => ["requested", "prepared", "accepted", "running"].includes(row.state))
+            .map(row => ({ ...row, command: "-> " + (row.preview ?? row.command), order: "1:" + agent.id + ":work:" + row.executionId }))];
+      }),
+      ...instances.flatMap(active).filter(row => !pcAgents.some(agent => agent.executionIds.includes(row.executionId))).map(row => ({ ...row, command: row.preview ?? row.command }))
+    ];
+    const state = instances.some(instance => active(instance).length) || pcMcp.some(instance => instance.calls.length) ? "RUNNING" : pcAgents.length || pcMcp.length ? "OBSERVING" :
+      instances.some(instance => instance.connection === "connected") ? "READY" : instances[0]?.connection.toUpperCase() ?? "OBSERVING";
+    // Keep each process with its PC heading, including in a short terminal.
+    if (rowCapacity - body.length < (rows.length ? width < 60 ? 5 : 4 : 3)) break;
+    body.push(pair("PC " + name + "  |  saved " + pcSaved + " tokens", state));
+    shownPcs++;
+    if (rows.length) {
+      if (width >= 100) body.push("  " + fit("AGENT/ID", 8) + "  " + fit("PID", 7) + "  " + fit("DOING", width - 71) +
+        "  " + fit("MODEL", 24) + "  " + fit("SAVED TOK", 10, true) + "  STATE");
+      for (const row of rows.sort((a, b) => (a.order ?? "1:" + a.executionId).localeCompare(b.order ?? "1:" + b.executionId))) {
+        const id = row.displayId ?? row.executionId.slice(0, 8), model = row.profile?.model ?? (row.kind === "host" ? "process only" : "not reported");
+        const saving = row.estimatedSavedTokens === null ? "n/a" : "~" + compact(row.estimatedSavedTokens) + (row.partial ? "+" : "");
+        const entry = width >= 100 ? ["  " + fit(id, 8) + "  " + fit(row.pid ?? "-", 7, true) + "  " + fit(row.command, width - 71) +
+          "  " + fit(model, 24) + "  " + fit(saving, 10, true) + "  " + fit(row.state.toUpperCase(), 10)] : [
+          pair("  " + id + "  " + row.command, row.state.toUpperCase()),
+          ...(width >= 60 ? ["    PID " + (row.pid ?? "-") + " | model " + fit(model, width - 51).trimEnd() + " | saved " + saving + " tok"] :
+            ["    model " + model, "    PID " + (row.pid ?? "-") + " | saved " + saving + " tok"])
+        ];
+        const context = row.context;
+        const detail = row.detail || (context ? [context.taskId && "task " + context.taskId,
+          context.pr && "PR #" + context.pr, context.directory && "dir " + context.directory].filter(Boolean).join(" | ") : "");
+        if (detail) entry.push("    " + detail);
+        if (body.length + entry.length + 1 > rowCapacity) break;
+        body.push(...entry);
+        if (row.kind && row.kind !== "call") shownAgents++;
+        else shown++;
+      }
+    } else body.push("  Waiting for work");
+    for (const line of statusLines) if (body.length + 2 <= capacity) body.push(line);
+    body.push("");
+  }
+  if (!pcs.size) body.push(result.instances.length ? "No live PC reported. See logs for completed work and connection history." :
+    "No monitoring snapshots. Update/start a monitoring-capable agent.");
+  lines.push(...body.slice(0, capacity));
+  while (lines.length < height - footer.length - 1) lines.push("");
+  lines.push((jobs > shown ? (jobs - shown) + " more active commands | " : "") +
+    (agents.length > shownAgents ? (agents.length - shownAgents) + " more agents/hosts | " : "") +
+    (pcs.size > shownPcs ? (pcs.size - shownPcs) + " more PCs | " : "") +
+    "Unavailable/stale/stopped snapshots: " + (result.unavailable + result.instances.length - live.length));
+  lines.push(...footer);
+  // Paint after clipping so ANSI sequences never count toward the terminal width.
+  return lines.slice(0, height).map(line => {
+    const text = fit(line, width);
+    if (!color) return text.trimEnd();
+    const cyan = /^LC |^> |^PC |^[+|]|^\s+[_|]/.test(line);
+    return "\x1b[48;2;15;23;42m\x1b[38;2;" + (cyan ? "0;255;213" : "191;219;254") + "m" +
+      text.replace(/\b(RUNNING|READY|CONNECTED|OBSERVING|OBSERVED|REPORTING|QUEUED|FAILED)\b|Saved:.*$/g, value =>
+        "\x1b[38;2;" + (value === "FAILED" ? "248;113;113" : value === "QUEUED" ? "251;191;36" : "0;255;213") + "m" + value + "\x1b[38;2;191;219;254m") + "\x1b[0m";
+  }).join("\n") + "\n";
+}
+
+export function formatInsights(result) {
+  const lines = ["OUTPUT TO REVIEW (recent measured bytes; potential savings unproven):"];
+  const candidates = result.instances.flatMap(instance => instance.executions.filter(row => row.sentBytes > 0)
+    .map(row => ({ ...row, computer: instance.computer ?? "unknown" })))
+    .sort((a, b) => b.sentBytes - a.sentBytes).slice(0, 5);
+  if (!candidates.length) lines.push("  No measured output candidates yet.");
+  for (const row of candidates) lines.push("  " + row.computer + " " + row.executionId.slice(0, 8) + " " + row.command + " | " + compact(row.sentBytes) +
+    " B sent | " + (row.reason ?? "unknown") + " | " +
+    (row.reason === "validated_compact" ? "already compacted; review remaining detail" :
+      row.name === "fs_read" ? "request a focused line range" : row.name === "fs_search" ? "narrow query and maxResults" :
+        "review command verbosity; preserve failures/warnings"));
+  for (const instance of result.instances) {
+    const stats = instance.efficiency;
+    if (stats && stats.polls.status + stats.polls.output >= 10) lines.push("POLLING: " + stats.polls.status + " status / " + stats.polls.output +
+      " output calls on " + (instance.computer ?? "unknown") + "; wait between polls and fetch final output once when practical.");
+  }
+  for (const instance of (result.mcp?.instances ?? []).filter(item => item.running)) {
+    lines.push("MCP " + instance.computer + " | queue " + (instance.queue ?? "n/a") + " | diagnostics writes " + instance.writes +
+      " | write errors " + instance.writeErrors + " | dropped observations " + instance.dropped);
+    for (const row of [...instance.metrics].sort((a, b) => b.sentBytes - a.sentBytes).slice(0, 5)) {
+      lines.push("  " + row.tool + ": " + row.calls + " calls | " + row.errors + " errors | " + row.sentBytes + "B responses | " + row.outputBytes +
+        "B output | saved stdout ~" + Math.round(row.savedBytes / 4) + " tok | " + Math.round(row.durationMs / Math.max(1, row.calls)) + "ms avg");
+      if (["process_output", "scheduler_status", "agent_monitor"].includes(row.tool) && row.calls >= 10) lines.push("    Repeated polling: wait between polls; fetch the final result once when practical.");
+      if (row.sentBytes > 16_384) lines.push("    Review " + (row.tool === "fs_read" ? "line range" : row.tool === "fs_search" ? "query/maxResults" : "verbosity") + "; preserve exit status, errors, warnings and required detail.");
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+// Fixed cursor positions: rewrite changed lines only, with no clear/redraw or scrolling.
+export function monitorFrame(previous, next, maxRows = Infinity) {
+  const before = previous ? previous.trimEnd().split("\n") : [];
+  const after = next.trimEnd().split("\n");
+  let output = "";
+  for (let index = 0; index < Math.min(maxRows, Math.max(before.length, after.length)); index++) {
+    if (before[index] !== after[index]) output += "\x1b[" + (index + 1) + ";1H\x1b[2K" + (after[index] ?? "");
+  }
+  return output;
+}
+
+export async function runMonitor(directory, command, args) {
+  const allowed = command === "logs" ? ["--follow"] : ["--watch", "--json"];
+  if (new Set(args).size !== args.length || args.some(arg => !allowed.includes(arg))) throw Error("ARGUMENT_INVALID");
+  const repeat = args.includes("--watch") || args.includes("--follow");
+  const stop = new AbortController();
+  const abort = () => stop.abort();
+  process.once("SIGINT", abort);
+  process.once("SIGTERM", abort);
+  const seen = new Map();
+  const previousHosts = new Map();
+  const fixedScreen = command === "monitor" && repeat && process.stdout.isTTY && !args.includes("--json");
+  let previous = "", previousSize = "", initial = true, insightCheckpoint = "";
+  let paused = false, latestResult, focusComputer = null, storyDepth = 2;
+  const interactive = fixedScreen && process.stdin.isTTY && typeof process.stdin.setRawMode === "function";
+  const wasRaw = process.stdin.isRaw, wasPaused = process.stdin.isPaused();
+  const input = chunk => {
+    const key = chunk.toString().toLowerCase();
+    if (key === "\u0003" || key === "q") stop.abort();
+    else if (key === " ") paused = !paused;
+    else if (key === "a") focusComputer = null;
+    else if (key === "l") storyDepth = storyDepth === 2 ? 5 : 2;
+    else if (key === "\t" && latestResult) {
+      const computers = [...new Set([...latestResult.instances.map(i => i.computer),
+        ...latestResult.mcp.instances.map(i => i.computer), ...(latestResult.activity?.rows ?? []).map(i => i.computer)].filter(Boolean))].sort();
+      focusComputer = computers[(computers.indexOf(focusComputer) + 1) % computers.length] ?? null;
+    }
+  };
+  if (interactive) { process.stdin.setRawMode(true); process.stdin.on("data", input); process.stdin.resume(); }
+  if (fixedScreen) process.stdout.write("\x1b[?1049h\x1b[?25l");
+  try {
+    do {
+      const result = paused && latestResult ? latestResult : await readMonitors(directory);
+      if (!(paused && latestResult)) {
+        result.mcp = await readMcpActivity();
+        result.health = await readMcpHealth();
+        if (command === "monitor") result.activity = await readAgentActivity(directory, { previousHosts, signal: stop.signal });
+        latestResult = result;
+      }
+      result.paused = paused; result.focusComputer = focusComputer; result.storyDepth = storyDepth;
+      if (command === "logs" && (result.instances.length || result.mcp.instances.length)) {
+        const checkpoint = result.mcp.instances.map(instance => instance.instanceId + ":" + Math.floor(instance.metrics.reduce((sum, row) => sum + row.calls, 0) / 5)).join(",");
+        if (initial || checkpoint !== insightCheckpoint) { process.stdout.write(formatInsights(result)); insightCheckpoint = checkpoint; }
+        for (const instance of result.instances) {
+          const after = seen.get(instance.instanceId) ?? 0;
+          if (after && instance.events[0]?.seq > after + 1) process.stdout.write("Earlier events were overwritten in the 100-event buffer.\n");
+          for (const event of instance.events) if (event.seq > after && !["status", "output"].includes(event.event)) process.stdout.write(logLine(instance, event) + "\n");
+          seen.set(instance.instanceId, instance.events.at(-1)?.seq ?? after);
+        }
+        for (const instance of result.mcp.instances) {
+          const key = "mcp:" + instance.instanceId;
+          const transitionsKey = key + ":starts";
+          const afterStart = seen.get(transitionsKey) ?? 0;
+          for (const event of instance.transitions ?? []) if (event.seq > afterStart) {
+            process.stdout.write([event.at, "pc=" + instance.computer, "agent=" + (event.name ?? "unbound"), event.preview, "RUNNING",
+              "model=" + (event.model ?? "not_reported"), event.context.directory && "dir=" + event.context.directory,
+              event.context.taskId && "task=" + event.context.taskId].filter(Boolean).join(" ") + "\n");
+          }
+          seen.set(transitionsKey, instance.transitions?.at(-1)?.seq ?? afterStart);
+          // Request IDs finish out of order: a per-event key tracks actual completions, not numeric high-water IDs.
+          for (const event of instance.events) {
+            const eventKey = key + ":" + event.id;
+            if (seen.has(eventKey)) continue;
+            process.stdout.write([event.at, "pc=" + instance.computer, "agent=" + (event.name ?? "unbound"), event.preview ?? event.command, event.state, "model=" + (event.model ?? "not_reported"),
+              "elapsed=" + event.durationMs + "ms", event.exitCode !== null && "exit=" + event.exitCode, event.timedOut && "timeout=true",
+              event.code, event.context.directory && "dir=" + event.context.directory, event.context.taskId && "task=" + event.context.taskId,
+              event.context.pr && "PR=" + event.context.pr, "sent=" + event.sentBytes + "B", "saved=~" + Math.round(event.savedBytes / 4) + "tok"].filter(Boolean).join(" ") + "\n");
+            seen.set(eventKey, 1);
+          }
+          for (const seenKey of seen.keys()) if (seenKey.startsWith(key + ":") && seenKey !== transitionsKey && !instance.events.some(event => seenKey === key + ":" + event.id)) seen.delete(seenKey);
+        }
+        for (const key of seen.keys()) if (!result.instances.some(instance => instance.instanceId === key) &&
+          !result.mcp.instances.some(instance => key.startsWith("mcp:" + instance.instanceId + ":"))) seen.delete(key);
+        if (result.unavailable) process.stderr.write("Some monitoring snapshots are unavailable.\n");
+      } else {
+        const columns = Math.max(1, (process.stdout.columns ?? 120) - 1);
+        const rows = Math.max(1, (process.stdout.rows ?? 40) - 1);
+        const size = columns + "x" + rows;
+        // A resized terminal must repaint even when the snapshot is unchanged.
+        if (fixedScreen && size !== previousSize) previous = "";
+        const next = args.includes("--json") ? JSON.stringify(result) + "\n" :
+          formatMonitor(result, fixedScreen ? columns : undefined, fixedScreen ? rows : undefined,
+            process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb");
+        process.stdout.write(fixedScreen ? monitorFrame(previous, next, Math.max(1, (process.stdout.rows ?? 40) - 1)) : next);
+        previous = next;
+        previousSize = size;
+      }
+      initial = false;
+      if (repeat) await delay(2000, undefined, { signal: stop.signal }).catch(error => { if (error.name !== "AbortError") throw error; });
+    } while (repeat && !stop.signal.aborted);
+  } finally {
+    if (interactive) { process.stdin.removeListener("data", input); process.stdin.setRawMode(!!wasRaw); if (wasPaused) process.stdin.pause(); }
+    if (fixedScreen) process.stdout.write("\x1b[0m\x1b[?25h\x1b[?1049l");
+    process.removeListener("SIGINT", abort);
+    process.removeListener("SIGTERM", abort);
+  }
+}