@comput/pi-intercom 0.4.2 → 0.5.1

package/references/observability.md

@@ -1,16 +1,17 @@
 # Local observations and terminal monitor
 
-Intercom's terminal monitor is a standalone Node/pi-tui process above the coordinator in Herdr. It reads local configuration and metadata logs; it is not an agent, scheduler, durable task journal, or proof of liveness. Included in npm release 0.4.1, replacing the browser dashboard. See [README](../README.md) for installation and validation scope.
+Intercom's terminal monitor is a standalone Node/pi-tui process above the coordinator in Herdr. It reads local configuration and metadata logs; it is not an agent, scheduler, durable task journal, or proof of liveness. The basic monitor was included in npm release 0.4.1, replacing the browser dashboard. Connectivity checks/disconnected sorting described below are included in 0.5.1. See [README](../README.md) for installation and validation scope.
 
 ## Terminal-first monitoring
 
 Coordinator startup checks its saved monitor ownership and either preserves the existing pane or creates one above the coordinator. Workers do not create monitors. The pane is named `Intercom monitor`; its generic label alone is not proof of ownership. Machine-local `monitor-*.json` files record the coordinator/workspace/pane identities and partial-launch state. Uncertain operations are fenced rather than blindly repeated.
 
-The monitor refreshes from disk approximately every three seconds after the previous read finishes. It never probes workers, launches model turns, or resends messages. Arrow keys select a worker; Enter toggles its details; Escape closes details before quitting, while q/Ctrl+C always quit the monitor only. Selection follows the worker's session ID across roster reorder. Details show configured responsibility, observations and explicit public worker reports, not inferred task state or approval controls.
+The monitor refreshes from disk and performs bounded loopback identity checks, then schedules the next pass approximately three seconds after completion. It never launches model turns or resends messages. Probes do not write config or observation logs; cancelling the monitor aborts in-flight probes. Arrow keys select a worker; Enter toggles its details; Escape closes details before quitting, while q/Ctrl+C always quit the monitor only. Selection follows the worker's session ID across roster reorder. Details show configured responsibility, observations and explicit public worker reports, not inferred task state or approval controls.
 
 - **Worker:** configured name. A roster entry does not prove a process exists.
 - **Seen:** age of the status observation, not the last redraw. Evidence older than 60 seconds is marked `(old)`.
-- **Status:** last observed working, thinking, idle, closed or unknown. Closed means extension runtime closure, not guaranteed process death. Idle is not a task-completion assertion.
+- **Connection:** connected, disconnected or unknown, separate from activity. Details show fixed reason/check time. Disconnected workers sort last; names, responsibilities and session IDs remain registered.
+- **Activity:** last observed working, thinking, idle, closed or unknown. Closed means extension runtime closure, not guaranteed process death. Idle is not a task-completion assertion.
 - **Last activity:** a fixed public description of observed activity, which may remain after settlement. No reasoning or tool payload is displayed.
 - **Report:** explicitly worker-authored blocked, needs-decision or ready-for-review state, with its own timestamp and public summary in details. It is never coordinator approval or inferred from observed activity.
 - **Unknown/partial:** missing, conflicting, future-dated or unreadable evidence is not guessed. Bounded history and dropped observations can make the view incomplete.
@@ -19,7 +20,7 @@ Names and descriptions are sanitized for terminal controls and clipped to availa
 
 ## Retired browser dashboard
 
-Version 0.4.1 no longer starts a dashboard HTTP server, ships browser assets, or returns `dashboardUrl` from `intercom_list`. Only Intercom's messaging HTTP endpoints remain.
+Version 0.4.1 no longer starts a dashboard HTTP server, ships browser assets, or returns `dashboardUrl` from `intercom_list`. Only Intercom's loopback agent HTTP listeners remain; 0.5.1 adds a side-effect-free health route to those existing listeners.
 
 Old coordinator-only `dashboardPort` fields are accepted for compatibility and removed through a guarded coordinator config update at startup. Listing never advertises the retired port, even if migration failed; a migration warning does not disable messaging. Reload an older running coordinator to close its existing dashboard listener and load the new implementation.
 
