@comput/pi-intercom 0.1.2 → 0.2.0

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

@@ -1,6 +1,8 @@
 # PiIntercom V1 Specification
 
-This is the consolidated record of the agreed V1 design. It supersedes conflicting wording in the original architecture proposal and historical discussion notes. Implementation gaps are listed separately at the end; they are not silently approved decisions.
+This is the consolidated **target design**, authoritative over conflicting wording in the original proposal and historical discussion notes. It is not a claim that every capability is currently supported. See [README](../README.md) for current behavior, release evidence and validation limits.
+
+**Current capability exception:** `intercom_stop_worker` and `intercom_close_worker` are registered but disabled on every host, before cancellation/shutdown or outgoing control. Their intended guarantees below remain unchanged; see the [cancellation blocker](implementation-blocker.md). Manual-compaction delivery also has a known acceptance gap: HTTP receipt does not guarantee Pi accepted the input. Unresolved contract questions are not silently approved decisions.
 
 ## 1. Scope and principles
 
@@ -34,7 +36,7 @@ Required configuration information:
 | Agent | Pi session ID, name, coordinator flag, responsibility description, port |
 | Worker | Project directory relative to coordinator root |
 
-Exact schema and versioning remain implementation gaps. Do not treat a saved endpoint or session ID as proof that its process exists.
+The implemented schema is version 1; its fields and validation are documented in [README: Config and wire contracts](../README.md#config-and-wire-contracts). Do not treat a saved endpoint or session ID as proof that its process exists.
 
 ## 3. Startup and registration
 
@@ -94,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
 
@@ -122,12 +124,12 @@ Every invocation reads the current Pi session ID and shared config, determines r
 | `intercom_create_worker` | Coordinator | `projectDirectory?` (default `.`) | Launch new anonymous worker with extension loaded; report launch success/failure without awaiting registration |
 | `intercom_configure_worker` | Coordinator | `sessionId`, `port`, `projectDirectory`, `name`, `description` | Write the explicitly supplied worker configuration; no notification |
 | `intercom_reload_worker` | Coordinator | `to` (name) | Send config-read control only |
-| `intercom_send` | Both | `to` (name), `message` | Deliver agent prompt/steering; return send result, not agent reply |
-| `intercom_list` | Both | None | Reread config; list names, responsibilities, IDs, roles, ports, without live probing |
+| `intercom_send` | Configured, responsibility-loaded sessions | `to` (name), `message` | Deliver agent prompt/steering; return send result, not agent reply |
+| `intercom_list` | Configured sessions | None | Reread config; list names, responsibilities, IDs, roles, ports, without live probing |
 | `intercom_request_status` | Coordinator | `to` (name) | Ask worker extension to send independent runtime status report |
-| `intercom_report_status` | Worker | None | Invoke shared reporting function; reject on coordinator |
-| `intercom_stop_worker` | Coordinator | `to` (name) | Cancel current work; leave Pi and extension running |
-| `intercom_close_worker` | Coordinator | `to` (name) | Cancel work, gracefully exit Pi, preserve session/config |
+| `intercom_report_status` | Worker, including anonymous | None | Invoke shared reporting function; reject on coordinator |
+| `intercom_stop_worker` | Coordinator | `to` (name) | Target: cancel current work; leave Pi and extension running. Currently disabled; unsupported-host error |
+| `intercom_close_worker` | Coordinator | `to` (name) | Target: cancel work, gracefully exit Pi, preserve session/config. Currently disabled; unsupported-host error |
 | `intercom_resume_worker` | Coordinator | `to` (name) | Launch saved session using configured directory and launcher; failures leave config unchanged |
 | `intercom_remove_worker` | Coordinator | `to` (name) | Remove config entry only; no process stop or session-file deletion |
 | `intercom_set_multiplexer` | Coordinator | `multiplexer` | Set `herdr` or `none` for future launches, including resume |
@@ -137,7 +139,7 @@ Every invocation reads the current Pi session ID and shared config, determines r
 - Configure rejects duplicate names, including `Coordinator`, case-insensitively. Keeping a session's own name is allowed.
 - Configure and reload are deliberately separate. Reload is not Pi's extension-code reload, a process restart, cancellation, or a work assignment. Explain this in tool and user documentation.
 - Reload synchronizes Pi session and applicable Herdr tab names to config.
-- Stop/close use Pi cancellation and graceful shutdown; no force-kill, automatic commit, or rollback. Close does not require a separate stop call.
+- Target contract: stop/close use Pi cancellation and graceful shutdown; no force-kill, automatic commit, or rollback. Close does not require a separate stop call. **Currently both fail closed; no stop or shutdown is performed.**
 - Close success at transport level is not proof that process exit has completed.
 - Remove a running worker only after explicitly closing it; removal itself never closes it.
 - Resume failure must be surfaced; no implicit removal, replacement, or reassignment.
@@ -156,21 +158,21 @@ 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.
 
 ## 9. Remaining implementation gaps — not new approved behavior
 
-Consolidate these before coding; avoid reopening settled user flows.
+Original design-gap inventory with current implementation annotations. Avoid reopening settled user flows. Implemented mechanisms are not proof of comprehensive live-host validation.
 
 1. **Registration handoff — resolved:** deliver reported session ID, port, and project directory into the coordinator Pi context. The coordinator agent decides what to do and supplies all values explicitly to configure_worker. No hidden pending-registration map, placeholder entry, or automatic configuration/reload workflow.
 2. **Retrying anonymous registration:** status reports do not create registrations. Define an explicit way to repeat a failed initial registration without conflating it with known-worker status.
-3. **Wire/config schemas:** finalize schema version, field names, control types, message envelope, validation, body limits, optional message IDs and receipt acknowledgment boundary. No synchronous agent reply semantics.
+3. **Wire/config schemas — implemented:** schema version 1, documented fields/control kinds, validation, 64 KiB body bound and extension-receipt acknowledgment are described in README. No message IDs, deduplication or synchronous agent replies. Receipt is not proof of Pi input acceptance or model completion.
 4. **Pi lifecycle APIs:** verify extension loading, session-ID resume lookup, cancellation, queued-message treatment on stop/close, busy detection, and session-switch cleanup. Stop must not unexpectedly restart queued work; exact API feasibility needs checking.
 5. **Launch integration:** verify installed Herdr operations and a Windows visible-terminal implementation, including readiness/launch-failure observability and tab association. A successful process launch is not worker registration success.
-6. **Configuration writes:** implement safe serialized/atomic coordinator writes and first-creation race handling. Define bounded handling of incomplete initialization. No malformed-file overwrites.
+6. **Configuration writes — implemented, validation limits remain:** serialized atomic updates and complete-file no-replace initial publication; invalid config is not overwritten. See README for filesystem assumptions and unverified cross-process/network-drive cases.
 7. **Missing coordinator session:** workers report connection failure and remain reachable. Explicit coordinator takeover is not specified or approved; do not invent it.
 8. **Unconfigured worker permissions:** explicitly define allowed worker-side tools before its entry exists, while retaining registration/reporting ability and forbidding coordinator operations.
 9. **Protocol control checks:** distinguish initial registration from configured-sender validation. Reload must reach the anonymous worker after the coordinator has created its entry.
@@ -180,4 +182,4 @@ Consolidate these before coding; avoid reopening settled user flows.
 - Read installed Pi documentation and relevant Herdr skills before implementation.
 - Document tool permissions, startup/registration flow, passive responsibility loading, separate configure/reload calls, and failure semantics.
 - Test role gates, port fallback, recipient mismatch, duplicate names, config errors, explicit recovery, and asynchronous steering/status paths.
-- No implementation code has been produced during this design discussion.
+- The original design discussion produced no implementation code. A supported-core implementation and releases now exist; current evidence and limitations are maintained in README.

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');
@@ -74,41 +80,60 @@ export class ConfigStore {
       const parent = path.dirname(at); if (parent === at) return undefined; at = parent;
     }
   }
