@comput/pi-intercom 0.3.0 → 0.4.2

package/src/activity.ts

@@ -0,0 +1,66 @@
+/** Public event categories only: never accept content, arguments, or results. */
+export type ActivityPhase = 'working' | 'thinking' | 'responding' | 'tool' | 'idle';
+export type ActivityDetail = 'processing' | 'thinking' | 'responding' | 'reading_files' |
+  'editing_files' | 'running_command' | 'using_tool' | 'multiple_tools' | 'settled';
+
+function toolDetail(name: string): ActivityDetail {
+  switch (name) {
+    case 'read': return 'reading_files';
+    case 'edit':
+    case 'write': return 'editing_files';
+    case 'bash':
+    case 'powershell': return 'running_command';
+    default: return 'using_tool';
+  }
+}
+
+/** Stores only opaque active tool IDs, public categories, and the last emitted state. */
+export function createActivityTracker(record: (phase: ActivityPhase, detail: ActivityDetail) => void) {
+  const tools = new Map<string, ActivityDetail>();
+  let lastPhase: ActivityPhase | undefined;
+  let lastDetail: ActivityDetail | undefined;
+  function emit(phase: ActivityPhase, detail: ActivityDetail): void {
+    if (lastPhase === phase && lastDetail === detail) return;
+    lastPhase = phase;
+    lastDetail = detail;
+    record(phase, detail);
+  }
+  function emitTools(): void {
+    const detail = tools.size > 1 ? 'multiple_tools' : tools.values().next().value;
+    if (detail) emit('tool', detail);
+  }
+  return {
+    start(): void {
+      tools.clear();
+      emit('working', 'processing');
+    },
+    settled(): void {
+      tools.clear();
+      emit('idle', 'settled');
+    },
+    message(type: string): void {
+      if (tools.size) return;
+      switch (type) {
+        case 'thinking_start':
+        case 'thinking_delta': emit('thinking', 'thinking'); break;
+        case 'thinking_end': emit('working', 'processing'); break;
+        case 'text_start':
+        case 'text_delta': emit('responding', 'responding'); break;
+      }
+    },
+    toolStart(id: string, name: string): void {
+      tools.set(id, toolDetail(name));
+      emitTools();
+    },
+    toolEnd(id: string): void {
+      if (!tools.delete(id)) return;
+      if (tools.size) emitTools();
+      else emit('working', 'processing');
+    },
+    reset(): void {
+      tools.clear();
+      lastPhase = undefined;
+      lastDetail = undefined;
+    },
+  };
+}

package/src/config.ts

@@ -8,7 +8,7 @@ export interface Agent {
   coordinator: boolean;
   description: string;
   port: number;
-  /** Last bound dashboard port, coordinator only; not evidence of a live server. */
+  /** Legacy browser dashboard field, accepted for migration only; removed at coordinator startup. */
   dashboardPort?: number;
   projectDirectory: string;
 }

package/src/index.ts

@@ -5,7 +5,8 @@ import { getAgentDir, SessionManager, SettingsManager, truncateHead, withFileMut
 import { ConfigStore } from './config.js';
 import { Intercom, UNSUPPORTED_CANCELLATION } from './runtime.js';
 import { launchers } from './launcher.js';
-import { startDashboard, type Dashboard } from './dashboard.js';
+import { ensureMonitorPane } from './monitor-launcher.js';
+import { createActivityTracker } from './activity.js';
 
 const to = Type.Object({ to: Type.String({ minLength: 1, maxLength: 128 }) });
 const tools: [string, string, TSchema][] = [
@@ -13,8 +14,10 @@ const tools: [string, string, TSchema][] = [
   ['configure_worker', 'Coordinator only. Write explicit reported connection details and responsibility to config. Does not notify, reload, or start work. Use reload_worker separately.', Type.Object({ sessionId: Type.String(), port: Type.Integer({ minimum: 1, maximum: 65535 }), projectDirectory: Type.String(), name: Type.String({ minLength: 1, maxLength: 128 }), description: Type.String({ minLength: 1, maxLength: 4096 }) })],
   ['reload_worker', 'Coordinator only. Ask worker to reread responsibility and synchronize names. NOT Pi extension reload, cancellation, restart, or work assignment.', to],
   ['send', 'Configured sessions only. Send an explicit work/progress/findings message by recipient name. Idle delivery starts a turn; busy delivery steers at supported boundaries. Receipt is not an agent reply. Progress questions do not cancel assignments.', Type.Object({ to: Type.String(), message: Type.String({ minLength: 1, maxLength: 48000 }) })],
+  ['worker_status', 'Configured sessions only. Read paginated JSON worker observations and public reports from local files, optionally by worker name. Last-observed status is not live liveness or task completion; reports are self-reported, not approval. No worker prompts, live probing or Telegram dependency. Follow nextOffset for further pages; null report means no readable active report.', Type.Object({ name: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })), offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })) })],
   ['list', 'Configured sessions only. Read current saved names, responsibilities, session IDs, roles and ports. No live probing. Output limited to 50 KiB/2000 lines; full data remains in config.json.', Type.Object({})],
   ['request_status', 'Coordinator only. Ask worker extension to send an independent sessionId/port/busy report without a model turn on worker. No synchronous status reply.', to],
