@comput/pi-intercom 0.1.3 → 0.2.1

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).
@@ -99,9 +101,21 @@ HTTP binds **127.0.0.1 only**, `POST /intercom`, UTF-8 JSON, at most 64 KiB. Env
 
 Kinds: `message`, `registration` (`port`, `projectDirectory`), `status` (`port`, `busy`), `request_status`, `reload`, `stop`, `close` (empty control payload). Sender session identity is the envelope `from`; registration/status agent notifications include an explicit `sessionId` field. Agent messages require configured sender and recipient; controls require the current coordinator's sender ID and a worker recipient. Registration/unknown status are intentional exceptions to configured-sender checks, accepted only by coordinator. All receivers verify expected recipient ID, protecting against stale ports reaching another session. Local processes are trusted: this is role validation, **not authentication**. No remote networking/proxies/redirects or credentials.
 
-`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.
+`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. Starting in 0.2.1, Intercom always supplies `deliverAs: 'steer'`: Pi starts normally when idle and steers when busy. This avoids the idle-snapshot-to-busy race that caused “Agent is already processing” errors; it does not fix manual-compaction rejection. 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.
+
+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.
 
-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).
+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,19 @@ 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.1 delivery regression validation
+
+Always specifying steering fixes the missing-streaming-mode race without adding retries or an Intercom queue. Coordinator and Quality independently passed typecheck and all **64 tests**, including a source-backed Pi 0.84.4 regression. Test fixtures now isolate discovery from real ancestor configurations; production discovery boundaries are unchanged and remain a separate design issue.
+
+### 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.1",
   "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');