+  protected openTemporary(file: string) { return open(file, 'wx'); }
   private async temporary(config: Config): Promise<string> {
     validateConfig(config);
     await mkdir(path.dirname(this.file), { recursive: true });
     const temp = `${this.file}.${randomUUID()}.tmp`;
-    const handle = await open(temp, 'wx');
-    try { await handle.writeFile(JSON.stringify(config, null, 2) + '\n'); await handle.sync(); }
-    finally { await handle.close(); }
-    return temp;
+    const handle = await this.openTemporary(temp);
+    try {
+      await handle.writeFile(JSON.stringify(config, null, 2) + '\n');
+      await handle.sync();
+      await handle.close();
+      return temp;
+    } catch (error) {
+      // Cleanup failures must not replace the original write/sync/close error.
+      await handle.close().catch(() => {});
+      await unlink(temp).catch(() => {});
+      throw error;
+    }
   }
-  async initialize(id: string, boundPort: number): Promise<boolean> {
+  async initialize(id: string, boundPort: number, assertValid: () => void = () => {}): Promise<boolean> {
     // Publish an already complete file using an atomic, no-replace hard link.
     // Losers only ever see complete JSON; unsupported filesystems fail explicitly.
+    assertValid();
     const temp = await this.temporary({ version: 1, multiplexer: 'herdr', agents: [{ sessionId: id, name: 'Coordinator', coordinator: true, description: DEFAULT_DESCRIPTION, port: boundPort, projectDirectory: '.' }] });
-    try { await link(temp, this.file); return true; }
-    catch (e) { if ((e as NodeJS.ErrnoException).code === 'EEXIST') { await this.read(); return false; } throw e; }
-    finally { await unlink(temp); }
+    try {
+      assertValid();
+      try { await link(temp, this.file); }
+      catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
+        await this.read(); await unlink(temp); return false;
+      }
+      await unlink(temp); return true;
+    } catch (error) { await unlink(temp).catch(() => {}); throw error; }
   }