+  ['report_work', 'Configured, responsibility-loaded workers only. Store one public report (blocked, needs_decision, ready_for_review) and notify the coordinator; clear retires it. Summary required except clear (omit or empty). Never include private reasoning, credentials, raw tool payloads, or secrets. Receipt is not approval, verified completion, or permission for follow-up work.', Type.Object({ status: Type.String({ enum: ['blocked', 'needs_decision', 'ready_for_review', 'clear'] }), summary: Type.Optional(Type.String({ maxLength: 2000 })) })],
   ['report_status', 'Worker only (including anonymous). Send runtime sessionId/port/busy report to coordinator. This is NOT registration and creates no config entry.', Type.Object({})],
   ['stop_worker', UNSUPPORTED_CANCELLATION, to],
   ['close_worker', UNSUPPORTED_CANCELLATION, to],
@@ -43,16 +46,23 @@ class PiConfigStore extends ConfigStore {
 export default function intercomExtension(pi: ExtensionAPI): void {
   let runtime: Intercom | undefined;
   let context: ExtensionContext | undefined;
-  let dashboard: Dashboard | undefined;
   let generation = 0;
+  let activityOutcome: 'started' | 'settled' | 'snapshot' = 'snapshot';
+  const activity = createActivityTracker((phase, detail) => {
+    runtime?.recordObservation('host.activity', { busy: phase !== 'idle', phase, detail, outcome: activityOutcome });
+  });
   const launcher = launchers({
     extension: fileURLToPath(import.meta.url),
     sessionExists: async (cwd, id) => (await SessionManager.list(cwd, resumeSessionDirectory(cwd))).some(s => s.id === id),
   });
   pi.on('session_start', async (_event, ctx) => {
     const started = ++generation;
-    await dashboard?.close(); dashboard = undefined;
-    await runtime?.close(); context = ctx;
+    activity.reset();
+    const oldRuntime = runtime;
+    runtime = undefined;
+    await oldRuntime?.close();
+    if (started !== generation) return;
+    context = ctx;
     if (!['win32', 'linux'].includes(process.platform) || ctx.mode !== 'tui') throw new Error('PiIntercom requires Windows or Linux interactive Pi. No resources started.');
     if (!ctx.isProjectTrusted()) throw new Error('PiIntercom requires project trust before honoring shared project configuration.');
     runtime = new Intercom({
@@ -68,39 +78,57 @@ export default function intercomExtension(pi: ExtensionAPI): void {
     const current = runtime;
     try { await current.start(); }
     catch (e) { if (runtime === current) runtime = undefined; ctx.ui.notify(String(e), 'error'); return; }
-    if (started !== generation) return;
-    let server: Dashboard | undefined;
-    let savingPort = false;
+    if (started !== generation) { await current.close(); return; }
     try {
       if ((await current.state()).me?.coordinator) {
-        server = await startDashboard(current.store.root);
-        if (started !== generation) { await server.close(); return; }
-        savingPort = true;
-        await current.recordDashboardPort(server.port);
-        if (started !== generation) { await server.close(); return; }
-        dashboard = server;
-        ctx.ui.notify(`Intercom read-only dashboard: ${server.url} (saved URL is last-known, not live availability)`, 'info');
+        try { await current.retireDashboardMetadata(); }
+        catch (error) {
+          if (started !== generation) return;
+          ctx.ui.notify(`Legacy dashboard metadata cleanup failed; messaging remains available: ${String(error)}`, 'warning');
+        }
+        if (started !== generation) return;
+        const monitor = await ensureMonitorPane({
+          root: current.store.root, sessionId: ctx.sessionManager.getSessionId(),
+          script: fileURLToPath(new URL('../dist/monitor.js', import.meta.url)),
+          assertCurrent: () => { if (started !== generation || runtime !== current) throw new Error('Coordinator session changed'); },
+        });
+        if (started !== generation) return;
+        ctx.ui.notify(`Intercom status monitor: ${monitor.outcome}${monitor.pane ? ` (${monitor.pane})` : ''}`, 'info');
       }
-    } catch {
-      await server?.close().catch(() => {});
+    } catch (error) {
       if (started !== generation) return;
-      ctx.ui.notify(savingPort
-        ? 'Intercom dashboard port could not be saved; the new dashboard was closed. Any saved URL is last-known only. Messaging remains available.'
-        : 'Intercom dashboard unavailable; communication remains independent.', 'error');
+      ctx.ui.notify(String(error), 'warning');
     }
   });
   pi.on('session_shutdown', async () => {
     generation++;
-    await dashboard?.close(); dashboard = undefined;
-    await runtime?.close(); runtime = undefined; context = undefined;
+    activity.reset();
+    const oldRuntime = runtime;
+    runtime = undefined; context = undefined;
+    await oldRuntime?.close();
   });
   pi.on('agent_start', async (_event, ctx) => {
     context = ctx;
-    runtime?.recordObservation('host.activity', { busy: !ctx.isIdle(), outcome: 'started' });
+    activityOutcome = 'started';
+    try { activity.start(); } finally { activityOutcome = 'snapshot'; }
   });
   pi.on('agent_settled', async (_event, ctx) => {
     context = ctx;
-    runtime?.recordObservation('host.activity', { busy: !ctx.isIdle(), outcome: 'settled' });
+    activityOutcome = 'settled';
+    try { activity.settled(); } finally { activityOutcome = 'snapshot'; }
+  });
+  pi.on('message_update', (event, ctx) => {
+    context = ctx;
+    // Inspect the event discriminator only. Never access reasoning/text payloads.
+    activity.message(event.assistantMessageEvent.type);
+  });
+  pi.on('tool_execution_start', (event, ctx) => {
+    context = ctx;
+    activity.toolStart(event.toolCallId, event.toolName);
+  });
+  pi.on('tool_execution_end', (event, ctx) => {
+    context = ctx;
+    activity.toolEnd(event.toolCallId);
   });
   pi.on('before_agent_start', async (event, ctx) => {
     context = ctx;

package/src/monitor-launcher.ts

@@ -0,0 +1,110 @@
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { access, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { run, shQuote, psQuote, encoded, type Run } from './launcher.js';
+
+interface Pane { pane_id: string; tab_id: string; workspace_id?: string; label?: string }
+interface RecordState { version: 1; sessionId: string; workspace: string; caller: string; pane?: string; stage: string }
+export interface MonitorLaunchOptions {
+  root: string; sessionId: string; script: string;
+  node?: string; platform?: string; env?: NodeJS.ProcessEnv; run?: Run;
+  assertCurrent?(): void;
+}
+/** Pane ownership is separate from agent config. Pending records fence uncertain
+ * mutations across reloads; neither errors nor absence of readiness cause retries. */
+export async function ensureMonitorPane(options: MonitorLaunchOptions): Promise<{ outcome: string; pane?: string }> {
+  const env = options.env ?? process.env;
+  if (env.HERDR_ENV !== '1') return { outcome: 'unavailable: coordinator is not inside Herdr' };
+  if (!env.HERDR_PANE_ID) throw new Error('Monitor requires caller pane identity; no focused-pane fallback');
+  const platform = options.platform ?? process.platform;
+  if (!['win32', 'linux'].includes(platform)) throw new Error('Monitor launcher supports Windows/Linux only');
+  const exec = options.run ?? run;
+  const check = () => options.assertCurrent?.();
+  const call = async (args: string[]) => {
+    check();
+    const output = await exec('herdr', args);
+    check();
+    // pane run acknowledges command submission with an empty stdout on current Herdr.
+    if (!output.trim() && args[1] === 'run') return {};
+    return JSON.parse(output).result;
+  };
+  const caller = (await call(['pane', 'current', '--current']))?.pane as Pane;
+  if (!caller?.pane_id || !caller.tab_id || !caller.workspace_id) throw new Error('Missing current Herdr pane identity');
+  const label = 'Intercom monitor';
+  const legacyMarker = `Intercom monitor [${options.sessionId}]`;
+  const key = createHash('sha256').update(options.sessionId).digest('hex').slice(0, 24);
+  const directory = path.join(options.root, '.pi-intercom');
+  await mkdir(directory, { recursive: true });
+  const file = path.join(directory, `monitor-${key}.json`), lock = `${file}.lock`;
+  check();
+  try { await writeFile(lock, '', { flag: 'wx', mode: 0o600 }); }
+  catch { throw new Error(`Monitor launch locked; inspect ${lock} before recovery. No pane created.`); }
+  let state: RecordState | undefined;
+  const save = async () => {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, JSON.stringify(state), { flag: 'wx', mode: 0o600 });
+      await rename(temporary, file);
+    } finally { await unlink(temporary).catch(() => {}); }
+  };
+  try {
+    try {
+      state = JSON.parse(await readFile(file, 'utf8'));
+      if (state?.version !== 1 || state.sessionId !== options.sessionId || typeof state.stage !== 'string') throw new Error('Invalid monitor ownership record');
+    } catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e; }
+    const panes = (await call(['pane', 'list', '--workspace', caller.workspace_id]))?.panes as Pane[];
+    if (!Array.isArray(panes) || panes.some(p => !p?.pane_id || !p.tab_id)) throw new Error('Invalid Herdr pane inventory');
+    const matches = panes.filter(p => p.label === legacyMarker ||
+      (state && state.workspace === caller.workspace_id && state.pane === p.pane_id));
+    if (matches.length > 1) throw new Error('Multiple monitor markers; inspect panes. No automatic changes.');
+    if (matches.length === 1) {
+      const pane = matches[0];
+      if (pane.pane_id === caller.pane_id || pane.tab_id !== caller.tab_id) throw new Error('Monitor marker is on caller or moved to another tab; no duplicate created');
+      if (state && (state.workspace !== caller.workspace_id || state.caller !== caller.pane_id || (state.pane && state.pane !== pane.pane_id))) {
+        throw new Error('Monitor ownership differs from current caller; no automatic changes');
+      }
+      if (state && !['submitted', 'observed'].includes(state.stage)) {
+        throw new Error(`Monitor partial launch needs inspection (${state.stage}); no retry or duplicate`);
+      }
+      if (!state) {
+        state = { version: 1, sessionId: options.sessionId, workspace: caller.workspace_id, caller: caller.pane_id, pane: pane.pane_id, stage: 'observed' };
+        await save();
+      }
+      if (pane.label !== label) await call(['pane', 'rename', pane.pane_id, label]);
+      return { outcome: 'existing pane preserved; process readiness not checked', pane: pane.pane_id };
+    }
+    if (panes.some(p => p.tab_id === caller.tab_id && p.label === label)) {
+      throw new Error('Unowned monitor label in coordinator tab; inspect before creating another pane');
+    }
+    if (state && (!['submitted', 'observed'].includes(state.stage) || state.workspace !== caller.workspace_id || panes.some(p => p.pane_id === state!.pane))) {
+      throw new Error(`Monitor ownership/partial launch needs inspection (${state.stage}, pane ${state.pane ?? 'unknown'}); no retry or duplicate`);
+    }
+    await access(options.script); // Missing build must not leave a new empty pane.
+    check();
+    state = { version: 1, sessionId: options.sessionId, workspace: caller.workspace_id, caller: caller.pane_id, stage: 'split_pending' };
+    await save();
+    // Small top quarter after swapping pane identities. Verify actual geometry below.
+    const split = await call(['pane', 'split', '--pane', caller.pane_id, '--direction', 'down', '--ratio', '0.25', '--cwd', options.root, '--no-focus']);
+    const pane = split?.pane?.pane_id;
+    if (typeof pane !== 'string' || pane === caller.pane_id) throw new Error('Split returned no distinct pane ID');
+    state.pane = pane; state.stage = 'rename_pending'; await save();
+    await call(['pane', 'rename', pane, label]);
+    state.stage = 'swap_pending'; await save();
+    const swapped = await call(['pane', 'swap', '--source-pane', caller.pane_id, '--target-pane', pane]);
+    if (swapped?.swap?.changed !== true) throw new Error('Herdr did not confirm pane swap');
+    const layout = (await call(['pane', 'layout', '--pane', caller.pane_id]))?.layout;
+    const top = layout?.panes?.find((p: { pane_id: string }) => p.pane_id === pane)?.rect;
+    const bottom = layout?.panes?.find((p: { pane_id: string }) => p.pane_id === caller.pane_id)?.rect;
+    if (!top || !bottom || top.y >= bottom.y || layout.focused_pane_id !== caller.pane_id) throw new Error('Monitor geometry/focus not confirmed; inspect panes before recovery');
+    state.stage = 'run_pending'; await save();
+    const args = [options.script, '--root', options.root];
+    const command = platform === 'win32'
+      ? `powershell.exe -NoProfile -ExecutionPolicy Bypass -EncodedCommand ${encoded(`& ${psQuote(options.node ?? process.execPath)} ${args.map(psQuote).join(' ')}`)}`
+      : `sh -c ${shQuote(`exec ${shQuote(options.node ?? process.execPath)} ${args.map(shQuote).join(' ')}`)}`;
+    await call(['pane', 'run', pane, command]);
+    state.stage = 'submitted'; await save();
+    return { outcome: 'command submitted; monitor readiness not awaited', pane };
+  } catch (e) {
+    throw new Error(`Intercom monitor: ${String(e)}. Pane ${state?.pane ?? 'unknown'} may remain; no automatic cleanup.`);
+  } finally { await unlink(lock).catch(() => {}); }
+}

package/src/monitor-view.ts

@@ -0,0 +1,123 @@
+import { stripVTControlCharacters } from 'node:util';
+import { truncateToWidth, visibleWidth } from 'pi-intercom-tui';
+import type { ObservationSnapshot } from './snapshot.js';
+import { workerObservation } from './worker-status.js';
+
+const safe = (value: string) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f\u2028-\u202e\u2066-\u2069]/g, ' ');
+const clip = (value: string, width: number) => stripVTControlCharacters(truncateToWidth(safe(value), Math.max(0, width)));
+const cell = (value: string, width: number) => {
+  const text = clip(value, width);
+  return text + ' '.repeat(Math.max(0, width - visibleWidth(text)));
+};
+const ageLabel = (milliseconds: number) => {
+  const seconds = Math.floor(milliseconds / 1000);
+  if (seconds < 60) return `${seconds}s ago`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
+  return `${Math.floor(seconds / 86400)}d ago`;
+};
+
+const reportLabels: Record<string, string> = {
+  blocked: 'Blocked', needs_decision: 'Needs decision', ready_for_review: 'Ready for review',
+};
+// Wrap only sanitized grapheme clusters, bounded by the terminal's remaining rows.
+function wrapSummary(value: string, width: number, rows: number): string[] {
+  if (width <= 0 || rows <= 0) return [];
+  const result: string[] = [];
+  let current = '';
+  for (const { segment } of new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(safe(value))) {
+    if (visibleWidth(current + segment) > width) {
+      if (current) result.push(current);
+      current = '';
+      if (result.length >= rows) break;
+    }
+    current += visibleWidth(segment) <= width ? segment : clip(segment, width);
+  }
+  if (current && result.length < rows) result.push(current);
+  return result;
+}
+
+/** Presentation only. All user-controlled text is sanitized before trusted ANSI styling. */
+export function renderMonitor(snapshot: ObservationSnapshot | undefined, width: number, height: number,
+  now = Date.now(), color = false, options: { selectedIndex?: number; details?: boolean } = {}): string[] {
+  width = Math.max(0, Math.min(1000, Math.floor(width)));
+  height = Math.max(0, Math.min(1000, Math.floor(height)));
+  if (!width || !height) return [];
+  const paint = (code: string, text: string) => color ? `\x1b[${code}m${text}\x1b[0m` : text;
+  const dim = (text: string) => paint('90', text);
+  const line = (text: string) => clip(text, width);
+  const lines: string[] = [];
+  if (!snapshot?.config) {
+    lines.push(paint('33', line('  Status unavailable — waiting for local observations')));
+  } else {
+    const workers = snapshot.config.agents.filter(agent => !agent.coordinator);
+    // Report remains distinct from observed status; last activity gives way first.
+    const wide = width >= 100;
+    const nameWidth = wide ? Math.min(22, Math.max(10, width - 88)) : 10;
+    const activityWidth = wide ? 12 : 8, ageWidth = 16, reportWidth = 16;
+    const table = (name: string, activity: string, age: string, detail: string, report = '—', tone = '90', selected = false) => {
+      const prefix = `${selected ? '› ' : '  '}${cell(name, nameWidth)}  ${cell(age, ageWidth)}  `;
+      const status = cell(activity, activityWidth);
+      const tail = `  ${cell(report, reportWidth)}${wide ? `  ${detail}` : ''}`;
+      // Clip as plain text first; no untrusted escape sequences enter the output.
+      if (!color) return line(prefix + status + tail);
+      const namePart = clip(prefix, width);
+      const statusRoom = Math.max(0, width - visibleWidth(namePart));
+      const statusPart = clip(status, statusRoom);
+      const tailRoom = Math.max(0, statusRoom - visibleWidth(statusPart));
+      return (selected ? paint('1;36', namePart) : namePart) + paint(tone, statusPart) + dim(clip(tail, tailRoom));
+    };
+    lines.push(paint('1', table('Worker', 'Status', 'Seen', 'Last activity', 'Report')));
+    lines.push(dim(line('  ' + '─'.repeat(Math.max(0, width - 2)))));
+    const selectedIndex = Math.min(workers.length - 1, Math.max(-1, options.selectedIndex ?? -1));
+    const showDetails = Boolean(options.details && selectedIndex >= 0 && height >= 8);
+    const selectedReport = snapshot.reports?.find(report => report.sessionId === workers[selectedIndex]?.sessionId && reportLabels[report.status]);
+    const detailBudget = showDetails ? Math.min(selectedReport ? 12 : 5, height - 5) : 0;
+    const available = Math.max(0, height - lines.length - 2 - detailBudget);
+    const needsOverflow = workers.length > available;
+    const count = Math.min(workers.length, Math.max(0, available - (needsOverflow && available > 1 ? 1 : 0)));
+    const start = Math.max(0, Math.min(Math.max(0, workers.length - count), selectedIndex - count + 1));
+    let selectedDetail: string[] = [];
+    for (const [offset, worker] of workers.slice(start, start + count).entries()) {
+      const observation = workerObservation(snapshot, worker.sessionId, now);
+      const activity = observation.observedStatus, evidence = observation.lastActivity;
+      const age = observation.observationAgeSeconds === null ? '—' : ageLabel(observation.observationAgeSeconds * 1000) + (observation.stale ? ' (old)' : '');
+      const tone = observation.stale ? '90' : activity === 'thinking' ? '35' : activity === 'working' ? '36' : activity === 'idle' ? '32' : '90';
+      const selected = start + offset === selectedIndex;
+      const report = snapshot.reports?.find(report => report.sessionId === worker.sessionId && reportLabels[report.status]);
+      lines.push(table(worker.name, activity, age, evidence, report ? reportLabels[report.status] : '—', tone, selected));
+      if (selected && showDetails && report) {
+        const elapsed = now - Date.parse(report.updatedAt);
+        const reportAge = !Number.isFinite(elapsed) || elapsed < 0 ? 'clock uncertain' : ageLabel(elapsed) + (elapsed > snapshot.staleAfterMs ? ' (old)' : '');
+        const contextRows = detailBudget >= 5 ? [
+          ...(detailBudget >= 6 ? [paint('1', line(`  ${worker.name}`))] : []),
+          line(`  Responsibility: ${worker.description || 'Not specified'}`),
+          line(`  Observed status: ${activity} · ${age}`),
+        ] : [];
+        selectedDetail = [
+          ...contextRows,
+          line(`  Report: ${reportLabels[report.status]} · ${reportAge}`),
+          line('  Self-reported, pending review'),
+          ...wrapSummary(`Summary: ${report.summary}`, Math.max(0, width - 2), Math.max(0, detailBudget - 2 - contextRows.length)).map(text => line(`  ${text}`)),
+        ];
+      } else if (selected && showDetails) selectedDetail = [
+        dim(line('  ' + '─'.repeat(Math.max(0, width - 2)))),
+        paint('1', line(`  ${worker.name}`)),
+        line(`  Responsibility: ${worker.description || 'Not specified'}`),
+        line(`  Observed status: ${activity} · ${age}`),
+        line(`  Last activity: ${evidence}`),
+      ];
+    }
+    if (workers.length > count && available > count) lines.push(dim(line(`  ${workers.length - count} more · rows ${count ? start + 1 : 0}–${start + count} of ${workers.length} · ↑↓ to browse`)));
+    lines.push(...(selectedReport ? selectedDetail.slice(0, detailBudget) : selectedDetail.slice(-detailBudget || selectedDetail.length)));
+    if (!workers.length && available) lines.push(dim(line('  No workers configured yet')));
+  }
+  // Anchor the hint at the bottom; do not fill the pane with decorative boxes.
+  const partial = snapshot && (snapshot.truncated || snapshot.errors.length);
+  const controls = options.details ? 'q quit · Esc back · ↑↓ select' : 'q quit · ↑↓ select · Enter details';
+  const hasReports = snapshot?.reports?.some(report => reportLabels[report.status] && snapshot.config?.agents.some(agent => !agent.coordinator && agent.sessionId === report.sessionId));
+  const footer = width < 18 ? 'q quit' : `  ${controls}${partial ? ' · Partial observations' : ''}${hasReports ? ' · Reports: self-reported, pending review' : ''}`;
+  while (lines.length < height - 1) lines.push('');
+  lines.push(dim(line(footer)));
+  return lines.slice(0, height);
+}

package/src/monitor.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Key, matchesKey, ProcessTerminal, TuiAltScreen, type Component, type TUI } from 'pi-intercom-tui';
+import { readObservationSnapshot, type ObservationSnapshot } from './snapshot.js';
+import { renderMonitor } from './monitor-view.js';
+
+export function parseMonitorRoot(args: string[]): string {
+  if (args.length !== 2 || args[0] !== '--root' || !path.isAbsolute(args[1])) {
+    throw new Error('Usage: node dist/monitor.js --root <absolute-project-path>');
+  }
+  return path.normalize(args[1]);
+}
+
+export interface MonitorOptions {
+  read?: typeof readObservationSnapshot;
+  rows: () => number;
+  requestRender: () => void;
+  onQuit: () => void;
+  intervalMs?: number;
+  color?: boolean;
+  now?: () => number;
+  /** Returns a cancellation function; injected by deterministic tests. */
+  schedule?: (callback: () => void, delayMs: number) => () => void;
+}
+
+/** No host, probing, network or writes. Closing never awaits an outstanding read. */
+export function createMonitor(root: string, options: MonitorOptions): Component & { start(): void; close(): void } {
+  let snapshot: ObservationSnapshot | undefined;
+  let selectedIndex = -1;
+  let selectedSessionId: string | undefined;
+  let details = false;
+  const workers = () => snapshot?.config?.agents.filter(agent => !agent.coordinator) ?? [];
+  const requestRender = () => { try { options.requestRender(); } catch { /* UI shutdown is independent of reading. */ } };
+  let closed = false, started = false;
+  let cancel: (() => void) | undefined;
+  const schedule = options.schedule ?? ((callback, delay) => {
+    const timer = setTimeout(callback, delay);
+    timer.unref();
+    return () => clearTimeout(timer);
+  });
+  const interval = Math.max(100, options.intervalMs ?? 3000);
+  async function refresh(): Promise<void> {
+    if (closed) return;
+    let next: ObservationSnapshot | undefined;
+    try { next = await (options.read ?? readObservationSnapshot)(root); } catch { /* Unavailable, no raw errors. */ }
+    if (closed) return;
+    snapshot = next;
+    // Preserve identity through reordering, and retain it across transient read failures.
+    if (snapshot?.config) {
+      const roster = workers();
+      const previous = roster.findIndex(agent => agent.sessionId === selectedSessionId);
+      selectedIndex = roster.length ? (previous >= 0 ? previous : Math.max(0, Math.min(selectedIndex, roster.length - 1))) : -1;
+      selectedSessionId = roster[selectedIndex]?.sessionId;
+      if (selectedIndex < 0) details = false;
+    }
+    requestRender();
+    if (!closed) cancel = schedule(() => { cancel = undefined; void refresh(); }, interval);
+  }
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    cancel?.(); cancel = undefined;
+  };
+  return {
+    start() { if (started || closed) return; started = true; void refresh(); },
+    close,
+    invalidate() {},
+    render(width) {
+      const height = Math.max(0, Math.floor(options.rows()));
+      if (width <= 0 || !height) return [];
+      const view = { selectedIndex: snapshot?.config ? selectedIndex : -1, details: !!snapshot?.config && details };
+      try { return renderMonitor(snapshot, width, height, (options.now ?? Date.now)(), options.color, view); }
+      catch { return renderMonitor(undefined, width, height, Date.now(), options.color, { selectedIndex: -1, details: false }); }
+    },
+    handleInput(data) {
+      if (closed) return;
+      if (matchesKey(data, Key.escape) && details) {
+        details = false; requestRender(); return;
+      }
+      if (matchesKey(data, 'q') || matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl('c'))) {
+        close(); options.onQuit(); return;
+      }
+      const roster = workers();
+      if (!roster.length) return;
+      if (matchesKey(data, Key.up) || matchesKey(data, Key.down)) {
+        const next = Math.max(0, Math.min(roster.length - 1, selectedIndex + (matchesKey(data, Key.up) ? -1 : 1)));
+        if (next !== selectedIndex) {
+          selectedIndex = next; selectedSessionId = roster[next].sessionId; requestRender();
+        }
+      } else if (matchesKey(data, Key.enter)) {
+        details = !details; requestRender();
+      }
+    },
+  };
+}
+
+/** CLI-only setup: importing this module never touches raw mode or project files. */
+export function runMonitor(args = process.argv.slice(2)): void {
+  const root = parseMonitorRoot(args);
+  if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('Intercom monitor requires an interactive terminal.');
+  // pi-tui supports optional disk diagnostics; this read-only process must not enable them.
+  delete process.env.PI_TUI_WRITE_LOG;
+  delete process.env.PI_TUI_DEBUG;
+  delete process.env.PI_DEBUG_REDRAW;
+  const terminal = new ProcessTerminal();
+  const tui: TUI = new TuiAltScreen(terminal, false, undefined, { mouse: false });
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    monitor.close();
+    process.removeListener('SIGINT', signalQuit);
+    process.removeListener('SIGTERM', signalQuit);
+    process.removeListener('exit', stop);
+    try { tui.stop(); } finally { terminal.stop(); }
+  };
+  // Explicit exit after restoring the terminal: an unresponsive filesystem read
+  // must not hold the standalone process open after the owner requests quit.
+  const quit = () => { stop(); process.exit(0); };
+  const signalQuit = () => quit();
+  const monitor = createMonitor(root, {
+    rows: () => terminal.rows,
+    color: process.env.NO_COLOR === undefined && process.env.TERM !== 'dumb',
+    requestRender: () => tui.requestRender(),
+    onQuit: quit,
+  });
+  tui.addChild(monitor);
+  tui.setFocus(monitor);
+  process.on('SIGINT', signalQuit);
+  process.on('SIGTERM', signalQuit);
+  process.on('exit', stop);
+  try { tui.start(); monitor.start(); }
+  catch (error) { stop(); throw error; }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  try { runMonitor(); }
+  catch (error) {
+    console.error(error instanceof Error ? error.message : 'Intercom monitor unavailable.');
+    process.exitCode = 1;
+  }
+}