@@ -49,9 +50,19 @@ Event types: `runtime.starting`, `runtime.ready`, `runtime.closed`, `runtime.fai
 
 Activity phases are `working`, `thinking`, `responding`, `tool`, `idle`. Details are `processing`, `thinking`, `responding`, `reading_files`, `editing_files`, `running_command`, `using_tool`, `multiple_tools`, `settled`. Only event discriminants and built-in tool categories are inspected. Repeated streaming phases are deduplicated, and concurrent tools take precedence over streaming hints. Thinking events are provider-dependent; missing events do not establish absence of reasoning.
 
+## Connectivity and retained sessions
+
+`GET /intercom/health` projects only version and Pi session ID after the originating runtime's lifecycle guard. It does not call the model/message acceptance path or expose prompts, arguments, results or host internals. Identity matching is correlation on trusted loopback, not authentication or a process-lock guarantee.
+
+`connections.ts` sends HTTP only to configured `127.0.0.1` ports, without redirects/proxies/retries. Limits: 4 KiB response headers, 1 KiB body, 750 ms total per-request deadline by default (including slow bodies), 4 s batch budget, 16 concurrent checks, first 256 inputs/outputs. Skipped/cancelled work is unknown, not disconnected. Missing health support, malformed data and unsupported versions remain unknown; refusal/deadline failure or mismatched session ID means disconnected/unmatched endpoint, never proven process termination.
+
+Checks expire to unknown after 30 seconds. Monitor batches rotate to avoid starvation; skipped checks may retain previous unexpired evidence. Saved-port changes/removal invalidate cached checks. Shared classification/sorting preserves config order within connected-or-unknown and disconnected groups. UI selection follows session ID across these order changes.
+
+Closing a worker does not remove config. Explicit resume uses the saved session ID, name and responsibility and requires user-confirmed closure (`confirmClosed:true`). A live matching health endpoint rejects duplicate resume. In-flight/uncertain submissions are fenced within this coordinator runtime until a later configured status announcement; preflight announcements do not qualify, and uncertain launch errors preserve the fence. Config/identity/lifecycle are rechecked before launch. These safeguards do not guarantee cross-process uniqueness, survive coordinator restart or certify OS process death. No automatic close, retry, restart or work assignment occurs.
+
 ## Read-only JSON status
 
-`intercom_worker_status` reads this same bounded snapshot, using the same `workerObservation` projection as the monitor. It returns configured workers only, optionally selected by name, with last-observed status/activity, timestamp, age, stale/unknown/conflicting evidence, and independent public reports. Missing or future evidence does not imply health. Clear tombstones appear as null reports.
+`intercom_worker_status` reads this same bounded snapshot, using the same `workerObservation` projection as the monitor. It returns configured workers only, optionally selected by name, with last-observed status/activity, timestamp, age, stale/unknown/conflicting evidence, and independent public reports. Missing or future evidence does not imply health. Clear tombstones appear as null reports. Default reads remain local-only with unknown/not_checked connections. `probe:true` checks only the selected page and returns separate connection data; disconnected entries sort last within that page. Page boundaries remain in saved config order, not global connection order.
 
 Pages default to 10 entries (limit 1–20), capped at 40 KiB before the final pagination field, below Pi's tool truncation limits. Follow `nextOffset`; each page is a new local snapshot, not a transaction spanning changing rosters. Snapshot truncation/errors are retained. No model calls, status requests, worker messages, Telegram dependencies or hidden reasoning are involved. Any presentation layer can consume the JSON.
 

package/src/connections.ts

@@ -0,0 +1,142 @@
+import http from 'node:http';
+import { setMaxListeners } from 'node:events';
+
+export type ConnectionReason = 'verified' | 'identity_mismatch' | 'unsupported_version' | 'refused' | 'timeout' | 'legacy' | 'malformed' | 'oversize' | 'http_error' | 'network_error' | 'aborted' | 'not_checked' | 'stale' | 'invalid_input';
+export interface WorkerConnection {
+  sessionId: string;
+  state: 'connected' | 'disconnected' | 'unknown';
+  checkedAt: string | null;
+  reason: ConnectionReason;
+}
+export interface ConnectionAgent { sessionId: string; port: number }
+export interface ProbeOptions { signal?: AbortSignal; timeoutMs?: number }
+export interface BatchProbeOptions extends ProbeOptions { budgetMs?: number; concurrency?: number }
+const MAX_BODY = 1024;
+const MAX_AGE = 30000;
+const MAX_WORKERS = 256;
+
+function bounded(value: number | undefined, fallback: number, maximum: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? Math.max(1, Math.min(maximum, Math.floor(value))) : fallback;
+}
+function unknown(sessionId: string, reason: ConnectionReason = 'not_checked', checkedAt: string | null = null): WorkerConnection {
+  return { sessionId, state: 'unknown', checkedAt, reason };
+}
+
+/** Read-only best-effort endpoint identity, never evidence of process termination. */
+export function probeWorker(agent: ConnectionAgent, options: ProbeOptions = {}): Promise<WorkerConnection> {
+  if (options.signal?.aborted) return Promise.resolve(unknown(agent.sessionId, 'aborted'));
+  if (typeof agent.sessionId !== 'string' || !agent.sessionId.trim() || agent.sessionId.length > 256 || !Number.isInteger(agent.port) || agent.port < 1 || agent.port > 65535) {
+    return Promise.resolve(unknown(agent.sessionId, 'invalid_input'));
+  }
+  const timeout = bounded(options.timeoutMs, 750, 4000);
+  return new Promise(resolve => {
+    let settled = false;
+    let request: http.ClientRequest | undefined;
+    let response: http.IncomingMessage | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (state: WorkerConnection['state'], reason: ConnectionReason) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      options.signal?.removeEventListener('abort', abort);
+      response?.destroy();
+      request?.destroy();
+      resolve(options.signal?.aborted
+        ? unknown(agent.sessionId, 'aborted', new Date().toISOString())
+        : { sessionId: agent.sessionId, state, reason, checkedAt: new Date().toISOString() });
+    };
+    const abort = () => finish('unknown', 'aborted');
+    const error = (error: NodeJS.ErrnoException) => {
+      if (error.code === 'ECONNREFUSED') finish('disconnected', 'refused');
+      else if (error.code === 'ETIMEDOUT') finish('disconnected', 'timeout');
+      else finish('unknown', 'network_error');
+    };
+    options.signal?.addEventListener('abort', abort, { once: true });
+    // Wall-clock deadline covers connect, headers AND the entire body, including
+    // slow-drip responses. Native HTTP ignores proxy env; no redirects/retries.
+    timer = setTimeout(() => finish('disconnected', 'timeout'), timeout);
+    try {
+      request = http.get({ hostname: '127.0.0.1', port: agent.port, path: '/intercom/health', agent: false, maxHeaderSize: 4096 }, res => {
+        response = res;
+        res.on('error', error);
+        if (settled) { res.destroy(); return; }
+        if (res.statusCode !== 200) {
+          finish('unknown', res.statusCode === 404 ? 'legacy' : 'http_error');
+          return;
+        }
+        let bytes = 0;
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk: Buffer) => {
+          bytes += chunk.length;
+          if (bytes > MAX_BODY) { finish('unknown', 'oversize'); return; }
+          chunks.push(chunk);
+        });
+        res.on('aborted', () => finish('unknown', 'network_error'));
+        res.on('end', () => {
+          if (settled) return;
+          let body: unknown;
+          try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+          catch { finish('unknown', 'malformed'); return; }
+          if (!body || typeof body !== 'object' || Array.isArray(body) ||
+            typeof (body as { version?: unknown }).version !== 'number' ||
+            typeof (body as { sessionId?: unknown }).sessionId !== 'string' ||
+            !(body as { sessionId: string }).sessionId.trim() || (body as { sessionId: string }).sessionId.length > 256) {
+            finish('unknown', 'malformed'); return;
+          }
+          const identity = body as { version: number; sessionId: string };
+          if (identity.version !== 1) finish('unknown', 'unsupported_version');
+          else if (identity.sessionId !== agent.sessionId) finish('disconnected', 'identity_mismatch');
+          else finish('connected', 'verified');
+        });
+      });
+      request.on('error', error);
+    } catch { finish('unknown', 'network_error'); }
+  });
+}
+
+/** One bounded concurrent pass; cancellation/budget exhaustion never implies disconnection. */
+export async function probeWorkers(agents: readonly ConnectionAgent[], options: BatchProbeOptions = {}): Promise<WorkerConnection[]> {
+  const boundedAgents = agents.slice(0, MAX_WORKERS);
+  const results = boundedAgents.map(agent => unknown(agent.sessionId));
+  const controller = new AbortController();
+  setMaxListeners(17, controller.signal);
+  const abort = () => controller.abort();
+  const budget = bounded(options.budgetMs, 4000, 4000);
+  const concurrency = bounded(options.concurrency, 16, 16);
+  if (options.signal?.aborted) return boundedAgents.map(agent => unknown(agent.sessionId, 'aborted'));
+  options.signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(abort, budget);
+  let next = 0;
+  try {
+    await Promise.all(Array.from({ length: Math.min(concurrency, boundedAgents.length) }, async () => {
+      while (!controller.signal.aborted && next < boundedAgents.length) {
+        const index = next++;
+        results[index] = await probeWorker(boundedAgents[index], { signal: controller.signal, timeoutMs: options.timeoutMs });
+      }
+    }));
+    return results;
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener('abort', abort);
+    controller.abort();
+  }
+}
+
+/** Health expires: an old failure must not indefinitely demote a configured worker. */
+export function currentConnection(sessionId: string, connections?: readonly WorkerConnection[], now = Date.now()): WorkerConnection {
+  const connection = connections?.find(item => item.sessionId === sessionId);
+  if (!connection) return unknown(sessionId);
+  if (connection.checkedAt === null) return unknown(sessionId, connection.state === 'unknown' ? connection.reason : 'not_checked');
+  const checked = Date.parse(connection.checkedAt);
+  if (!Number.isFinite(checked) || !Number.isFinite(now) || checked > now || now - checked > MAX_AGE) return unknown(sessionId, 'stale', connection.checkedAt);
+  return { ...connection };
+}
+
+/** Stable disconnected-last copy; does not mutate configuration or observations. */
+export function sortWorkersByConnection<T extends { sessionId: string }>(workers: readonly T[], connections?: readonly WorkerConnection[], now = Date.now()): T[] {
+  const current: T[] = [], disconnected: T[] = [];
+  for (const worker of workers) {
+    (currentConnection(worker.sessionId, connections, now).state === 'disconnected' ? disconnected : current).push(worker);
+  }
+  return [...current, ...disconnected];
+}

package/src/index.ts

@@ -14,14 +14,14 @@ 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 })) })],
+  ['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. Local-only by default; probe:true performs bounded loopback identity checks for this page only, without worker prompts or Telegram dependency. Disconnected means endpoint unreachable, not process termination. 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 })), probe: Type.Optional(Type.Boolean()) })],
   ['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],
-  ['resume_worker', 'Coordinator only. Launch saved session by ID in configured directory. No replacement/removal on failure; no old assignment is automatically started.', to],
+  ['resume_worker', 'Coordinator only. Resume saved session/name/responsibility after the user explicitly confirms the old session was closed: set confirmClosed:true only for that confirmation, never infer it from disconnected status. A matching live health endpoint blocks launch. In-flight/uncertain attempts are fenced until worker status arrives; otherwise inspect process and reload coordinator before considering retry. No cross-process uniqueness guarantee, automatic assignment, replacement or removal.', Type.Object({ to: Type.String({ minLength: 1, maxLength: 128 }), confirmClosed: Type.Boolean() })],
   ['remove_worker', 'Coordinator only. Remove config entry only; never stop process or delete session files. A running worker must be explicitly closed before removal. Stop/close are disabled on current host: arrange explicit user closure first.', to],
   ['set_multiplexer', 'Coordinator only. Set herdr (default, Windows/Linux) or none (separate visible Windows terminals; unsupported on Linux) for future launches. Never move/restart existing workers or fall back.', Type.Object({ multiplexer: Type.String({ enum: ['herdr', 'none'] }) })],
 ];

package/src/monitor-view.ts

@@ -2,6 +2,7 @@ import { stripVTControlCharacters } from 'node:util';
 import { truncateToWidth, visibleWidth } from 'pi-intercom-tui';
 import type { ObservationSnapshot } from './snapshot.js';
 import { workerObservation } from './worker-status.js';
+import { currentConnection, sortWorkersByConnection } from './connections.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)));
@@ -50,29 +51,29 @@ export function renderMonitor(snapshot: ObservationSnapshot | undefined, width:
   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 workers = sortWorkersByConnection(snapshot.config.agents.filter(agent => !agent.coordinator), snapshot.connections, now);
+    // Connection is independent of historical activity and public reports.
     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 nameWidth = wide ? Math.min(22, Math.max(10, width - 100)) : Math.max(1, Math.min(10, width - 16));
+    const activityWidth = 8, ageWidth = 16, reportWidth = 16;
+    const table = (name: string, connection: string, activity: string, age: string, detail: string, report = '—', tone = '90', selected = false) => {
+      const prefix = `${selected ? '› ' : '  '}${cell(name, nameWidth)}  `;
+      const status = cell(connection, 12);
+      const tail = `  ${cell(report, reportWidth)}  ${cell(activity, activityWidth)}${width >= 78 ? `  ${cell(age, ageWidth)}` : ''}${wide ? `  ${detail}` : ''}`;
+      // Clip each lower-priority section independently so a truncated tail never
+      // steals space from a fully fitting connection label. Styling is trusted.
       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(paint('1', table('Worker', 'Connection', 'Activity', '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 detailBudget = showDetails ? Math.min(selectedReport ? 15 : 8, 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)));
@@ -82,17 +83,25 @@ export function renderMonitor(snapshot: ObservationSnapshot | undefined, width:
       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 connection = currentConnection(worker.sessionId, snapshot.connections, now);
+      const tone = connection.state === 'disconnected' ? '33' : connection.state === 'connected' ? '32' : '90';
+      const checkedAge = connection.checkedAt ? now - Date.parse(connection.checkedAt) : NaN;
+      const connectionDetails = [
+        line(`  Connection: ${connection.state} · ${connection.reason}`),
+        line(`  Checked: ${connection.checkedAt ?? 'never'} · ${Number.isFinite(checkedAge) && checkedAge >= 0 ? ageLabel(checkedAge) : 'age unknown'}`),
+      ];
       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));
+      lines.push(table(worker.name, connection.state, 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}`))] : []),
+        const contextRows = detailBudget >= 8 ? [
+          paint('1', line(`  ${worker.name}`)),
+          ...connectionDetails,
           line(`  Responsibility: ${worker.description || 'Not specified'}`),
           line(`  Observed status: ${activity} · ${age}`),
+          ...(detailBudget >= 10 ? [line(`  Last activity: ${evidence}`)] : []),
         ] : [];
         selectedDetail = [
           ...contextRows,
@@ -101,15 +110,14 @@ export function renderMonitor(snapshot: ObservationSnapshot | undefined, width:
           ...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}`)),
+        ...connectionDetails,
         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)));
+    lines.push(...selectedDetail.slice(0, detailBudget));
     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.

package/src/monitor.ts

@@ -4,6 +4,7 @@ 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';
+import { probeWorkers, sortWorkersByConnection, type WorkerConnection } from './connections.js';
 
 export function parseMonitorRoot(args: string[]): string {
   if (args.length !== 2 || args[0] !== '--root' || !path.isAbsolute(args[1])) {
@@ -14,6 +15,8 @@ export function parseMonitorRoot(args: string[]): string {
 
 export interface MonitorOptions {
   read?: typeof readObservationSnapshot;
+  /** Injected readers do not probe unless explicitly supplied. */
+  probe?: typeof probeWorkers;
   rows: () => number;
   requestRender: () => void;
   onQuit: () => void;
@@ -24,13 +27,24 @@ export interface MonitorOptions {
   schedule?: (callback: () => void, delayMs: number) => () => void;
 }
 
-/** No host, probing, network or writes. Closing never awaits an outstanding read. */
+/** Read-only snapshots and bounded health checks. Closing never awaits pending IO. */
 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 now = options.now ?? Date.now;
+  const workers = (at = now()) => sortWorkersByConnection(snapshot?.config?.agents.filter(agent => !agent.coordinator) ?? [], snapshot?.connections, at);
+  const probe = options.probe ?? (options.read ? undefined : probeWorkers);
+  const abort = new AbortController();
+  let connections: WorkerConnection[] = [];
+  let connectionPorts = new Map<string, number>();
+  let probeStart = 0;
+  const selection = (at = now()) => {
+    const roster = workers(at);
+    const index = roster.findIndex(worker => worker.sessionId === selectedSessionId);
+    return { roster, index: index >= 0 ? index : selectedIndex };
+  };
   const requestRender = () => { try { options.requestRender(); } catch { /* UI shutdown is independent of reading. */ } };
   let closed = false, started = false;
   let cancel: (() => void) | undefined;
@@ -45,6 +59,31 @@ export function createMonitor(root: string, options: MonitorOptions): Component
     let next: ObservationSnapshot | undefined;
     try { next = await (options.read ?? readObservationSnapshot)(root); } catch { /* Unavailable, no raw errors. */ }
     if (closed) return;
+    if (next?.config && probe) {
+      const roster = next.config.agents.filter(agent => !agent.coordinator);
+      const start = roster.length ? probeStart % roster.length : 0;
+      const rotated = [...roster.slice(start), ...roster.slice(0, start)].slice(0, 256);
+      let checked: WorkerConnection[] = [];
+      try { checked = await probe(rotated, { signal: abort.signal }); } catch { /* Preserve prior checks until stale. */ }
+      if (closed) return;
+      // A check belongs to a saved endpoint, not just a session identity. Keep
+      // the last successful roster across read failures, but retire removed IDs
+      // and invalidate cached evidence when their configured port changes.
+      const ports = new Map(roster.map(worker => [worker.sessionId, worker.port]));
+      const previous = new Map(connections
+        .filter(connection => ports.has(connection.sessionId) && connectionPorts.get(connection.sessionId) === ports.get(connection.sessionId))
+        .map(connection => [connection.sessionId, connection]));
+      connectionPorts = ports;
+      for (const connection of checked) {
+        if (connection.reason !== 'not_checked' || !previous.has(connection.sessionId)) previous.set(connection.sessionId, connection);
+      }
+      connections = roster.flatMap(worker => {
+        const connection = previous.get(worker.sessionId);
+        return connection ? [connection] : [];
+      });
+      probeStart = start + Math.max(1, checked.filter(connection => connection.reason !== 'not_checked').length);
+      next = { ...next, connections };
+    }
     snapshot = next;
     // Preserve identity through reordering, and retain it across transient read failures.
     if (snapshot?.config) {
@@ -60,6 +99,7 @@ export function createMonitor(root: string, options: MonitorOptions): Component
   const close = () => {
     if (closed) return;
     closed = true;
+    abort.abort();
     cancel?.(); cancel = undefined;
   };
   return {
@@ -69,8 +109,9 @@ export function createMonitor(root: string, options: MonitorOptions): Component
     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); }
+      const at = now();
+      const view = { selectedIndex: snapshot?.config ? selection(at).index : -1, details: !!snapshot?.config && details };
+      try { return renderMonitor(snapshot, width, height, at, options.color, view); }
       catch { return renderMonitor(undefined, width, height, Date.now(), options.color, { selectedIndex: -1, details: false }); }
     },
     handleInput(data) {
@@ -81,7 +122,8 @@ export function createMonitor(root: string, options: MonitorOptions): Component
       if (matchesKey(data, 'q') || matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl('c'))) {
         close(); options.onQuit(); return;
       }
-      const roster = workers();
+      const { roster, index } = selection();
+      selectedIndex = index;
       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)));

package/src/runtime.ts

@@ -6,6 +6,7 @@ import { listen, send, reportPayload, type Endpoint, type Envelope, type Kind }
 import { saveWorkerReport } from './reports.js';
 import { readObservationSnapshot } from './snapshot.js';
 import { workerStatusPage } from './worker-status.js';
+import { probeWorker, probeWorkers } from './connections.js';
 
 export const UNSUPPORTED_CANCELLATION = 'Unsupported Pi host: stop_worker and close_worker are disabled. Pi 0.84.4 extension abort does not cancel retry backoff/continuations; graceful shutdown cannot guarantee no queued work restarts. No cancellation or shutdown was performed. See references/implementation-blocker.md. A verified supported host API is required (no version-only override).';
 export interface Host {
@@ -21,6 +22,7 @@ export interface RuntimeOptions {
   launch(request: LaunchRequest): Promise<unknown>;
   listen?: typeof listen;
   send?: typeof send;
+  probe?: typeof probeWorker;
   store?: (root: string) => ConfigStore;
   observe?: (root: string, sessionId: string) => Observer;
 }
@@ -35,6 +37,8 @@ export class Intercom {
   private closing?: Promise<void>;
   private reportWrites: Promise<void> = Promise.resolve();
   private pendingReports = 0;
+  private probeController = new AbortController();
+  private resumeFences = new Map<string, { inFlight: boolean; submitted: boolean; announced: boolean }>();
   private captureObserver(): (event: EventType, metadata?: EventMetadata) => void {
     const observer = this.observer;
     return (event, metadata = {}) => {
@@ -60,6 +64,8 @@ export class Intercom {
     if (this.closing) await this.closing;
     if (this.active) fail('runtime already active');
     this.initialId = this.host.sessionId(); this.active = true;
+    this.probeController = new AbortController();
+    this.resumeFences.clear();
     const generation = ++this.generation, assertValid = this.validity();
     let record = this.captureObserver();
     try {
@@ -72,7 +78,10 @@ export class Intercom {
       const previous = discovered ? await this.store.read() : undefined;
       assertValid();
       const own = previous?.agents.find(a => a.sessionId === this.id());
-      const endpoint = await (this.options.listen ?? listen)(own?.port, m => { assertValid(); return this.receive(m); });
+      const endpoint = await (this.options.listen ?? listen)(own?.port, m => { assertValid(); return this.receive(m); }, () => {
+        assertValid();
+        return { version: 1, sessionId: this.initialId };
+      });
       try { assertValid(); } catch (error) { await endpoint.close(); throw error; }
       this.endpoint = endpoint;
       if (!previous) {
@@ -118,6 +127,7 @@ export class Intercom {
     this.recordObservation('runtime.closed');
     const observer = this.observer; this.observer = undefined;
     this.active = false; this.generation++;
+    this.probeController.abort();
     const endpoint = this.endpoint; this.endpoint = undefined;
     this.responsibility = undefined;
     const closing = (async () => {
@@ -202,6 +212,8 @@ export class Intercom {
   private async handleReceive(message: Envelope): Promise<void> {
     const record = this.captureObserver();
     const assertValid = this.validity();
+    const receivedFence = message.kind === 'status' ? this.resumeFences.get(message.from) : undefined;
+    const eligibleAnnouncement = receivedFence?.submitted ? receivedFence : undefined;
     const { id, config, me } = await this.state();
     assertValid();
     if (message.to !== id) fail('recipient session ID mismatch (stale endpoint)');
@@ -233,6 +245,12 @@ export class Intercom {
           const entry = c.agents.find(a => a.sessionId === message.from && !a.coordinator);
           if (entry) entry.port = message.payload.port as number;
         }, assertValid);
+        assertValid();
+        const fence = sender && this.resumeFences.get(sender.sessionId);
+        if (fence && fence === eligibleAnnouncement) {
+          fence.announced = true;
+          if (!fence.inFlight) this.resumeFences.delete(sender!.sessionId);
+        }
         record('status.received', { ...metadata, busy: message.payload.busy as boolean, port: message.payload.port as number });
         if (sender) record('config.changed', { operation: 'port_update', peerSessionId: message.from, port: message.payload.port as number, outcome: 'written' });
         notify('status', JSON.stringify({ sessionId: message.from, port: message.payload.port, busy: message.payload.busy, configured: !!sender }));
@@ -291,7 +309,14 @@ export class Intercom {
       if (!me) fail('worker_status requires a configured session');
       const snapshot = await readObservationSnapshot(this.store.root);
       assertValid();
-      return workerStatusPage(snapshot, { name: args.name as string | undefined, offset: args.offset as number | undefined, limit: args.limit as number | undefined });
+      if (args.probe !== undefined && typeof args.probe !== 'boolean') fail('probe must be a boolean');
+      const pageOptions = { name: args.name as string | undefined, offset: args.offset as number | undefined, limit: args.limit as number | undefined };
+      const page = workerStatusPage(snapshot, pageOptions);
+      if (!args.probe) return page;
+      const ids = new Set(page.workers.map(worker => worker.sessionId));
+      snapshot.connections = await probeWorkers(snapshot.config?.agents.filter(agent => !agent.coordinator && ids.has(agent.sessionId)) ?? [], { signal: this.probeController.signal });
+      assertValid();
+      return workerStatusPage(snapshot, pageOptions);
     }
     if (operation === 'list') {
       if (!me) fail('anonymous intercom_list permissions unresolved (TODO); no coordinator privileges');
@@ -331,9 +356,31 @@ export class Intercom {
       return { accepted: true, completion: 'not awaited' };
     }
     if (operation === 'resume_worker') {
-      const relative = await directory(this.store.root, target.projectDirectory);
-      assertValid();
-      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), sessionId: target.sessionId });
+      if (args.confirmClosed !== true) fail('Resume requires explicit user confirmation that the previous worker session is closed (confirmClosed:true). Disconnected alone is not proof of closure.');
+      if (this.resumeFences.has(target.sessionId)) fail('Resume already in flight or awaiting worker status; outcome may be uncertain. Inspect the worker before any retry; no automatic relaunch.');
+      const fence = { inFlight: true, submitted: false, announced: false };
+      this.resumeFences.set(target.sessionId, fence);
+      let completed = false;
+      try {
+        const connection = await (this.options.probe ?? probeWorker)(target, { signal: this.probeController.signal });
+        assertValid();
+        if (connection.state === 'connected') fail('Worker endpoint is still connected; refusing to resume the same session twice.');
+        const relative = await directory(this.store.root, target.projectDirectory);
+        assertValid();
+        const cwd = path.resolve(this.store.root, relative);
+        const fresh = await this.state();
+        assertValid();
+        requireCoordinator(fresh.config, id);
+        const current = fresh.config.agents.find(agent => agent.sessionId === target.sessionId && !agent.coordinator);
+        if (!current || current.port !== target.port || current.projectDirectory !== target.projectDirectory) fail('Worker configuration changed during resume check; no launch submitted.');
+        fence.submitted = true;
+        const result = await this.launchObserved({ multiplexer: fresh.config.multiplexer, cwd, sessionId: current.sessionId });
+        completed = true;
+        return result;
+      } finally {
+        fence.inFlight = false;
+        if ((!fence.submitted || (completed && fence.announced)) && this.resumeFences.get(target.sessionId) === fence) this.resumeFences.delete(target.sessionId);
+      }
     }
     if (operation === 'remove_worker') {
       // No live process claim: the caller must explicitly ensure closure first.

package/src/snapshot.ts

@@ -3,6 +3,7 @@ import { lstat, open, opendir, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { validateConfig, type Config } from './config.js';
 import { readWorkerReports, type WorkerReport } from './reports.js';
+import type { WorkerConnection } from './connections.js';
 import { LOG_DIRECTORY, LOG_FILE_PATTERN, sanitizeObservation, type Observation } from './observability.js';
 
 const CONFIG_BYTES = 1024 * 1024, TAIL_BYTES = 128 * 1024, TOTAL_BYTES = 2 * 1024 * 1024;
@@ -14,6 +15,8 @@ export interface ObservationSnapshot {
   config: Pick<Config, 'multiplexer' | 'agents'> | null;
   events: Observation[];
   reports?: WorkerReport[];
+  /** Ephemeral explicit health checks; never persisted or inferred from activity logs. */
+  connections?: WorkerConnection[];
   truncated: boolean;
   errors: string[];
 }

package/src/transport.ts

@@ -35,9 +35,20 @@ export function envelope(value: unknown): Envelope {
   return m;
 }
 export interface Endpoint { port: number; close(): Promise<void> }
-export async function listen(preferred: number | undefined, accept: (message: Envelope) => Promise<void>): Promise<Endpoint> {
+export async function listen(preferred: number | undefined, accept: (message: Envelope) => Promise<void>, health?: () => { version: 1; sessionId: string }): Promise<Endpoint> {
   const server = http.createServer(async (req, res) => {
     const reply = (status: number, data: unknown) => { if (!res.destroyed) { res.writeHead(status, { 'content-type': 'application/json', connection: 'close' }); res.end(JSON.stringify(data)); } };
+    if (req.method === 'GET' && req.url === '/intercom/health') {
+      try {
+        if (!health) reply(404, { error: 'health unavailable' });
+        else {
+          const identity = health();
+          if (identity.version !== 1 || typeof identity.sessionId !== 'string' || !identity.sessionId.trim() || identity.sessionId.length > 256) throw new Error('invalid health identity');
+          reply(200, { version: 1, sessionId: identity.sessionId });
+        }
+      } catch { reply(503, { error: 'health unavailable' }); }
+      req.resume(); return;
+    }
     if (req.method !== 'POST' || req.url !== '/intercom') { reply(404, { error: 'POST /intercom required' }); req.resume(); return; }
     let bytes = 0;
     const chunks: Buffer[] = [];