-  async update(id: string, mutate: (config: Config) => void | Promise<void>): Promise<Config> {
+  async update(id: string, mutate: (config: Config) => void | Promise<void>, assertValid: () => void = () => {}): Promise<Config> {
     const operation = this.tail.then(async () => {
-      const c = await this.read(); requireCoordinator(c, id);
-      await mutate(c); validateConfig(c);
+      assertValid();
+      const c = await this.read(); assertValid(); requireCoordinator(c, id);
+      await mutate(c); assertValid(); validateConfig(c);
       const temp = await this.temporary(c);
-      try { await rename(temp, this.file); }
-      finally { await unlink(temp).catch(e => { if (e.code !== 'ENOENT') throw e; }); }
+      try {
+        // Last check before publication; an already submitted OS rename cannot be undone.
+        assertValid(); await rename(temp, this.file);
+      } catch (error) { await unlink(temp).catch(() => {}); throw error; }
       return c;
     });
     this.tail = operation.catch(() => {}); return operation;
   }
-  async configure(id: string, values: Omit<Agent, 'coordinator'>): Promise<Config> {
+  async configure(id: string, values: Omit<Agent, 'coordinator'>, assertValid: () => void = () => {}): Promise<Config> {
     return this.update(id, async c => {
       if (values.sessionId === coordinator(c).sessionId) fail('cannot configure coordinator as worker');
       const projectDirectory = await directory(this.root, values.projectDirectory);
       const a: Agent = { sessionId: values.sessionId, name: values.name, description: values.description, port: values.port, projectDirectory, coordinator: false };
       const index = c.agents.findIndex(old => old.sessionId === a.sessionId);
       if (index < 0) c.agents.push(a); else c.agents[index] = a;
-    });
+    }, assertValid);
   }
 }

package/src/dashboard.ts

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

package/src/index.ts

@@ -1,9 +1,11 @@
 import { fileURLToPath } from 'node:url';
+import path from 'node:path';
 import { Type, type TSchema } from 'typebox';