package/src/observability.ts

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import type { ActivityPhase, ActivityDetail } from './activity.js';
 import { randomUUID } from 'node:crypto';
 import { appendFile, lstat, mkdir, opendir, rename, stat, unlink } from 'node:fs/promises';
 
@@ -9,7 +10,7 @@ export const EVENT_TYPES = ['runtime.starting', 'runtime.ready', 'runtime.closed
 export type EventType = typeof EVENT_TYPES[number];
 const OUTCOMES = ['attempted', 'returned', 'failed', 'http_receipt', 'handler_failed', 'started', 'settled', 'snapshot', 'ended', 'written', 'removed', 'ready'] as const;
 const ERROR_CODES = ['operation_failed', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EADDRINUSE', 'EACCES', 'EPERM', 'ENOENT', 'ENOSPC'] as const;
-const KINDS = ['message', 'registration', 'status', 'request_status', 'reload', 'stop', 'close'] as const;
+const KINDS = ['message', 'report', 'registration', 'status', 'request_status', 'reload', 'stop', 'close'] as const;
 const OPERATIONS = ['configure_worker', 'set_multiplexer', 'remove_worker', 'create_worker', 'resume_worker', 'port_update', 'initialize'] as const;
 export interface EventMetadata {
   peerSessionId?: string;
@@ -17,6 +18,8 @@ export interface EventMetadata {
   correlationId?: string;
   kind?: typeof KINDS[number];
   busy?: boolean;
+  phase?: ActivityPhase;
+  detail?: ActivityDetail;
   port?: number;
   role?: 'coordinator' | 'worker' | 'anonymous';
   outcome?: typeof OUTCOMES[number];
@@ -49,6 +52,8 @@ export function sanitizeObservation(value: unknown): Observation | undefined {
   if (safeText(v.correlationId, 128) && /^[a-zA-Z0-9-]+$/.test(v.correlationId)) result.correlationId = v.correlationId;
   if (includes(KINDS, v.kind)) result.kind = v.kind;
   if (typeof v.busy === 'boolean') result.busy = v.busy;
+  if (includes(['working', 'thinking', 'responding', 'tool', 'idle'], v.phase)) result.phase = v.phase;
+  if (includes(['processing', 'thinking', 'responding', 'reading_files', 'editing_files', 'running_command', 'using_tool', 'multiple_tools', 'settled'], v.detail)) result.detail = v.detail;
   if (Number.isInteger(v.port) && Number(v.port) >= 1 && Number(v.port) <= 65535) result.port = Number(v.port);
   if (includes(['coordinator', 'worker', 'anonymous'], v.role)) result.role = v.role;
   if (includes(OUTCOMES, v.outcome)) result.outcome = v.outcome;