@comput/pi-intercom 0.1.2 → 0.2.0

package/README.md

@@ -19,11 +19,21 @@ Alternatively install from npm:
 pi install npm:@comput/pi-intercom
 ```
 
-Then start a new Pi session or run `/reload`. Nothing here changes global/project Pi settings automatically. Do not load both the source and built output as separate extensions.
+Then start a new Pi session or run Pi `/reload`. `pi install` records the package in user settings by default; add `-l` for project settings. The Intercom extension itself does not change Pi settings. Load only one copy: do not enable the installed package alongside an explicit source checkout, or load both source and built output.
+
+### Updating the loaded copy
+
+- **npm installation:** update the installed package, not this checkout: `pi update npm:@comput/pi-intercom`. A pinned version must be explicitly changed (for example, `pi install npm:@comput/pi-intercom@0.1.2`, using the same settings scope as the original installation). `pi list` shows configured package sources; inspect that installation's `package.json` to confirm its version.
+- **Source loading (`pi -e .../src/index.ts`):** update that checkout. `npm run build` produces test output; it does not update a separate npm installation.
+- After obtaining the intended code, start a new session or use Pi `/reload` in each affected running host. **`intercom_reload_worker` only reads shared configuration; it cannot load extension-code fixes.** Workers launched by a coordinator receive the coordinator extension's actual file path. Updating a different copy does not change that path, and existing workers do not automatically reload.
+
+The 0.1.2 update/reload and subsequent worker creation were observed live; comprehensive reload/session-replacement lifecycle coverage remains pending.
+
+### Startup and launchers
 
 Without shared config, the current working directory becomes the coordinator root. Startup creates `.pi-intercom/config.json`, opens a loopback listener, synchronizes the name `Coordinator`, and waits for user input (no model turn). Existing config is found by walking upward. Invalid/unreadable config is an error and is not overwritten. Unknown session IDs, including forks, are workers, never replacement coordinators.
 
-Default launcher `herdr` requires the coordinator to be inside Herdr (`HERDR_ENV=1` and workspace context), with `herdr` on PATH. Each worker gets **one tab, one pane, no split, no focus change**. The `none` launcher requires `pi.cmd` and Windows PowerShell on PATH and opens a separate visible PowerShell terminal. Missing launcher is an error, not fallback. These launchers have mocked tests but have **not been exercised with live workers**.
+Default launcher `herdr` requires the coordinator to be inside Herdr (`HERDR_ENV=1` and workspace context), with `herdr` on PATH and `powershell.exe` plus `pi.ps1` available in the worker pane. Each worker gets **one tab, one pane, no split, no focus change**. The `none` launcher requires `pi.cmd` and Windows PowerShell on PATH and opens a separate visible PowerShell terminal. Missing launcher is an error, not fallback. Launch acknowledgment means command submission/terminal creation, not Pi readiness. A failed launch can leave a tab or process behind; no automatic cleanup occurs. See the scoped live evidence below.
 
 ## Explicit workflow
 
@@ -34,25 +44,25 @@ Default launcher `herdr` requires the coordinator to be inside Herdr (`HERDR_ENV
 5. Coordinator sends explicit work using `intercom_send({to:"Builder",message:"..."})`. Workers can communicate directly with configured peers. Findings do not authorize unrelated implementation. Progress questions ask for reporting and continuation, not cancellation.
 6. Workers report as instructed and wait, without autonomous exit. Coordinator unavailability does not close the worker or cancel its assignment.
 
-Existing workers restore responsibility by session ID, bind their saved port or an OS-selected fallback, and report their actual port. Coordinator updates existing ports as bookkeeping. Status from removed/unknown sessions notifies Pi but creates no entry. Resume uses the configured project directory and full session ID, with a saved-session lookup first; a never-used Pi session might not yet exist on disk. Failure leaves config unchanged, without fabricated history or forced model turns.
+Existing workers restore responsibility by session ID, bind their saved port or, if it is already in use, an OS-selected fallback, and report their actual port. Coordinator updates existing ports as bookkeeping. Status from removed/unknown sessions notifies Pi but creates no entry. Resume uses the configured project directory and full session ID, with a saved-session lookup first; a never-used Pi session might not yet exist on disk. Failure leaves config unchanged, without fabricated history or forced model turns.
 
 ## Tools and permissions
 
 Every tool rereads current config and checks the live Pi session ID. Names are case-insensitive for lookup/uniqueness; display capitalization is preserved. `Coordinator` is reserved.
 
