@comput/pi-intercom 0.1.3 → 0.2.0

package/README.md

@@ -56,7 +56,7 @@ Every tool rereads current config and checks the live Pi session ID. Names are c
 | `intercom_configure_worker` | `sessionId`, `port`, `projectDirectory`, `name`, `description` | Coordinator; all five explicit fields, writes only |
 | `intercom_reload_worker` | `to` (worker name) | Coordinator; passive config/name reload |
 | `intercom_send` | `to` (name), `message` | Configured, responsibility-loaded sessions; asynchronous message |
-| `intercom_list` | None | Configured sessions; saved state only, never live health |
+| `intercom_list` | None | Configured coordinator/workers; saved roster and derived `dashboardUrl`, never live health |
 | `intercom_request_status` | `to` (worker name) | Coordinator; independent extension report |
 | `intercom_report_status` | None | Workers including anonymous; shared report function, never registration |
 | `intercom_stop_worker`, `intercom_close_worker` | `to` (worker name) | Coordinator role checked, then **unsupported-host error**, no side effects |
@@ -87,6 +87,8 @@ Shared, source-controlled file: `<root>/.pi-intercom/config.json`. Do not ignore
 }
 ```
 
+Version 0.2.0 dashboard support adds optional `dashboardPort` (integer 1–65535) on the **coordinator entry only**. Older config without it remains valid; workers cannot have it. This is separate from each agent's messaging `port`. `intercom_list` keeps `version`, `multiplexer` and `agents`, and adds top-level `dashboardUrl`: `http://127.0.0.1:<saved dashboardPort>/`, or `null` when no dashboard port is saved. It reads saved config without probing or starting a dashboard; the URL is last-known, not a liveness claim.
+
 Workers have `coordinator:false` and an existing project directory equal to root or below it. Writes canonicalize directories and check real paths (including symlink escapes). Only coordinator extension operations write config; ordinary Pi file/shell tools are not restricted.
 
 Initial creation writes/fsyncs a complete temporary file then atomically publishes via a no-replace hard link. Contenders see only complete config; exactly one wins. Unsupported hard-link filesystems fail explicitly, without unsafe fallback. Interrupted staging files can remain as ignored `.tmp` files but are never mistaken for config. Updates are serialized, join Pi's file-mutation queue, validate, fsync a temporary file and atomically rename. Duplicate activation of the same coordinator session in multiple processes and external editors racing writes remain outside V1's guarantees (session locks deferred).