-import { SessionManager, truncateHead, withFileMutationQueue, type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { getAgentDir, SessionManager, SettingsManager, truncateHead, withFileMutationQueue, type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { ConfigStore } from './config.js';
 import { Intercom, UNSUPPORTED_CANCELLATION } from './runtime.js';
 import { launchers } from './launcher.js';
+import { startDashboard, type Dashboard } from './dashboard.js';
 
 const to = Type.Object({ to: Type.String({ minLength: 1, maxLength: 128 }) });
 const tools: [string, string, TSchema][] = [
@@ -21,20 +23,35 @@ const tools: [string, string, TSchema][] = [
   ['set_multiplexer', 'Coordinator only. Set herdr (default) or none (separate visible Windows terminals) for future launches. Never move/restart existing workers or fall back.', Type.Object({ multiplexer: Type.String({ enum: ['herdr', 'none'] }) })],
 ];
 
+// Launchers pass no --session-dir. Match child Pi's env > per-cwd settings >
+// default lookup, resolving relative paths against the child's cwd, not ours.
+// SettingsManager's public getter applies Pi's own path/tilde normalization.
+export function resumeSessionDirectory(cwd: string, envSessionDir = process.env.PI_CODING_AGENT_SESSION_DIR, agentDir = getAgentDir()): string | undefined {
+  const settings = envSessionDir
+    ? SettingsManager.inMemory({ sessionDir: envSessionDir })
+    : SettingsManager.create(cwd, path.resolve(cwd, agentDir));
+  const sessionDir = settings.getSessionDir();
+  return sessionDir ? path.resolve(cwd, sessionDir) : undefined;
+}
+
 // Participate in Pi's own per-file mutation queue as well as Intercom serialization.
 class PiConfigStore extends ConfigStore {
-  override update(id: string, mutate: Parameters<ConfigStore['update']>[1]) {
-    return withFileMutationQueue(this.file, () => super.update(id, mutate));
+  override update(id: string, mutate: Parameters<ConfigStore['update']>[1], assertValid?: () => void) {
+    return withFileMutationQueue(this.file, () => super.update(id, mutate, assertValid));
   }
 }
 export default function intercomExtension(pi: ExtensionAPI): void {
   let runtime: Intercom | undefined;
   let context: ExtensionContext | undefined;
+  let dashboard: Dashboard | undefined;
+  let generation = 0;
   const launcher = launchers({
     extension: fileURLToPath(import.meta.url),
-    sessionExists: async (cwd, id) => (await SessionManager.list(cwd, process.env.PI_CODING_AGENT_SESSION_DIR)).some(s => s.id === id),
+    sessionExists: async (cwd, id) => (await SessionManager.list(cwd, resumeSessionDirectory(cwd))).some(s => s.id === id),
   });
   pi.on('session_start', async (_event, ctx) => {
+    const started = ++generation;
+    await dashboard?.close(); dashboard = undefined;
     await runtime?.close(); context = ctx;
     if (process.platform !== 'win32' || ctx.mode !== 'tui') throw new Error('PiIntercom V1 requires Windows interactive Pi. No resources started.');
     if (!ctx.isProjectTrusted()) throw new Error('PiIntercom requires project trust before honoring shared project configuration.');
@@ -46,10 +63,43 @@ export default function intercomExtension(pi: ExtensionAPI): void {
       setName: async name => { if (pi.getSessionName() !== name) pi.setSessionName(name); await launcher.syncName(name); },
       notify: text => ctx.ui.notify(text, 'info'),
     }, { launch: launcher.launch, store: root => new PiConfigStore(root) });
-    try { await runtime.start(); }
-    catch (e) { runtime = undefined; ctx.ui.notify(String(e), 'error'); }
+    const current = runtime;
+    try { await current.start(); }
+    catch (e) { if (runtime === current) runtime = undefined; ctx.ui.notify(String(e), 'error'); return; }
+    if (started !== generation) return;
+    let server: Dashboard | undefined;
+    let savingPort = false;
+    try {
+      if ((await current.state()).me?.coordinator) {
+        server = await startDashboard(current.store.root);
+        if (started !== generation) { await server.close(); return; }
+        savingPort = true;
+        await current.recordDashboardPort(server.port);
+        if (started !== generation) { await server.close(); return; }
+        dashboard = server;
+        ctx.ui.notify(`Intercom read-only dashboard: ${server.url} (saved URL is last-known, not live availability)`, 'info');
+      }
+    } catch {
+      await server?.close().catch(() => {});
+      if (started !== generation) return;
+      ctx.ui.notify(savingPort
+        ? 'Intercom dashboard port could not be saved; the new dashboard was closed. Any saved URL is last-known only. Messaging remains available.'
+        : 'Intercom dashboard unavailable; communication remains independent.', 'error');
+    }
+  });
+  pi.on('session_shutdown', async () => {
+    generation++;
+    await dashboard?.close(); dashboard = undefined;
+    await runtime?.close(); runtime = undefined; context = undefined;
+  });
+  pi.on('agent_start', async (_event, ctx) => {
+    context = ctx;
+    runtime?.recordObservation('host.activity', { busy: !ctx.isIdle(), outcome: 'started' });
+  });
+  pi.on('agent_settled', async (_event, ctx) => {
+    context = ctx;
+    runtime?.recordObservation('host.activity', { busy: !ctx.isIdle(), outcome: 'settled' });
   });
-  pi.on('session_shutdown', async () => { await runtime?.close(); runtime = undefined; context = undefined; });
   pi.on('before_agent_start', async (event, ctx) => {
     context = ctx;
     if (!runtime) return;