-| Tool | Permission / effect |
-|---|---|
-| `intercom_create_worker` | Coordinator; launch anonymous worker, optional directory defaults to root |
-| `intercom_configure_worker` | Coordinator; explicit five fields above, writes only |
-| `intercom_reload_worker` | Coordinator; named worker's passive config/name reload |
-| `intercom_send` | Configured, responsibility-loaded sessions; named asynchronous message |
-| `intercom_list` | Configured sessions; saved state only, never live health |
-| `intercom_request_status` | Coordinator; ask named worker extension for an independent report |
-| `intercom_report_status` | Workers including anonymous; shared report function, never registration |
-| `intercom_stop_worker`, `intercom_close_worker` | Coordinator role checked, then **unsupported-host error**, no side effects |
-| `intercom_resume_worker` | Coordinator; named saved session, configured launcher/directory |
-| `intercom_remove_worker` | Coordinator; config entry only, no shutdown/session deletion |
-| `intercom_set_multiplexer` | Coordinator; `herdr` or `none`, future launches only |
+| Tool | Arguments | Permission / effect |
+|---|---|---|
+| `intercom_create_worker` | `projectDirectory?` (default `.`) | Coordinator; launch anonymous worker |
+| `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 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 |
+| `intercom_resume_worker` | `to` (worker name) | Coordinator; saved session, configured launcher/directory |
+| `intercom_remove_worker` | `to` (worker name) | Coordinator; config entry only, no shutdown/session deletion |
+| `intercom_set_multiplexer` | `multiplexer`: `herdr` or `none` | Coordinator; future launches only |
 
 **Removal precondition:** explicitly close a running worker before removing its entry. Since remote close is disabled, arrange explicit user closure in its terminal first. Intercom does not infer liveness from saved IDs/ports and cannot certify closure. No hidden probing or force-kill is performed.
 
@@ -77,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).
@@ -89,12 +101,26 @@ 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 extension receipt/acceptance, never model completion. 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. 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.
+
+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).
 
-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).
+## 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
 
+Run these commands from a source checkout; tests and workflows are not shipped in the npm package. The [original implementation validation snapshot](https://github.com/mbundgaard/PiIntercom/blob/main/references/implementation-progress.md) is historical, not the current live-test inventory.
+
 ```sh
 npm ci
 npm run typecheck
@@ -108,18 +134,51 @@ Production source runs through Pi's TypeScript loader; `npm run build` generates
 
 ## Publishing
 