@@ -101,7 +103,19 @@ Kinds: `message`, `registration` (`port`, `projectDirectory`), `status` (`port`,
 
 `202 {"accepted":true}` means Intercom extension receipt/dispatch, **not guaranteed Pi input acceptance, queueing, or model completion**. In Pi 0.84.4, `sendUserMessage` can reject during manual compaction after Intercom has acknowledged receipt: its void extension API reports the asynchronous rejection only as a local host error. Intercom has no delivery queue or retry to repair this gap; inspect the recipient's local error and arrange an explicit resend after compaction if needed. Replacing it with `sendMessage` is not a safe workaround because that path can start a concurrent run. Invalid/unsupported requests return an error; excessive bodies return 413. Request-status sends its report separately after accepting control. Delivery is normal when idle and steering when busy, sampled at arrival. It does not hard-interrupt an executing tool. Each send resolves the recipient again from config; 5-second receipt deadline, **no retries**. Timeout means unknown outcome, not proof of nondelivery. No durable inbox, deduplication or replay log in V1.
 
-Tool text output is bounded to 50 KiB/2000 lines. Full list data remains in the shared config file. Name sync errors are surfaced; startup retains the useful endpoint, and explicit reload reports failure (Pi name/responsibility may already have changed before a Herdr tab rename fails).
+Version 0.2.0 telemetry adds an optional envelope `correlationId` for one transport attempt; legacy envelopes without it remain accepted. It is not agent identity, deduplication, a task ID, or a reply/completion guarantee.
+
+Tool text output is bounded to 50 KiB/2000 lines. The full saved roster remains in the shared config file; `dashboardUrl` is derived for list output. Name sync errors are surfaced; startup retains the useful endpoint, and explicit reload reports failure (Pi name/responsibility may already have changed before a Herdr tab rename fails).
+
+## Local observation dashboard (0.2.0)
+
+Current source adds metadata-only event logs and a coordinator-only, read-only localhost dashboard. Startup binds an OS-assigned port, then saves the actual port as the coordinator's `dashboardPort` and prints the local URL. Configured coordinator and worker sessions can retrieve the saved URL using `intercom_list`—no new dashboard tool or control. Open that URL in a local browser. The saved address can remain stale after shutdown or failure; it is not proof of reachability. Workers log metadata but do not start a dashboard. No browser opens automatically, and no agent controls, assignments or automatic recovery are added.
+
+The roster shows saved names/responsibilities/endpoints plus **last-observed** busy/idle, timestamp and age. Evidence older than 60 seconds is marked stale, never offline; missing evidence is unknown. The timeline refreshes approximately every three seconds and can be filtered by agent, event type and errors. Expand events for safe metadata/correlation, not prompt bodies. A disconnected dashboard retains old data with an explicit warning.
+
+Logs under `.pi-intercom/logs/` exclude message bodies and raw errors; roster responsibility text still comes from shared config, so do not put secrets there. `writerId` identifies an ephemeral log writer, not an agent; Pi session ID remains agent identity. Transport `correlationId` identifies one send attempt, not a task or completion. Logging is bounded/best effort and does not change HTTP receipt semantics or repair manual-compaction rejection. Never interpret a quiet timeline as completed work.
+
+See [observability reference](references/observability.md) for privacy, rotation/retention limits, partial-error semantics and the HTTP boundary. This feature requires **version 0.2.0 or later**; update the package and reload each participating Pi session to activate it. The dashboard is not a durable inbox, replay log or task journal.
 
 ## Development and validation
 
@@ -131,6 +145,8 @@ Published versions are immutable. For a new release, bump package and lockfile v
 - [v0.1.1](https://github.com/mbundgaard/PiIntercom/releases/tag/v0.1.1): successful npm OIDC [run 35466923379](https://github.com/mbundgaard/PiIntercom/actions/runs/35466923379).
 - [v0.1.2](https://github.com/mbundgaard/PiIntercom/releases/tag/v0.1.2): successful npm OIDC [run 35467586052](https://github.com/mbundgaard/PiIntercom/actions/runs/35467586052). Fixes Windows Herdr launching by using `herdr pane run` on the returned pane ID with encoded PowerShell invoking `pi.ps1`, instead of the failing `Start-Process pi` wrapper. No Herdr agent alias is needed.
 
+- [v0.1.3](https://github.com/mbundgaard/PiIntercom/releases/tag/v0.1.3): successful npm OIDC [run 35474304380](https://github.com/mbundgaard/PiIntercom/actions/runs/35474304380). Contains the fixes below, not the observability feature added in 0.2.0.
+
 ### 0.1.3 changes and verification
 
 Version 0.1.3 includes these fixes (not present in 0.1.2):
@@ -139,7 +155,15 @@ Version 0.1.3 includes these fixes (not present in 0.1.2):
 - Failed temporary-file write, sync or close attempts best-effort close/unlink cleanup while preserving the primary error. Filesystem cleanup failures can still leave temporary files.
 - Resume preflight now follows the child session-storage context: `PI_CODING_AGENT_SESSION_DIR`, then target-project/global `sessionDir` settings, then Pi's default. Relative storage paths resolve against the target working directory. Launchers do not propagate the coordinator's CLI `--session-dir`; no machine-specific session path is stored in shared config. A static persisted-session fixture and mocked launcher validate lookup, not live resumed-worker startup.
 
-Coordinator validation of this source snapshot: `npm run typecheck` PASS; `npm test` **36/36**, no failures; `npm run check:package` PASS; `git diff --check` PASS (line-ending warnings only). Quality independently confirmed typecheck and all 36 tests, with no remaining actionable regression identified in these fixes. Tests include actual extension-adapter event handling against a mocked Pi API/context and runtime-to-runtime loopback HTTP; they do not establish real Pi queue or compaction behavior.
+Pre-observability fix milestone: coordinator validation recorded `npm run typecheck` PASS; `npm test` **36/36**, no failures; `npm run check:package` PASS; `git diff --check` PASS (line-ending warnings only). Quality independently confirmed typecheck and all 36 tests, with no remaining actionable regression identified in those fixes. This count predates the logging/dashboard changes; it is not their aggregate validation. Tests include actual extension-adapter event handling against a mocked Pi API/context and runtime-to-runtime loopback HTTP; they do not establish real Pi queue or compaction behavior.
+
+### 0.2.0 observability validation
+
+Coordinator and Quality independently ran `npm run typecheck && npm test`: **63/63 tests passed, zero skips**. Coordinator also confirmed the 15-file package dry-run (dashboard assets and observability reference included; runtime logs excluded) and a clean `git diff --check`.
+
+Coverage includes bounded metadata logging, transport/runtime instrumentation, read-only dashboard HTTP/security, actual UI code against hostile-text DOM fixtures, actual bound-port persistence before readiness, passive saved-URL discovery, bind/persistence failures and shutdown races. These use mocked Pi hosts and test-only loopback services; no live Pi dashboard startup or URL-liveness guarantee is claimed.
+
+A separate synthetic-browser smoke check verified desktop rendering, literal hostile labels, unknown/stale evidence, error filtering and expandable metadata. Browser native-click automation timed out; programmatic DOM clicks verified the interactions instead, so this is not a full keyboard/mouse accessibility or live Pi end-to-end test.
 
 Tests use temporary directories, local test-only HTTP servers, static session fixtures and mocked Pi hosts/launch executors. They never start agents, tabs, terminals, contact models, services or bridges, or access credentials.
 

package/dashboard/app.js

@@ -0,0 +1,182 @@
+'use strict';
+
+(() => {
+  const byId = id => document.getElementById(id);
+  const ui = Object.fromEntries(['roster', 'events', 'notice', 'connection-state', 'snapshot-time', 'roster-count', 'event-count', 'event-window', 'worker-filter', 'type-filter', 'errors-filter'].map(id => [id, byId(id)]));
+  const refreshMs = 3000;
+  let snapshot = null;
+  let connected = false;
+  let eventSignature = '';
+  const safeText = (value, max = 4096) => typeof value === 'string' ? value.slice(0, max) : '';
+  const timestamp = value => typeof value === 'string' ? Date.parse(value) : NaN;
+  const node = (tag, text, className) => {
+    const result = document.createElement(tag);
+    if (text !== undefined) result.textContent = String(text);
+    if (className) result.className = className;
+    return result;
+  };
+  const formatDate = value => Number.isFinite(timestamp(value)) ? new Date(value).toLocaleString() : 'Unknown time';
+  const age = value => {
+    const milliseconds = Date.now() - timestamp(value);
+    if (!Number.isFinite(milliseconds)) return 'Age unknown';
+    if (milliseconds < -5000) return 'Clock ahead; age uncertain';
+    const seconds = Math.max(0, Math.floor(milliseconds / 1000));
+    if (seconds < 60) return `${seconds}s ago`;
+    if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
+    return `${Math.floor(seconds / 3600)}h ago`;
+  };
+  const isError = event => Boolean(event.errorCode) || ['error', 'failed', 'failure', 'rejected', 'handler_failed'].includes(event.outcome) || /(?:^|\.)(?:error|failed|failure|rejected)$/.test(event.event);
+  const agents = () => Array.isArray(snapshot?.config?.agents) ? snapshot.config.agents : [];
+  const events = () => Array.isArray(snapshot?.events) ? snapshot.events : [];
+  const agentName = id => safeText(agents().find(agent => agent.sessionId === id)?.name, 128) || safeText(id, 256) || 'Unknown agent';
+
+  function renderRoster() {
+    const observed = new Map();
+    for (const event of events()) {
+      if (!['runtime.ready', 'host.activity'].includes(event.event) || typeof event.busy !== 'boolean' || !Number.isFinite(timestamp(event.timestamp))) continue;
+      const previous = observed.get(event.sessionId);
+      if (!previous || timestamp(event.timestamp) >= timestamp(previous.timestamp)) observed.set(event.sessionId, event);
+    }
+    ui['roster-count'].textContent = String(agents().length);
+    const fragment = document.createDocumentFragment();
+    for (const agent of agents()) {
+      const article = node('article', undefined, 'agent');
+      article.append(node('h3', safeText(agent.name, 128) || 'Unnamed agent'));
+      article.append(node('span', agent.coordinator ? 'Coordinator' : 'Worker', 'agent-role'));
+      article.append(node('p', safeText(agent.description) || 'No responsibility recorded.', 'responsibility'));
+      const port = Number.isInteger(agent.port) && agent.port > 0 && agent.port <= 65535 ? `127.0.0.1:${agent.port}` : 'Unknown endpoint';
+      article.append(node('p', `Saved endpoint · ${port}`, 'endpoint'));
+      article.append(node('p', `Pi session · ${safeText(agent.sessionId, 256)}`, 'identity'));
+      const observation = observed.get(agent.sessionId);
+      const badges = node('div', undefined, 'observation');
+      if (!observation) {
+        badges.append(node('span', 'Status unknown', 'badge'));
+        article.append(badges, node('p', 'No busy/idle observation in the retained event window.', 'observed-time'));
+      } else {
+        const elapsed = Date.now() - timestamp(observation.timestamp);
+        const stale = elapsed > snapshot.staleAfterMs;
+        const uncertain = elapsed < -5000;
+        badges.append(node('span', observation.busy ? 'Observed busy' : 'Observed idle', 'badge badge-observed'));
+        badges.append(node('span', uncertain ? 'Clock uncertain' : stale ? 'Stale evidence' : 'Recent evidence', `badge${stale || uncertain ? ' badge-stale' : ''}`));
+        article.append(badges, node('p', `${formatDate(observation.timestamp)} · ${age(observation.timestamp)}${!connected ? ' · Dashboard disconnected' : ''}`, 'observed-time'));
+      }
+      fragment.append(article);
+    }
+    if (!agents().length) fragment.append(node('p', snapshot?.config ? 'No agents in this snapshot.' : 'Saved configuration is unavailable. No roster can be inferred from events.', 'empty'));
+    ui.roster.replaceChildren(fragment);
+  }
+
+  function syncOptions(select, values, allLabel) {
+    const signature = JSON.stringify(values);
+    if (select.dataset.options === signature) return;
+    const selected = select.value;
+    select.replaceChildren(new Option(allLabel, ''));
+    for (const [value, label] of values) select.append(new Option(label, value));
+    if (values.some(([value]) => value === selected)) select.value = selected;
+    select.dataset.options = signature;
+  }
+
+  function syncFilters() {
+    const ids = new Set(agents().map(agent => agent.sessionId));
+    for (const event of events()) {
+      if (event.sessionId) ids.add(event.sessionId);
+      if (event.peerSessionId) ids.add(event.peerSessionId);
+    }
+    syncOptions(ui['worker-filter'], [...ids].sort().map(id => [id, agentName(id)]), 'All agents');
+    syncOptions(ui['type-filter'], [...new Set(events().map(event => event.event))].sort().map(type => [type, type]), 'All types');
+  }
+
+  function renderEvents() {
+    const worker = ui['worker-filter'].value;
+    const type = ui['type-filter'].value;
+    const onlyErrors = ui['errors-filter'].checked;
+    const filtered = events().filter(event => (!worker || event.sessionId === worker || event.peerSessionId === worker) && (!type || event.event === type) && (!onlyErrors || isError(event))).slice().reverse();
+    ui['event-count'].textContent = `${filtered.length} / ${events().length}`;
+    ui['event-window'].textContent = `${snapshot?.truncated ? 'Bounded window: earlier or excess records omitted. ' : 'Retained event window. '}Newest first. Status evidence older than ${Math.round((snapshot?.staleAfterMs || 60000) / 1000)} seconds is marked stale, not offline.`;
+    const signature = JSON.stringify([filtered, agents().map(agent => [agent.sessionId, agent.name])]);
+    if (signature === eventSignature) return;
+    eventSignature = signature;
+    const opened = new Set([...ui.events.querySelectorAll('details[open]')].map(item => item.dataset.key));
+    const focusedKey = document.activeElement?.closest('details')?.dataset.key;
+    const fragment = document.createDocumentFragment();
+    const metadata = [
+      ['timestamp', 'Timestamp'], ['sessionId', 'Pi session'], ['peerSessionId', 'Peer session'],
+      ['peerName', 'Peer label'], ['writerId', 'Telemetry writer'], ['correlationId', 'Correlation ID'],
+      ['kind', 'Wire kind'], ['operation', 'Operation'], ['role', 'Observed role'],
+      ['outcome', 'Outcome'], ['errorCode', 'Error code'], ['busy', 'Busy snapshot'], ['port', 'Observed port'],
+    ];
+    const occurrences = new Map();
+    filtered.forEach(event => {
+      const details = node('details', undefined, 'event');
+      const identity = JSON.stringify(event);
+      const occurrence = occurrences.get(identity) || 0;
+      occurrences.set(identity, occurrence + 1);
+      const key = `${identity}:${occurrence}`;
+      details.dataset.key = key;
+      details.open = opened.has(key);
+      const summary = node('summary');
+      const time = node('time', Number.isFinite(timestamp(event.timestamp)) ? new Date(event.timestamp).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' }) : 'Unknown', 'event-time');
+      if (Number.isFinite(timestamp(event.timestamp))) time.dateTime = event.timestamp;
+      time.title = formatDate(event.timestamp);
+      const label = node('span');
+      label.append(node('span', safeText(event.event, 128), 'event-name'));
+      label.append(node('span', `${agentName(event.sessionId)}${event.peerSessionId ? ` · peer ${agentName(event.peerSessionId)}` : ''}`, 'event-route'));
+      if (isError(event)) label.append(node('span', 'Error recorded', 'badge badge-error'));
+      summary.append(time, label);
+      details.append(summary);
+      const list = node('dl');
+      for (const [field, title] of metadata) {
+        const value = event[field];
+        if (!['string', 'number', 'boolean'].includes(typeof value)) continue;
+        list.append(node('dt', title), node('dd', typeof value === 'string' ? safeText(value) : String(value)));
+      }
+      details.append(list);
+      fragment.append(details);
+    });
+    if (!filtered.length) fragment.append(node('p', events().length ? 'No events match these filters. Choose another agent or event type.' : 'No readable events in this window. This does not indicate that agents are idle or work is complete.', 'empty'));
+    ui.events.replaceChildren(fragment);
+    if (focusedKey) [...ui.events.querySelectorAll('details')].find(item => item.dataset.key === focusedKey)?.querySelector('summary')?.focus({ preventScroll: true });
+  }
+
+  const errorLabels = {
+    config_unavailable: 'Shared configuration could not be read.',
+    logs_unavailable: 'Event logs are unavailable.',
+    log_read_failed: 'Some event logs could not be read.',
+  };
+  function renderNotice(failed = false) {
+    const messages = failed ? ['Dashboard disconnected or snapshot unavailable. Last received data is retained below; it is not current process status. Refresh attempts continue automatically.'] : [];
+    for (const code of snapshot?.errors || []) messages.push(errorLabels[code] || 'Part of this snapshot is unavailable.');
+    ui.notice.textContent = [...new Set(messages)].join(' ');
+    ui.notice.hidden = !messages.length;
+  }
+
+  async function refresh() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 8000);
+    try {
+      const response = await fetch('/api/snapshot', { cache: 'no-store', credentials: 'omit', signal: controller.signal });
+      if (!response.ok) throw new Error('snapshot_unavailable');
+      const value = await response.json();
+      if (value?.version !== 1 || !Array.isArray(value.events) || !Array.isArray(value.errors) || !Number.isFinite(timestamp(value.generatedAt))) throw new Error('snapshot_invalid');
+      snapshot = { ...value, events: value.events.filter(event => event && typeof event.event === 'string').slice(-500), staleAfterMs: Number.isFinite(value.staleAfterMs) && value.staleAfterMs > 0 ? value.staleAfterMs : 60000 };
+      connected = true;
+      ui['connection-state'].textContent = 'Local dashboard connected';
+      ui['snapshot-time'].textContent = `Snapshot ${formatDate(snapshot.generatedAt)}`;
+      renderNotice();
+      syncFilters();
+      renderRoster();
+      renderEvents();
+    } catch {
+      connected = false;
+      ui['connection-state'].textContent = 'Dashboard disconnected';
+      renderNotice(true);
+      if (snapshot) renderRoster();
+    } finally {
+      clearTimeout(timeout);
+      setTimeout(refresh, refreshMs);
+    }
+  }
+  document.querySelector('.filters').addEventListener('submit', event => event.preventDefault());
+  for (const id of ['worker-filter', 'type-filter', 'errors-filter']) ui[id].addEventListener('change', renderEvents);
+  void refresh();
+})();

package/dashboard/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light">
+  <title>PiIntercom · Observation ledger</title>
+  <link rel="stylesheet" href="/style.css">
+  <script src="/app.js" defer></script>
+</head>
+<body>
+  <a class="skip-link" href="#timeline">Skip to event timeline</a>
+  <header class="masthead">
+    <div><p class="eyebrow">PiIntercom / Local observation</p><h1>Communication, observed.</h1>
+      <p class="intro">A read-only record of agents and their exchanges. Pi decides the work.</p></div>
+    <div class="connection"><span id="connection-state" role="status">Connecting to local dashboard…</span><p id="snapshot-time">No snapshot received</p><span class="read-only">Read only · Refreshes every 3 seconds</span></div>
+  </header>
+  <main>
+    <div id="notice" class="notice" role="status" hidden></div>
+    <div class="workspace">
+      <section class="roster-panel" aria-labelledby="roster-heading">
+        <div class="section-heading"><h2 id="roster-heading">Configured agents</h2><span id="roster-count" class="count">—</span></div>
+        <p class="help">Saved endpoints are not proof of a running process. Busy and idle are last-observed snapshots, not availability.</p>
+        <div id="roster" class="roster"><p class="empty">Waiting for the saved roster.</p></div>
+      </section>
+      <section id="timeline" class="timeline-panel" aria-labelledby="timeline-heading" tabindex="-1">
+        <div class="section-heading"><h2 id="timeline-heading">Exchange ledger</h2><span id="event-count" class="count">—</span></div>
+        <p class="help">Metadata only. Receipt does not prove Pi accepted the input or completed work.</p>
+        <form class="filters" aria-label="Filter event timeline">
+          <div><label for="worker-filter">Agent</label><select id="worker-filter"><option value="">All agents</option></select></div>
+          <div><label for="type-filter">Event type</label><select id="type-filter"><option value="">All types</option></select></div>
+          <label class="checkbox"><input id="errors-filter" type="checkbox">Errors only</label>
+        </form>
+        <p id="event-window" class="window-note">Waiting for event metadata.</p>
+        <div id="events" class="events"><p class="empty">The ledger will appear after the first snapshot.</p></div>
+      </section>
+    </div>
+  </main>
+  <footer><strong>Observe, don't infer.</strong> A quiet timeline may mean no recent events, unavailable logging, or an unreachable dashboard—not completed work. No assignments or agent controls are available here.</footer>
+</body>
+</html>

package/dashboard/style.css

@@ -0,0 +1,82 @@
+:root {
+  --canvas: #e9eff5;
+  --paper: #ffffff;
+  --ink: #20354b;
+  --muted: #526477;
+  --blue: #326080;
+  --line: #c7d3df;
+  --wash: #f3f6fa;
+  --warning: #854617;
+  --warning-wash: #fff3e6;
+  font-family: "Segoe UI", system-ui, sans-serif;
+  color: var(--ink);
+  background: var(--canvas);
+  font-synthesis: none;
+}
+* { box-sizing: border-box; }
+body { margin: 0; }
+[hidden] { display: none !important; }
+a { color: var(--blue); }
+:focus-visible { outline: 3px solid var(--blue); outline-offset: 4px; }
+.skip-link { position: absolute; left: 16px; top: -80px; padding: 12px; background: var(--paper); z-index: 2; }
+.skip-link:focus { top: 12px; }
+.masthead { display: flex; justify-content: space-between; gap: 32px; padding: 38px clamp(20px, 4vw, 64px) 30px; border-top: 7px solid var(--blue); }
+.eyebrow { margin: 0 0 12px; color: var(--blue); text-transform: uppercase; letter-spacing: .12em; font-size: .72rem; font-weight: 750; }
+h1 { font: 400 clamp(2rem, 3.3vw, 3.2rem)/1.08 Georgia, "Times New Roman", serif; margin: 0; letter-spacing: -.025em; }
+.intro { color: var(--muted); line-height: 1.5; margin: 14px 0 0; }
+.connection { align-self: center; flex: 0 0 275px; border-left: 2px solid var(--line); padding-left: 22px; font-size: .86rem; }
+#connection-state { font-weight: 700; }
+#snapshot-time { color: var(--muted); margin: 7px 0 12px; line-height: 1.4; }
+.read-only { font: .72rem/1.5 Consolas, monospace; color: var(--muted); }
+main { margin: 0 clamp(16px, 4vw, 64px); }
+.notice { background: var(--warning-wash); border-left: 4px solid var(--warning); padding: 14px 18px; margin-bottom: 18px; line-height: 1.5; color: var(--warning); }
+.workspace { display: grid; grid-template-columns: minmax(260px, 340px) minmax(0, 1fr); border: 1px solid var(--line); background: var(--paper); border-radius: 8px; overflow: hidden; }
+.roster-panel { background: var(--wash); border-right: 1px solid var(--line); padding: 26px 22px; }
+.timeline-panel { padding: 26px clamp(18px, 2.5vw, 36px); min-width: 0; }
+.section-heading { display: flex; justify-content: space-between; align-items: baseline; gap: 12px; }
+h2 { margin: 0; font-size: 1.1rem; font-weight: 700; }
+.count { font: .8rem Consolas, monospace; color: var(--muted); }
+.help { color: var(--muted); font-size: .82rem; line-height: 1.55; margin: 12px 0 23px; }
+.agent { border-top: 1px solid var(--line); padding: 20px 0; overflow-wrap: anywhere; }
+.agent h3 { font-size: 1rem; margin: 0 0 7px; }
+.agent-role { font: .7rem Consolas, monospace; color: var(--blue); text-transform: uppercase; letter-spacing: .06em; }
+.responsibility { font-size: .84rem; line-height: 1.55; margin: 10px 0 14px; }
+.endpoint, .identity { font: .72rem/1.5 Consolas, monospace; color: var(--muted); margin: 4px 0; }
+.observation { display: flex; flex-wrap: wrap; gap: 7px; margin-top: 15px; }
+.badge { display: inline-block; padding: 4px 8px; border: 1px solid var(--line); border-radius: 4px; font-size: .72rem; font-weight: 650; color: var(--muted); background: var(--paper); }
+.badge-observed { color: var(--blue); border-color: #a8bfce; }
+.badge-stale, .badge-error { color: var(--warning); border-color: #d5b594; background: var(--warning-wash); }
+.observed-time { color: var(--muted); font-size: .72rem; line-height: 1.5; margin: 8px 0 0; }
+.filters { display: flex; flex-wrap: wrap; align-items: flex-end; gap: 14px; padding: 16px; background: var(--wash); border-radius: 5px; }
+.filters > div { flex: 1 1 160px; min-width: 0; }
+.filters label { display: block; font-size: .76rem; font-weight: 650; margin-bottom: 7px; }
+select { width: 100%; min-height: 38px; font: inherit; font-size: .84rem; border: 1px solid #98acbf; border-radius: 3px; padding: 7px 24px 7px 9px; color: var(--ink); background: var(--paper); }
+.filters .checkbox { display: flex; gap: 7px; align-items: center; min-height: 38px; margin: 0; }
+input[type="checkbox"] { width: 17px; height: 17px; accent-color: var(--blue); }
+.window-note { font-size: .73rem; color: var(--muted); line-height: 1.5; margin: 16px 0; }
+.event { border-top: 1px solid var(--line); padding: 15px 0; }
+.event summary { display: grid; grid-template-columns: 82px minmax(0, 1fr) auto; gap: 12px; cursor: pointer; align-items: baseline; list-style: none; }
+.event summary::-webkit-details-marker { display: none; }
+.event summary::after { content: "+"; color: var(--blue); font: 1.15rem Consolas, monospace; }
+.event[open] summary::after { content: "−"; }
+.event-time { font: .76rem/1.5 Consolas, monospace; color: var(--muted); }
+.event-name { display: block; font-size: .88rem; font-weight: 650; overflow-wrap: anywhere; }
+.event-route { display: block; margin-top: 5px; font-size: .76rem; line-height: 1.5; color: var(--muted); overflow-wrap: anywhere; }
+.event dl { display: grid; grid-template-columns: 120px minmax(0, 1fr); gap: 8px 14px; margin: 15px 0 0 94px; padding: 15px; background: var(--wash); font-size: .76rem; }
+.event dt { color: var(--muted); }
+.event dd { margin: 0; font-family: Consolas, monospace; overflow-wrap: anywhere; }
+.empty { padding: 28px 0; color: var(--muted); line-height: 1.6; font-size: .9rem; }
+footer { max-width: 950px; color: var(--muted); margin: 24px clamp(20px, 4vw, 64px) 40px; font-size: .77rem; line-height: 1.6; }
+footer strong { color: var(--ink); }
+@media (max-width: 850px) {
+  .masthead { display: block; padding-top: 28px; }
+  .connection { margin-top: 24px; padding-left: 15px; }
+  .workspace { grid-template-columns: 1fr; }
+  .roster-panel { border-right: 0; border-bottom: 1px solid var(--line); }
+  .roster { display: grid; grid-template-columns: repeat(auto-fit, minmax(230px, 1fr)); gap: 0 22px; }
+}
+@media (max-width: 480px) {
+  .event summary { grid-template-columns: 65px minmax(0, 1fr) auto; gap: 8px; }
+  .event dl { margin-left: 0; grid-template-columns: 90px minmax(0, 1fr); }
+}
+@media (prefers-reduced-motion: reduce) { *, *::before, *::after { scroll-behavior: auto !important; } }

package/package.json

@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/mbundgaard/PiIntercom/issues"
   },
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Explicit local communication between Pi sessions; Pi orchestrates.",
   "type": "module",
   "keywords": [
@@ -25,7 +25,9 @@
   },
   "files": [
     "src",
+    "dashboard",
     "README.md",
+    "references/observability.md",
     "references/v1-specification.md",
     "references/implementation-blocker.md"
   ],
@@ -45,7 +47,7 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "test": "npm run build && node --test tests/core.test.mjs tests/integration.test.mjs tests/launcher.test.mjs tests/extension.test.mjs tests/runtime-http.test.mjs tests/resume-storage.test.mjs",
+    "test": "npm run build && node --test tests/core.test.mjs tests/integration.test.mjs tests/launcher.test.mjs tests/extension.test.mjs tests/runtime-http.test.mjs tests/resume-storage.test.mjs tests/observability.test.mjs tests/dashboard.test.mjs tests/dashboard-security.test.mjs tests/observability-integration.test.mjs",
     "test:host": "node --test tests/pi-cancellation-probe.test.mjs",
     "check:package": "npm pack --dry-run --ignore-scripts"
   }

package/references/observability.md

@@ -0,0 +1,104 @@
+# Local event logs and read-only dashboard
+
+Available starting in **version 0.2.0**; not part of version 0.1.3. Validation status is tracked in [README](../README.md). This is observation, not orchestration, a durable task journal, or proof of agent liveness.
+
+## Opening the dashboard
+
+Coordinator startup automatically binds a separate HTTP listener to `127.0.0.1` on an OS-selected port, writes the actual bound port to its shared coordinator entry as `dashboardPort`, and prints the local dashboard URL in Pi. Open that exact URL in a local browser. No browser is opened automatically. Workers write local event metadata but do not start dashboard listeners. Extension teardown closes the dashboard and its active connections; a later startup can use a different URL.
+
+`dashboardPort` is optional and coordinator-only, an integer from 1 through 65535. Existing configuration without it remains valid. It is **not the messaging `port`** and does not change agent-message routing. The saved port is last-known metadata; it is not a requested bind port or a guarantee that any process is listening.
+
+Configured coordinators and workers can call existing `intercom_list` to obtain top-level `dashboardUrl`, derived as `http://127.0.0.1:<saved dashboardPort>/`, or `null` if the coordinator has no saved dashboard port. The result retains `version`, `multiplexer` and `agents`. Listing only reads shared config: it does not probe, start, rebind or control the dashboard. A previously saved address remains after closure or startup failure, so a non-null URL is **not proof of dashboard liveness**. No new tool or dashboard control is added.
+
+The URL is announced only after the new bound port has been saved and startup lifecycle checks still pass. If saving fails, the newly created dashboard is closed and a local error is shown; Intercom messaging remains available. The previous saved URL, if any, is not cleared and can be stale. Shutdown likewise leaves the saved field intact. Startup does not request or reuse the saved dashboard port.
+
+The dashboard polls its read-only snapshot endpoint every three seconds after the preceding request settles, with an eight-second client timeout. It has no agent controls, assignment forms, send buttons, stop/close, recovery actions, or retry controls. Its refresh loop only rereads telemetry; it does not resend Intercom messages or probe workers.
+
+### Reading the screen
+
+- **Configured agents:** names, responsibilities, saved endpoints and Pi session IDs come from shared configuration. Saved entries do not establish whether a process exists. Responsibility is not an assignment.
+- **Observed busy / observed idle:** the most recent `runtime.ready` or `host.activity` event in the retained window for that Pi session. The event's own timestamp and age are shown. `status.received` is not attributed to its writer as that writer's busy state; its `busy` value describes the reporting peer.
+- **Stale evidence:** an observation older than 60 seconds. It does not mean offline: a legitimately idle host may emit no new activity. **Unknown** means no eligible observation in the retained window, not idle or unavailable. Future-dated observations are marked clock-uncertain.
+- **Exchange ledger:** newest metadata first; filter by agent (including either side of an exchange), event type, or errors. Expand a row for allowlisted fields and correlation. Receipt, submission, and host activity are separate facts, not task-completion states.
+- **Disconnected / partial snapshot:** the banner states the problem. Previously received data may remain visible and continues to age; it must not be treated as current process status. An empty timeline does not prove no activity occurred.
+
+The UI uses local HTML/CSS/JavaScript, with no CDN or remote fonts. Event/config text is inserted as text, never as executable HTML. It displays selected roster fields, not a raw config dump.
+
+## Privacy and event contract
+
+Logs live under `<coordinator-root>/.pi-intercom/logs/`. They are **metadata-only**: there is no prompt-body logging mode in this implementation. Message bodies, tool arguments/results, credentials, raw error messages/stacks, and responsibility text are not copied into log events. The dashboard separately reads configured names and responsibilities for its roster; do not put secrets in those fields. Metadata can still be sensitive: session IDs, human labels, endpoints, timings and communication patterns may identify your work. Keep logs local and do not commit or publish them. Shared `config.json` remains the source-controlled configuration; logging does not move IDs or ports out of it.
+
+Version 1 event fields:
+
+| Field | Meaning |
+|---|---|
+| `version` | `1` |
+| `timestamp` | UTC ISO observation time, not a global ordering guarantee |
+| `sessionId` | Actual Pi agent/session identity |
+| `writerId` | Ephemeral UUID for this log writer/file group only; **not a new agent or transport identity** |
+| `event` | Allowlisted event type |
+| `peerSessionId`, `peerName` | Optional peer metadata |
+| `correlationId` | Optional identifier for one transport attempt, not a task, reply promise or completion token |
+| `kind`, `operation`, `role`, `outcome` | Optional allowlisted metadata values |
+| `busy`, `port` | Optional observed boolean / port |
+| `errorCode` | Optional fixed safe error label; no raw exception text |
+
+Current event types: `runtime.starting`, `runtime.ready`, `runtime.closed`, `runtime.failed`, `config.changed`, `config.reloaded`, `transport.send`, `transport.receipt`, `transport.failed`, `transport.received`, `transport.rejected`, `registration.received`, `status.received`, `launch.result`, `host.submission`, `host.activity`, `host.ui_prompt`.
+
+A sender generates an optional wire-envelope `correlationId` for each send; the receiver can record it too. Legacy envelopes without it are accepted. It provides trace correlation only: no deduplication, replay, durable delivery or synchronous request/reply behavior is introduced.
+
+### What the records do not establish
+
+- `transport.receipt` / `http_receipt` means the sender saw HTTP acceptance. It does **not** prove Pi accepted or queued the input, nor that a model turn or assignment completed.
+- `host.submission` with `attempted`, `returned` or `failed` records a synchronous host call. Pi 0.84.4's void `sendUserMessage` binding can report an asynchronous manual-compaction rejection only locally after HTTP acceptance. Logging does not fix or reliably observe that asynchronous rejection.
+- `host.activity` `started`/`settled` observes host activity, not a particular message's result. Busy snapshots are not availability guarantees.
+- `launch.result` does not establish agent readiness. `host.ui_prompt` does not authorize work. Neither monitoring nor errors trigger orchestration.
+- Stop/close remain disabled. Telemetry does not add cancellation, forced shutdown, retries, recovery or rollback.
+
+## Storage bounds and failure behavior
+
+Each writer appends newline-delimited JSON to `writer-<UUID>.jsonl` and rotates through `.jsonl.1` and `.jsonl.2`.
+
+| Bound | Policy |
+|---|---|
+| Active/rotated file size | 1 MiB each, up to three data files per writer |
+| Event size | At most 4 KiB per JSONL record |
+| In-memory writer queue | At most 256 queued entries plus one in-flight entry; excess records are dropped |
+| Closed-group retention | Seven days; cleanup can remove older closed groups earlier to target 32 MiB aggregate storage |
+| Cleanup scan | At most 4096 directory entries per maintenance pass |
+| Maintenance | Coordinator only, at startup and every 60 seconds |
+
+A graceful writer close renames its active file to `.jsonl.closed`; that suffix is the cleanup eligibility marker, not a live process probe. Cleanup removes only closed writer groups, oldest first. Active and crash-orphan groups are left untouched. The 32 MiB directory target is therefore **best effort, not a hard disk cap**, especially if active/orphan groups or scan limits dominate. Filesystem failures may leave files behind.
+
+Logging is non-authoritative and best effort. Discovery failures before root resolution and invalid HTTP envelopes rejected before runtime handling are not emitted as runtime log events. Sanitization/size/queue failures can discard observations. An append/rotation I/O failure disables that writer and drops queued records without retrying or failing Intercom communication. Maintenance failures are ignored by the communication path. Ordinary record/send/delivery operations never await logging I/O. During teardown, the runtime invalidates its lifecycle and closes its HTTP endpoint before waiting at most **250 ms** for logger shutdown. Concurrent close callers share the same close operation. This is not a guaranteed flush: timed-out I/O cannot be cancelled and may finish later.
+
+The writer refuses pre-existing symbolic links at `.pi-intercom` or its `logs` directory; these checks are best effort, not race-proof protection against a hostile filesystem. The dashboard cannot certify that logging was complete or that a quiet writer is healthy; inspect local storage when diagnosing missing evidence. Logs are not fsynced as a durable delivery journal.
+
+## HTTP snapshot boundary
+
+Only the coordinator exposes these GET routes:
+
+| Route | Response |
+|---|---|
+| `/` | Local `dashboard/index.html` |
+| `/app.js`, `/style.css` | Explicitly allowlisted local assets |
+| `/api/snapshot` | Sanitized JSON snapshot |
+
+Snapshot shape:
+
+```text
+{ version: 1, generatedAt, staleAfterMs: 60000,
+  config: { multiplexer, agents: [selected validated roster fields] } | null,
+  events: [sanitized v1 events, oldest first], truncated: boolean,
+  errors: [fixed safe labels] }
+```
+
+Reads are bounded: config at most 1 MiB and 256 agents; scan at most 512 log-directory entries, select up to 32 newest matching files among those scanned (not necessarily the globally newest files in an oversized directory), tail at most 128 KiB per file and 2 MiB total, and return at most 500 latest events. `truncated` indicates bounded omissions, not complete history. Unsupported, malformed or partial records are ignored. Reads can overlap rotation and are not a transactional global snapshot.
+
+Partial snapshots return HTTP 200 with `config_unavailable`, `logs_unavailable` and/or `log_read_failed` labels; no raw read errors or paths are returned. Unknown routes (including query variants) return 404; non-GET requests return 405; rejected Host/Origin/cross-site requests return 403; overload or static-asset failures return 503. The listener admits at most eight active requests and 16 connections. Concurrent snapshot requests share the pending read, not a worker probe.
+
+The backend rejects linked/redirected config, log and asset path components and serves no arbitrary file route. It sets no-store, nosniff, same-origin-only content policy, no-referrer and frame-ancestor restrictions. These checks reduce exposure but are **not authentication or a security boundary against hostile local processes**; localhost remains trusted. Do not proxy or expose the dashboard remotely.
+
+## Validation scope
+
+See README for verified test results. Synthetic filesystem/HTTP/DOM fixtures do not prove actual Pi queue acceptance, live resume, host name persistence, or full interactive lifecycle correctness. No dashboard observation should be used to infer unobserved completion or availability.

package/references/v1-specification.md

@@ -96,7 +96,7 @@ No worker-specific config path, callback address, instance ID, or preassigned re
 - Include sender identity and label agent messages with sender and purpose.
 - Incoming coordinator-only controls check sender session ID against current config. This is role validation, not authentication.
 - Receipt timeout is 5 seconds. No automatic retries. A failure or timeout is reported; the agent decides recovery.
-- Dedicated durable message logging is deferred until the basic system works.
+- Dedicated durable message logging is deferred. A subsequently approved, separate scope adds best-effort metadata telemetry and a coordinator-only read-only dashboard; see [observability](observability.md). This is not a durable inbox, task journal, replay mechanism, completion guarantee or orchestration layer.
 
 ### Agent delivery
 
@@ -158,7 +158,7 @@ Every invocation reads the current Pi session ID and shared config, determines r
 ## 8. Explicitly deferred
 
 - Other operating systems and multiplexers.
-- Durable message logging, including storage/retention policy.
+- Durable message/task journals and replay remain deferred. The newly approved [metadata-only observation feature](observability.md) has bounded best-effort storage/retention, not durable-delivery guarantees.
 - Duplicate Pi-session activation detection or session-ID locks.
 - Automatic retry queues and recovery orchestration are not V1 behavior.
 - Bulk tools: use individual operations instead.

package/src/config.ts

@@ -8,6 +8,8 @@ export interface Agent {
   coordinator: boolean;
   description: string;
   port: number;
+  /** Last bound dashboard port, coordinator only; not evidence of a live server. */
+  dashboardPort?: number;
   projectDirectory: string;
 }
 export interface Config { version: 1; multiplexer: 'herdr' | 'none'; agents: Agent[] }
@@ -33,6 +35,10 @@ export function validateConfig(value: unknown): Config {
     text(a.sessionId, 'sessionId', 256); text(a.name, 'name', 128); text(a.description, 'description');
     if (a.name !== a.name.trim() || /[\r\n\x00-\x1f]/.test(a.name)) fail('invalid name');
     port(a.port); relativeDirectory(a.projectDirectory);
+    if (a.dashboardPort !== undefined) {
+      if (!a.coordinator) fail('dashboardPort is coordinator-only');
+      port(a.dashboardPort);
+    }
     if (names.has(key(a.name)) || ids.has(a.sessionId)) fail('duplicate name or session ID');
     names.add(key(a.name)); ids.add(a.sessionId);
     if (a.coordinator ? (a.name !== 'Coordinator' || a.projectDirectory !== '.') : key(a.name) === 'coordinator') fail('reserved Coordinator identity');

package/src/dashboard.ts

@@ -0,0 +1,158 @@
+import { createServer } from 'node:http';
+import { constants } from 'node:fs';
+import { lstat, open, opendir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateConfig, type Config } from './config.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;
+const MAX_FILES = 32, MAX_ENTRIES = 512, MAX_EVENTS = 500, MAX_AGENTS = 256;
+export interface DashboardSnapshot {
+  version: 1;
+  generatedAt: string;
+  staleAfterMs: number;
+  config: Pick<Config, 'multiplexer' | 'agents'> | null;
+  events: Observation[];
+  truncated: boolean;
+  errors: string[];
+}
+
+// Only fixed, extension-owned paths are read. Reject symlink/junction components
+// rather than allowing a local log/config link to expose an unrelated file.
+async function confined(root: string, relative: string): Promise<string> {
+  const base = await realpath(root);
+  let current = base;
+  for (const segment of relative.split(/[\\/]/)) {
+    if (!segment || segment === '.' || segment === '..') throw new Error('invalid path');
+    current = path.join(current, segment);
+    if ((await lstat(current)).isSymbolicLink()) throw new Error('linked path');
+    if (path.relative(current, await realpath(current)) !== '') throw new Error('redirected path');
+  }
+  return current;
+}
+
+async function boundedRead(file: string, limit: number, tail = false): Promise<{ text: string; truncated: boolean; bytes: number }> {
+  if (!(await lstat(file)).isFile()) throw new Error('not a file');
+  const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error('not a file');
+    if (!tail && stat.size > limit) throw new Error('file too large');
+    const size = Math.min(stat.size, limit), start = tail ? Math.max(0, stat.size - size) : 0;
+    const buffer = Buffer.alloc(size);
+    const { bytesRead } = await handle.read(buffer, 0, size, start);
+    let text = buffer.subarray(0, bytesRead).toString('utf8');
+    // Drop potentially partial UTF-8/JSON at both tail boundaries. Writers append
+    // complete newline-terminated records; incomplete records are not evidence.
+    if (tail) {
+      if (start > 0) text = text.slice(text.indexOf('\n') + 1);
+      text = text.slice(0, text.lastIndexOf('\n') + 1);
+    }
+    return { text, truncated: stat.size > limit, bytes: bytesRead };
+  } finally { await handle.close(); }
+}
+
+export async function readDashboardSnapshot(root: string): Promise<DashboardSnapshot> {
+  const result: DashboardSnapshot = { version: 1, generatedAt: new Date().toISOString(), staleAfterMs: 60000, config: null, events: [], truncated: false, errors: [] };
+  try {
+    const file = await confined(root, '.pi-intercom/config.json');
+    const config = validateConfig(JSON.parse((await boundedRead(file, CONFIG_BYTES)).text));
+    result.truncated ||= config.agents.length > MAX_AGENTS;
+    result.config = { multiplexer: config.multiplexer, agents: config.agents.slice(0, MAX_AGENTS).map(a => ({
+      sessionId: a.sessionId, name: a.name, coordinator: a.coordinator, description: a.description,
+      projectDirectory: a.projectDirectory, port: a.port,
+      ...(a.dashboardPort === undefined ? {} : { dashboardPort: a.dashboardPort }),
+    })) };
+  } catch { result.errors.push('config_unavailable'); }
+  try {
+    const directory = await confined(root, LOG_DIRECTORY);
+    const files: { name: string; modified: number }[] = [];
+    const entries = await opendir(directory);
+    let scanned = 0;
+    for await (const entry of entries) {
+      if (++scanned > MAX_ENTRIES) { result.truncated = true; break; }
+      if (!entry.isFile() || !LOG_FILE_PATTERN.test(entry.name)) continue;
+      try {
+        const file = await confined(root, `${LOG_DIRECTORY}/${entry.name}`);
+        files.push({ name: entry.name, modified: (await lstat(file)).mtimeMs });
+      } catch { /* Rotations can remove a file while scanning. */ }
+    }
+    files.sort((a, b) => b.modified - a.modified || a.name.localeCompare(b.name));
+    result.truncated ||= files.length > MAX_FILES;
+    let budget = TOTAL_BYTES;
+    for (const file of files.slice(0, MAX_FILES)) {
+      if (budget <= 0) { result.truncated = true; break; }
+      try {
+        const resolved = await confined(root, `${LOG_DIRECTORY}/${file.name}`);
+        const read = await boundedRead(resolved, Math.min(TAIL_BYTES, budget), true);
+        budget -= read.bytes;
+        result.truncated ||= read.truncated;
+        for (const line of read.text.split('\n')) {
+          if (!line) continue;
+          try {
+            const event = sanitizeObservation(JSON.parse(line));
+            if (event) result.events.push(event);
+          } catch { /* Ignore malformed/partial/foreign records, never expose raw data. */ }
+        }
+      } catch { if (!result.errors.includes('log_read_failed')) result.errors.push('log_read_failed'); }
+    }
+    result.events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    if (result.events.length > MAX_EVENTS) { result.events = result.events.slice(-MAX_EVENTS); result.truncated = true; }
+  } catch { result.errors.push('logs_unavailable'); }
+  return result;
+}
+
+export interface Dashboard { url: string; port: number; close(): Promise<void> }
+export async function startDashboard(root: string, options: { assetDirectory?: string } = {}): Promise<Dashboard> {
+  const assets = options.assetDirectory ?? fileURLToPath(new URL('../dashboard/', import.meta.url));
+  const routes: Record<string, [string, string]> = {
+    '/': ['index.html', 'text/html; charset=utf-8'],
+    '/app.js': ['app.js', 'text/javascript; charset=utf-8'],
+    '/style.css': ['style.css', 'text/css; charset=utf-8'],
+  };
+  let port = 0, active = 0, closing = false;
+  let pending: Promise<DashboardSnapshot> | undefined;
+  const server = createServer(async (request, response) => {
+    response.setHeader('Cache-Control', 'no-store');
+    response.setHeader('X-Content-Type-Options', 'nosniff');
+    response.setHeader('Content-Security-Policy', "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; base-uri 'none'; frame-ancestors 'none'");
+    response.setHeader('Referrer-Policy', 'no-referrer');
+    const end = (code: number, body: string, type = 'text/plain; charset=utf-8') => {
+      response.writeHead(code, { 'Content-Type': type }); response.end(body);
+    };
+    const hosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+    if (!hosts.includes(request.headers.host ?? '') ||
+      (request.headers.origin !== undefined && !hosts.some(host => request.headers.origin === `http://${host}`)) ||
+      request.headers['sec-fetch-site'] === 'cross-site') return end(403, 'Forbidden');
+    if (request.method !== 'GET') { response.setHeader('Allow', 'GET'); return end(405, 'GET only'); }
+    if (closing || active >= 8) return end(503, 'Unavailable');
+    active++;
+    try {
+      if (request.url === '/api/snapshot') {
+        pending ??= readDashboardSnapshot(root).finally(() => { pending = undefined; });
+        return end(200, JSON.stringify(await pending), 'application/json; charset=utf-8');
+      }
+      const route = Object.hasOwn(routes, request.url ?? '') ? routes[request.url!] : undefined;
+      if (!route) return end(404, 'Not found');
+      const file = await confined(assets, route[0]);
+      return end(200, (await boundedRead(file, 256 * 1024)).text, route[1]);
+    } catch { return end(503, 'Unavailable'); }
+    finally { active--; }
+  });
+  server.requestTimeout = 5000; server.headersTimeout = 5000; server.keepAliveTimeout = 1000;
+  server.maxConnections = 16;
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => { server.off('error', reject); resolve(); });
+  });
+  port = (server.address() as { port: number }).port;
+  let closed: Promise<void> | undefined;
+  return { port, url: `http://127.0.0.1:${port}/`, close() {
+    closing = true;
+    return closed ??= new Promise<void>((resolve, reject) => {
+      server.close(error => error ? reject(error) : resolve());
+      server.closeAllConnections();
+    });
+  } };
+}

package/src/index.ts

@@ -5,6 +5,7 @@ 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';
 
 const to = Type.Object({ to: Type.String({ minLength: 1, maxLength: 128 }) });
 const tools: [string, string, TSchema][] = [
@@ -42,11 +43,15 @@ 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;
   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;
     if (process.platform !== 'win32' || ctx.mode !== 'tui') throw new Error('PiIntercom V1 requires Windows interactive Pi. No resources started.');
     if (!ctx.isProjectTrusted()) throw new Error('PiIntercom requires project trust before honoring shared project configuration.');
@@ -58,10 +63,43 @@ export default function intercomExtension(pi: ExtensionAPI): void {
       setName: async name => { if (pi.getSessionName() !== name) pi.setSessionName(name); await launcher.syncName(name); },
       notify: text => ctx.ui.notify(text, 'info'),
     }, { launch: launcher.launch, store: root => new PiConfigStore(root) });
-    try { await runtime.start(); }
-    catch (e) { runtime = undefined; ctx.ui.notify(String(e), 'error'); }
+    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;
+    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');
+      }
+    } catch {
+      await server?.close().catch(() => {});
+      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');
+    }
+  });
+  pi.on('session_shutdown', async () => {
+    generation++;
+    await dashboard?.close(); dashboard = undefined;
+    await runtime?.close(); runtime = undefined; context = undefined;
+  });
+  pi.on('agent_start', async (_event, ctx) => {
+    context = ctx;
+    runtime?.recordObservation('host.activity', { busy: !ctx.isIdle(), outcome: 'started' });
+  });
+  pi.on('agent_settled', async (_event, ctx) => {
+    context = ctx;
+    runtime?.recordObservation('host.activity', { busy: !ctx.isIdle(), outcome: 'settled' });
   });