-`.github/workflows/publish.yml` publishes through npm Trusted Publishing (GitHub OIDC), without an npm token secret. Configure the npm trusted publisher as owner `mbundgaard`, repository `PiIntercom`, workflow `publish.yml`, with no environment.
+[`.github/workflows/publish.yml`](https://github.com/mbundgaard/PiIntercom/blob/main/.github/workflows/publish.yml) publishes through npm Trusted Publishing (GitHub OIDC), without an npm token secret. Configure the npm trusted publisher as owner `mbundgaard`, repository `PiIntercom`, workflow `publish.yml`, with no environment.
 
 The workflow validates on Windows, then publishes with provenance from a GitHub-hosted Ubuntu runner. It runs when a GitHub release is published or when manually dispatched. Release tags must be `v<package.json version>`.
 
-Version `0.1.0` is already published and cannot be republished. For the next release, bump package and lockfile versions, commit/push, then publish a matching GitHub release. Do not dispatch publishing for an already published version. CI validates pushes and pull requests separately without publishing.
+Published versions are immutable. For a new release, bump package and lockfile versions, commit/push, then publish a matching GitHub release. Manual dispatch publishes the selected ref and is **not a dry run**; the release-tag check only applies when a release tag is present. Do not dispatch publishing for an already published version. CI validates pushes to `main` and pull requests separately without publishing.
+
+### Release evidence
+
+- [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):
+
+- Lifecycle generation/session checks reject stale queued or in-flight operations before submitting new launches, sends, deliveries or config publication. This includes delayed listener startup, anonymous registration and deferred status reporting. An OS link/rename or external action already submitted before invalidation is **not cancelled or rolled back**; there is no guarantee that in-flight external actions are drained.
+- 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.
+
+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.
+
+### Observed live behavior
+
+The release/session evidence reported during the 0.1.2 validation establishes these specific observations, not blanket lifecycle compliance:
 
-Tests use temporary directories, local test-only HTTP servers, and mocked Pi hosts/launch executors. They never start agents, tabs, terminals, contact models, services or bridges, or access credentials.
+- Encoded PowerShell invoking `pi.ps1` recovered an existing failed Herdr tab; Pi started and the worker registered.
+- After package update and Pi reload, coordinator `intercom_create_worker` launched three workers; each registered, then was explicitly configured and separately reloaded. Integration's configured name was applied through configure/reload.
+- An asynchronous Core → Coordinator message was relayed with `telegram_send` and receipt was confirmed by the owner. Telegram is a separate integration, not an Intercom transport or automatic forwarding feature.
 
-### Not live-tested / remaining limitations
+### Remaining limitations / not comprehensively live-tested
 
-- Actual Pi extension loading, idle/steering queue delivery, busy snapshots, session-name persistence, trust UI and session replacement/reload lifecycle with live Pi hosts.
-- Complete Herdr create/register/configure/rename flow still needs end-to-end validation. The Windows launch path uses `herdr pane run` on the returned pane ID to invoke `pi.ps1` through explicitly encoded PowerShell, avoiding Herdr's failing `Start-Process pi` wrapper. Command submission is not agent readiness. This command path was live-tested in the previously failed tab: Pi started and registered successfully. No Herdr agent alias is needed.
+- Idle/steering queue edge cases, busy snapshots, session-name persistence across restarts, trust UI and session replacement/reload lifecycle. The specific manual-compaction rejection gap described above remains unresolved; successful ordinary messaging does not verify that case.
+- The observations above do not establish all Herdr failure paths, tab-association edge cases or readiness guarantees.
 - Windows visible terminal/Pi process startup. Success only proves terminal creation, **not Pi readiness**; startup failures remain visible in that terminal. No live readiness handshake was added.
 - Actual persisted-session lookup and resumed worker startup; never-used session failure.
 - Cross-process/network-drive atomicity and Windows ACL/sharing failures (same-process temp-filesystem races are tested).

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.2",
+  "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",
+    "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/implementation-blocker.md

@@ -1,6 +1,6 @@
 # V1 cancellation capability blocked: Pi cancellation contract
 
-> **Current status:** The user subsequently approved implementing independent features. The supported core now exists; see `implementation-progress.md` and `../README.md`. Only stop/close remain disabled, failing before cancellation/shutdown. The historical feasibility report below is preserved as evidence; its statements that no implementation exists describe the earlier run, not current project status.
+> **Current status:** The user subsequently approved implementing independent features. The supported core now exists; see the [historical implementation snapshot](https://github.com/mbundgaard/PiIntercom/blob/main/references/implementation-progress.md) and [current README](../README.md). Stop/close remain disabled, failing before cancellation/shutdown; README also records the separate manual-compaction input-acceptance gap. The historical feasibility report below is preserved as evidence; its statements that no implementation exists describe the earlier run, not current project status.
 
 ## Historical outcome
 
@@ -40,7 +40,7 @@ No private-runtime access, repeated abort polling, synthetic Escape input, setti
 
 Added `tests/pi-cancellation-probe.test.mjs`, a dependency-free compatibility probe. It extracts selected installed methods and executes them with mocks; it does not construct a Pi session, read credentials, contact a model, bind a server, launch a process, or modify Herdr.
 
-Git Bash invocation:
+Git Bash invocation from a source checkout (the probe is not shipped in the npm package):
 
 ```bash
 PI_INTERCOM_PI_ROOT='C:/Users/martin/AppData/Roaming/npm/node_modules/@earendil-works/pi-coding-agent' \