-  pi.on('session_shutdown', async () => { await runtime?.close(); runtime = undefined; context = undefined; });
   pi.on('before_agent_start', async (event, ctx) => {
     context = ctx;
     if (!runtime) return;

package/src/observability.ts

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { appendFile, lstat, mkdir, opendir, rename, stat, unlink } from 'node:fs/promises';
+
+export const LOG_DIRECTORY = '.pi-intercom/logs';
+export const LOG_FILE_PATTERN = /^writer-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl(?:\.[12]|\.closed)?$/;
+export const LOG_LIMITS = { fileBytes: 1024 * 1024, filesPerInstance: 3, queueEntries: 256, entryBytes: 4096, retentionMs: 7 * 24 * 60 * 60 * 1000, directoryBytes: 32 * 1024 * 1024, scanEntries: 4096, closeTimeoutMs: 250 } as const;
+export const EVENT_TYPES = ['runtime.starting', 'runtime.ready', 'runtime.closed', 'runtime.failed', 'config.changed', 'config.reloaded', 'transport.send', 'transport.receipt', 'transport.failed', 'transport.received', 'transport.rejected', 'registration.received', 'status.received', 'launch.result', 'host.submission', 'host.activity', 'host.ui_prompt'] as const;
+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 OPERATIONS = ['configure_worker', 'set_multiplexer', 'remove_worker', 'create_worker', 'resume_worker', 'port_update', 'initialize'] as const;
+export interface EventMetadata {
+  peerSessionId?: string;
+  peerName?: string;
+  correlationId?: string;
+  kind?: typeof KINDS[number];
+  busy?: boolean;
+  port?: number;
+  role?: 'coordinator' | 'worker' | 'anonymous';
+  outcome?: typeof OUTCOMES[number];
+  errorCode?: typeof ERROR_CODES[number];
+  operation?: typeof OPERATIONS[number];
+}
+export interface Observation extends EventMetadata {
+  version: 1;
+  timestamp: string;
+  /** Log-file writer identity only: never a transport or agent identity. */
+  writerId: string;
+  sessionId: string;
+  event: EventType;
+}
+export interface Observer { record(event: EventType, metadata?: EventMetadata): void; close(): Promise<void>; maintain?(): void }
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function safeText(value: unknown, max: number): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= max && !/[\x00-\x1f\x7f]/.test(value);
+}
+function includes<T extends string>(list: readonly T[], value: unknown): value is T { return typeof value === 'string' && list.includes(value as T); }
+/** Project only explicitly allowed metadata, including when reading untrusted on-disk logs. */
+export function sanitizeObservation(value: unknown): Observation | undefined {
+  if (!value || typeof value !== 'object') return;
+  const v = value as Record<string, unknown>;
+  if (v.version !== 1 || !includes(EVENT_TYPES, v.event) || !safeText(v.sessionId, 256) || typeof v.writerId !== 'string' || !uuid.test(v.writerId)) return;
+  if (typeof v.timestamp !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(v.timestamp) || !Number.isFinite(Date.parse(v.timestamp))) return;
+  const result: Observation = { version: 1, timestamp: v.timestamp, writerId: v.writerId, sessionId: v.sessionId, event: v.event };
+  if (safeText(v.peerSessionId, 256)) result.peerSessionId = v.peerSessionId;
+  if (safeText(v.peerName, 128)) result.peerName = v.peerName;
+  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 (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;
+  if (includes(ERROR_CODES, v.errorCode)) result.errorCode = v.errorCode;
+  if (includes(OPERATIONS, v.operation)) result.operation = v.operation;
+  return result;
+}
+/** Never inspect error.message/stack, response bodies, paths, or arbitrary error codes. */
+export function observationError(error: unknown): EventMetadata['errorCode'] {
+  try {
+    const code = error && typeof error === 'object' ? (error as { code?: unknown }).code : undefined;
+    return includes(ERROR_CODES, code) ? code : 'operation_failed';
+  } catch { return 'operation_failed'; }
+}
+export class LocalObserver implements Observer {
+  readonly writerId = randomUUID();
+  readonly directory: string;
+  readonly file: string;
+  private queue: string[] = [];
+  private pending?: Promise<void>;
+  private initialized = false;
+  private bytes = 0;
+  private closed = false;
+  private disabled = false;
+  private maintenance = false;
+  private timer?: ReturnType<typeof setInterval>;
+  dropped = 0;
+  constructor(root: string, readonly sessionId: string, private readonly limits: { fileBytes?: number; queueEntries?: number } = {}) {
+    this.directory = path.join(root, LOG_DIRECTORY);
+    this.file = path.join(this.directory, `writer-${this.writerId}.jsonl`);
+  }
+  record(event: EventType, metadata: EventMetadata = {}): void {
+    try {
+      if (this.closed || this.disabled) return;
+      const observation = sanitizeObservation({ ...metadata, version: 1, timestamp: new Date().toISOString(), writerId: this.writerId, sessionId: this.sessionId, event });
+      if (!observation) return;
+      const line = JSON.stringify(observation) + '\n';
+      const capacity = Math.max(1, Math.min(LOG_LIMITS.queueEntries, this.limits.queueEntries ?? LOG_LIMITS.queueEntries));
+      if (Buffer.byteLength(line) > LOG_LIMITS.entryBytes || this.queue.length >= capacity) { this.dropped++; return; }
+      this.queue.push(line);
+      this.schedule();
+    } catch { /* Observability must never throw into communication. */ }
+  }
+  private schedule(): void {
+    if (this.pending || this.disabled) return;
+    this.pending = Promise.resolve().then(() => this.drain()).catch(() => {
+      // Disable this writer after an I/O failure; no retry queue and no communication failure.
+      this.disabled = true; this.dropped += this.queue.length; this.queue = [];
+    }).finally(() => {
+      this.pending = undefined;
+      if (this.queue.length && !this.disabled) this.schedule();
+    });
+  }
+  /** Runtime calls only on the coordinator. No process probes or activity inference. */
+  maintain(): void {
+    if (this.closed || this.disabled || this.timer) return;
+    const request = () => { this.maintenance = true; this.schedule(); };
+    this.timer = setInterval(request, 60_000); this.timer.unref(); request();
+  }
+  protected append(file: string, line: string): Promise<void> { return appendFile(file, line, { encoding: 'utf8', mode: 0o600 }); }
+  private async prune(): Promise<void> {
+    const files: { file: string; base: string; mtime: number; bytes: number }[] = [];
+    const closed = new Set<string>();
+    let scanned = 0;
+    for await (const entry of await opendir(this.directory)) {
+      if (++scanned > LOG_LIMITS.scanEntries) break;
+      if (!entry.isFile() || !LOG_FILE_PATTERN.test(entry.name)) continue;
+      const file = path.join(this.directory, entry.name);
+      const base = file.replace(/\.(?:closed|[12])$/, '');
+      if (file.endsWith('.closed')) closed.add(base);
+      const info = await stat(file).catch(() => undefined);
+      if (info) files.push({ file, base, mtime: info.mtimeMs, bytes: info.size });
+    }
+    let total = files.reduce((sum, file) => sum + file.bytes, 0);
+    const groups = [...closed].map(base => {
+      const members = files.filter(file => file.base === base);
+      return { members, newest: Math.max(...members.map(file => file.mtime)) };
+    }).sort((a, b) => a.newest - b.newest);
+    for (const group of groups) {
+      // Only gracefully closed writer groups are eligible. Active/crashed writers stay untouched.
+      if (Date.now() - group.newest > LOG_LIMITS.retentionMs || total > LOG_LIMITS.directoryBytes) {
+        // Remove the closed marker last, retaining eligibility if an earlier unlink fails.
+        for (const file of group.members.sort((a, b) => Number(a.file.endsWith('.closed')) - Number(b.file.endsWith('.closed')))) {
+          try { await unlink(file.file); total -= file.bytes; } catch { break; }
+        }
+      }
+    }
+  }
+  private async drain(): Promise<void> {
+    if (!this.initialized) {
+      const parent = path.dirname(this.directory);
+      await mkdir(parent, { recursive: true, mode: 0o700 });
+      if ((await lstat(parent)).isSymbolicLink()) throw new Error('log parent must not be a symlink');
+      await mkdir(this.directory, { recursive: true, mode: 0o700 });
+      if ((await lstat(this.directory)).isSymbolicLink()) throw new Error('log directory must not be a symlink');
+      this.initialized = true;
+    }
+    if (this.maintenance) { this.maintenance = false; await this.prune().catch(() => {}); }
+    const maxBytes = Math.max(LOG_LIMITS.entryBytes, Math.min(LOG_LIMITS.fileBytes, this.limits.fileBytes ?? LOG_LIMITS.fileBytes));
+    while (this.queue.length) {
+      const line = this.queue.shift()!, size = Buffer.byteLength(line);
+      if (this.bytes + size > maxBytes) {
+        await unlink(`${this.file}.2`).catch(e => { if (e.code !== 'ENOENT') throw e; });
+        await rename(`${this.file}.1`, `${this.file}.2`).catch(e => { if (e.code !== 'ENOENT') throw e; });
+        await rename(this.file, `${this.file}.1`).catch(e => { if (e.code !== 'ENOENT') throw e; });
+        this.bytes = 0;
+      }
+      await this.append(this.file, line); this.bytes += size;
+    }
+  }
+  async close(): Promise<void> {
+    if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
+    this.closed = true;
+    while (this.pending) await this.pending;
+    // An atomic suffix change is the sole inactive-writer signal. Crashes leave no such signal.
+    if (this.initialized && !this.disabled) await rename(this.file, `${this.file}.closed`).catch(() => {});
+  }
+}

package/src/runtime.ts

@@ -1,5 +1,7 @@
 import path from 'node:path';
-import { ConfigStore, coordinator, directory, fail, named, requireCoordinator, type Agent, type Config } from './config.js';
+import { randomUUID } from 'node:crypto';
+import { LocalObserver, LOG_LIMITS, observationError, type Observer, type EventType, type EventMetadata } from './observability.js';
+import { ConfigStore, coordinator, directory, fail, named, port, requireCoordinator, type Agent, type Config } from './config.js';
 import { listen, send, type Endpoint, type Envelope, type Kind } from './transport.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).';
@@ -17,6 +19,7 @@ export interface RuntimeOptions {
   listen?: typeof listen;
   send?: typeof send;
   store?: (root: string) => ConfigStore;
+  observe?: (root: string, sessionId: string) => Observer;
 }
 export class Intercom {
   store!: ConfigStore;
@@ -25,6 +28,15 @@ export class Intercom {
   private generation = 0;
   private initialId = '';
   responsibility?: Agent;
+  private observer?: Observer;
+  private closing?: Promise<void>;
+  private captureObserver(): (event: EventType, metadata?: EventMetadata) => void {
+    const observer = this.observer;
+    return (event, metadata = {}) => {
+      try { observer?.record(event, metadata); } catch { /* Logging cannot affect communication. */ }
+    };
+  }
+  recordObservation(event: EventType, metadata: EventMetadata = {}): void { this.captureObserver()(event, metadata); }
   constructor(readonly host: Host, readonly options: RuntimeOptions) {}
   private id(): string {
     const id = this.host.sessionId();
@@ -40,26 +52,36 @@ export class Intercom {
     };
   }
   async start(): Promise<void> {
+    if (this.closing) await this.closing;
     if (this.active) fail('runtime already active');
     this.initialId = this.host.sessionId(); this.active = true;
     const generation = ++this.generation, assertValid = this.validity();
+    let record = this.captureObserver();
     try {
       const discovered = await ConfigStore.discover(this.host.cwd);
       assertValid();
       this.store = this.options.store?.(discovered?.root ?? this.host.cwd) ?? discovered ?? new ConfigStore(this.host.cwd);
+      try { this.observer = this.options.observe ? this.options.observe(this.store.root, this.initialId) : new LocalObserver(this.store.root, this.initialId); } catch { /* Logging is optional on failure. */ }
+      record = this.captureObserver();
+      record('runtime.starting');
       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); });
       try { assertValid(); } catch (error) { await endpoint.close(); throw error; }
       this.endpoint = endpoint;
-      if (!previous) await this.store.initialize(this.id(), this.endpoint.port, assertValid);
+      if (!previous) {
+        const initialized = await this.store.initialize(this.id(), this.endpoint.port, assertValid);
+        if (initialized) record('config.changed', { operation: 'initialize', outcome: 'written' });
+      }
       const config = await this.store.read();
       assertValid();
       const me = config.agents.find(a => a.sessionId === this.id());
       if (me?.coordinator) {
+        try { this.observer?.maintain?.(); } catch { /* No cleanup failure affects readiness. */ }
         await this.store.update(this.id(), c => { requireCoordinator(c, this.id()).port = this.endpoint!.port; }, assertValid);
         assertValid();
+        record('config.changed', { operation: 'port_update', outcome: 'written', port: this.endpoint.port });
         try { await this.reload(); } catch (e) { assertValid(); this.host.notify(`Name/responsibility synchronization failed: ${String(e)}`); }
         assertValid();
         this.host.notify(`Intercom Coordinator ready at 127.0.0.1:${this.endpoint.port}; waiting for user input.`);
@@ -77,13 +99,39 @@ export class Intercom {
         assertValid();
         this.host.notify(`Intercom worker ready at 127.0.0.1:${this.endpoint.port}; waiting for explicit work.`);
       }
-    } catch (e) { if (generation === this.generation) await this.close(); throw e; }
+      record('runtime.ready', { port: this.endpoint.port, role: me?.coordinator ? 'coordinator' : me ? 'worker' : 'anonymous', busy: this.host.busy(), outcome: 'ready' });
+    } catch (e) {
+      if (generation === this.generation) {
+        record('runtime.failed', { errorCode: observationError(e), outcome: 'failed' });
+        await this.close();
+      }
+      throw e;
+    }
   }
   async close(): Promise<void> {
+    if (this.closing) return this.closing;
+    this.recordObservation('runtime.closed');
+    const observer = this.observer; this.observer = undefined;
     this.active = false; this.generation++;
     const endpoint = this.endpoint; this.endpoint = undefined;
     this.responsibility = undefined;
-    if (endpoint) await endpoint.close();
+    const closing = (async () => {
+      try { if (endpoint) await endpoint.close(); }
+      finally {
+        if (observer) {
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          try {
+            // Only shutdown waits, and only for this bounded deadline. Already-issued I/O cannot be cancelled.
+            await Promise.race([
+              Promise.resolve().then(() => observer.close()).catch(() => {}),
+              new Promise<void>(resolve => { timer = setTimeout(resolve, LOG_LIMITS.closeTimeoutMs); }),
+            ]);
+          } finally { if (timer) clearTimeout(timer); }
+        }
+      }
+    })();
+    this.closing = closing;
+    try { await closing; } finally { if (this.closing === closing) this.closing = undefined; }
   }
   async state(): Promise<{ id: string; config: Config; me?: Agent }> {
     const assertValid = this.validity();
@@ -91,7 +139,16 @@ export class Intercom {
     assertValid();
     return { id, config, me: config.agents.find(a => a.sessionId === id) };
   }
+  /** Persist an actual dashboard bind; saved discovery metadata, not a live-status assertion. */
+  async recordDashboardPort(boundPort: number): Promise<void> {
+    const record = this.captureObserver(), assertValid = this.validity();
+    const { id, config } = await this.state();
+    assertValid(); requireCoordinator(config, id); port(boundPort);
+    await this.store.update(id, c => { requireCoordinator(c, id).dashboardPort = boundPort; }, assertValid);
+    record('config.changed', { outcome: 'written' });
+  }
   async reload(): Promise<void> {
+    const record = this.captureObserver();
     const assertValid = this.validity();
     const { me } = await this.state();
     assertValid();
@@ -99,14 +156,24 @@ export class Intercom {
     this.responsibility = { ...me };
     await this.host.setName(me.name);
     assertValid();
+    record('config.reloaded', { role: me.coordinator ? 'coordinator' : 'worker' });
     this.host.notify(`Intercom responsibility loaded for ${me.name}; no work turn started.`);
   }
   async transmit(to: string, kind: Kind, payload: Record<string, unknown> = {}): Promise<void> {
+    const record = this.captureObserver();
     const assertValid = this.validity();
     const { id, config } = await this.state();
     assertValid();
-    const target = named(config, to);
-    await (this.options.send ?? send)(target.port, { version: 1, from: id, to: target.sessionId, kind, payload });
+    const target = named(config, to), correlationId = randomUUID();
+    const metadata = { peerSessionId: target.sessionId, peerName: target.name, correlationId, kind };
+    record('transport.send', { ...metadata, outcome: 'attempted' });
+    try {
+      await (this.options.send ?? send)(target.port, { version: 1, from: id, to: target.sessionId, kind, payload, correlationId });
+      record('transport.receipt', { ...metadata, outcome: 'http_receipt' });
+    } catch (error) {
+      record('transport.failed', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+      throw error;
+    }
   }
   async report(): Promise<void> {
     const assertValid = this.validity();
@@ -117,15 +184,35 @@ export class Intercom {
     await this.transmit(coordinator(config).name, 'status', { port: this.endpoint.port, busy: this.host.busy() });
   }
   async receive(message: Envelope): Promise<void> {
+    const record = this.captureObserver();
+    const metadata = { peerSessionId: message.from, correlationId: message.correlationId, kind: message.kind };
+    record('transport.received', metadata);
+    try { await this.handleReceive(message); }
+    catch (error) {
+      record('transport.rejected', { ...metadata, outcome: 'handler_failed', errorCode: observationError(error) });
+      throw error;
+    }
+  }
+  private async handleReceive(message: Envelope): Promise<void> {
+    const record = this.captureObserver();
     const assertValid = this.validity();
     const { id, config, me } = await this.state();
     assertValid();
     if (message.to !== id) fail('recipient session ID mismatch (stale endpoint)');
     const sender = config.agents.find(a => a.sessionId === message.from);
     const busy = this.host.busy();
+    const metadata = { peerSessionId: message.from, peerName: sender?.name, correlationId: message.correlationId, kind: message.kind, busy };
     const notify = (purpose: string, content: string) => {
       assertValid();
-      this.host.deliver(`[Intercom ${purpose} from ${sender?.name ?? 'unconfigured worker'} (${message.from})]\n${content}`, busy);
+      record('host.submission', { ...metadata, outcome: 'attempted' });
+      try {
+        this.host.deliver(`[Intercom ${purpose} from ${sender?.name ?? 'unconfigured worker'} (${message.from})]\n${content}`, busy);
+        // A synchronous return is not Pi queue acceptance or model completion.
+        record('host.submission', { ...metadata, outcome: 'returned' });
+      } catch (error) {
+        record('host.submission', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+        throw error;
+      }
     };
     if (message.kind === 'registration' || message.kind === 'status') {
       requireCoordinator(config, id);
@@ -133,12 +220,15 @@ export class Intercom {
       if (message.kind === 'registration') {
         const projectDirectory = await directory(this.store.root, message.payload.projectDirectory as string);
         // No pending map, placeholder or configuration mutation.
+        record('registration.received', { ...metadata, port: message.payload.port as number });
         notify('registration', JSON.stringify({ sessionId: message.from, port: message.payload.port, projectDirectory }) + '\nThis is connection information, not a work assignment. Configure explicitly, then reload separately.');
       } else {
         if (sender) await this.store.update(id, c => {
           const entry = c.agents.find(a => a.sessionId === message.from && !a.coordinator);
           if (entry) entry.port = message.payload.port as number;
         }, assertValid);
+        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 }));
       }
       return;
@@ -166,12 +256,14 @@ export class Intercom {
     fail('unsupported control');
   }
   async tool(operation: string, args: Record<string, unknown>): Promise<unknown> {
+    const record = this.captureObserver();
     const assertValid = this.validity();
     const { id, config, me } = await this.state();
     assertValid();
     if (operation === 'list') {
       if (!me) fail('anonymous intercom_list permissions unresolved (TODO); no coordinator privileges');
-      return config;
+      const dashboardPort = coordinator(config).dashboardPort;
+      return { ...config, dashboardUrl: dashboardPort === undefined ? null : `http://127.0.0.1:${dashboardPort}/` };
     }
     if (operation === 'report_status') { await this.report(); return { accepted: true }; }
     if (operation === 'send') {
@@ -182,15 +274,17 @@ export class Intercom {
     if (operation === 'stop_worker' || operation === 'close_worker') fail(UNSUPPORTED_CANCELLATION);
     if (operation === 'configure_worker') {
       await this.store.configure(id, args as unknown as Omit<Agent, 'coordinator'>, assertValid);
+      record('config.changed', { operation: 'configure_worker', peerSessionId: args.sessionId as string, peerName: args.name as string, outcome: 'written' });
       return { written: true, reloaded: false };
     }
     if (operation === 'set_multiplexer') {
-      await this.store.update(id, c => { c.multiplexer = args.multiplexer as Config['multiplexer']; }, assertValid); return { written: true };
+      await this.store.update(id, c => { c.multiplexer = args.multiplexer as Config['multiplexer']; }, assertValid);
+      record('config.changed', { operation: 'set_multiplexer', outcome: 'written' }); return { written: true };
     }
     if (operation === 'create_worker') {
       const relative = await directory(this.store.root, (args.projectDirectory as string | undefined) ?? '.');
       assertValid();
-      return this.options.launch({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative) });
+      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative) });
     }
     const target = named(config, args.to as string);
     if (target.coordinator) fail('operation requires a worker target');
@@ -201,13 +295,27 @@ export class Intercom {
     if (operation === 'resume_worker') {
       const relative = await directory(this.store.root, target.projectDirectory);
       assertValid();
-      return this.options.launch({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), sessionId: target.sessionId });
+      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), sessionId: target.sessionId });
     }
     if (operation === 'remove_worker') {
       // No live process claim: the caller must explicitly ensure closure first.
       await this.store.update(id, c => { c.agents = c.agents.filter(a => a.sessionId !== target.sessionId); }, assertValid);
+      record('config.changed', { operation: 'remove_worker', peerSessionId: target.sessionId, peerName: target.name, outcome: 'removed' });
       return { removed: true, processStopped: false, sessionDeleted: false };
     }
     fail(`unknown operation ${operation}`);
   }
+  private async launchObserved(request: LaunchRequest): Promise<unknown> {
+    const record = this.captureObserver();
+    const metadata: EventMetadata = { operation: request.sessionId ? 'resume_worker' : 'create_worker', peerSessionId: request.sessionId };
+    record('launch.result', { ...metadata, outcome: 'attempted' });
+    try {
+      const result = await this.options.launch(request);
+      record('launch.result', { ...metadata, outcome: 'returned' });
+      return result;
+    } catch (error) {
+      record('launch.result', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+      throw error;
+    }
+  }
 }

package/src/transport.ts

@@ -10,11 +10,14 @@ export interface Envelope {
   from: string;
   to: string;
   payload: Record<string, unknown>;
+  /** Optional diagnostics correlation only; never authentication or agent identity. */
+  correlationId?: string;
 }
 export function envelope(value: unknown): Envelope {
   const m = value as Envelope;
   if (!m || m.version !== 1 || !['message', 'registration', 'status', 'request_status', 'reload', 'stop', 'close'].includes(m.kind)) fail('invalid wire schema/version/kind');
   text(m.from, 'sender sessionId', 256); text(m.to, 'recipient sessionId', 256);
+  if (m.correlationId !== undefined && (typeof m.correlationId !== 'string' || !/^[a-zA-Z0-9-]{1,128}$/.test(m.correlationId))) fail('invalid correlation ID');
   if (!m.payload || Array.isArray(m.payload) || typeof m.payload !== 'object') fail('invalid payload');
   if (m.kind === 'message') text(m.payload.message, 'message', 48000);
   if (m.kind === 'registration' || m.kind === 'status') port(m.payload.port);