@comput/pi-intercom 0.1.2 → 0.2.0

package/src/observability.ts

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

package/src/runtime.ts

@@ -1,5 +1,7 @@
 import path from 'node:path';
-import { ConfigStore, coordinator, directory, fail, named, requireCoordinator, type Agent, type Config } from './config.js';
+import { randomUUID } from 'node:crypto';
+import { LocalObserver, LOG_LIMITS, observationError, type Observer, type EventType, type EventMetadata } from './observability.js';
+import { ConfigStore, coordinator, directory, fail, named, port, requireCoordinator, type Agent, type Config } from './config.js';
 import { listen, send, type Endpoint, type Envelope, type Kind } from './transport.js';
 
 export const UNSUPPORTED_CANCELLATION = 'Unsupported Pi host: stop_worker and close_worker are disabled. Pi 0.84.4 extension abort does not cancel retry backoff/continuations; graceful shutdown cannot guarantee no queued work restarts. No cancellation or shutdown was performed. See references/implementation-blocker.md. A verified supported host API is required (no version-only override).';
@@ -17,81 +19,200 @@ export interface RuntimeOptions {
   listen?: typeof listen;
   send?: typeof send;
   store?: (root: string) => ConfigStore;
+  observe?: (root: string, sessionId: string) => Observer;
 }
 export class Intercom {
   store!: ConfigStore;
   endpoint?: Endpoint;
   private active = false;
+  private generation = 0;
   private initialId = '';
   responsibility?: Agent;
+  private observer?: Observer;
+  private closing?: Promise<void>;
+  private captureObserver(): (event: EventType, metadata?: EventMetadata) => void {
+    const observer = this.observer;
+    return (event, metadata = {}) => {
+      try { observer?.record(event, metadata); } catch { /* Logging cannot affect communication. */ }
+    };
+  }
+  recordObservation(event: EventType, metadata: EventMetadata = {}): void { this.captureObserver()(event, metadata); }
   constructor(readonly host: Host, readonly options: RuntimeOptions) {}
   private id(): string {
     const id = this.host.sessionId();
     if (!this.active || id !== this.initialId) fail('session is inactive or replaced');
     return id;
   }
+  private validity(): () => void {
+    const generation = this.generation;
+    this.id();
+    return () => {
+      this.id();
+      if (generation !== this.generation) fail('runtime lifecycle replaced');
+    };
+  }
   async start(): Promise<void> {
+    if (this.closing) await this.closing;
+    if (this.active) fail('runtime already active');
     this.initialId = this.host.sessionId(); this.active = true;
+    const generation = ++this.generation, assertValid = this.validity();
+    let record = this.captureObserver();
     try {
       const discovered = await ConfigStore.discover(this.host.cwd);
+      assertValid();
       this.store = this.options.store?.(discovered?.root ?? this.host.cwd) ?? discovered ?? new ConfigStore(this.host.cwd);
+      try { this.observer = this.options.observe ? this.options.observe(this.store.root, this.initialId) : new LocalObserver(this.store.root, this.initialId); } catch { /* Logging is optional on failure. */ }
+      record = this.captureObserver();
+      record('runtime.starting');
       const previous = discovered ? await this.store.read() : undefined;
+      assertValid();
       const own = previous?.agents.find(a => a.sessionId === this.id());
-      this.endpoint = await (this.options.listen ?? listen)(own?.port, m => this.receive(m));
-      if (!previous) await this.store.initialize(this.id(), this.endpoint.port);
+      const endpoint = await (this.options.listen ?? listen)(own?.port, m => { assertValid(); return this.receive(m); });
+      try { assertValid(); } catch (error) { await endpoint.close(); throw error; }
+      this.endpoint = endpoint;
+      if (!previous) {
+        const initialized = await this.store.initialize(this.id(), this.endpoint.port, assertValid);
+        if (initialized) record('config.changed', { operation: 'initialize', outcome: 'written' });
+      }
       const config = await this.store.read();
+      assertValid();
       const me = config.agents.find(a => a.sessionId === this.id());
       if (me?.coordinator) {
-        await this.store.update(this.id(), c => { requireCoordinator(c, this.id()).port = this.endpoint!.port; });
-        try { await this.reload(); } catch (e) { this.host.notify(`Name/responsibility synchronization failed: ${String(e)}`); }
+        try { this.observer?.maintain?.(); } catch { /* No cleanup failure affects readiness. */ }
+        await this.store.update(this.id(), c => { requireCoordinator(c, this.id()).port = this.endpoint!.port; }, assertValid);
+        assertValid();
+        record('config.changed', { operation: 'port_update', outcome: 'written', port: this.endpoint.port });
+        try { await this.reload(); } catch (e) { assertValid(); this.host.notify(`Name/responsibility synchronization failed: ${String(e)}`); }
+        assertValid();
         this.host.notify(`Intercom Coordinator ready at 127.0.0.1:${this.endpoint.port}; waiting for user input.`);
       } else {
-        if (me) { try { await this.reload(); } catch (e) { this.host.notify(`Name/responsibility synchronization failed: ${String(e)}`); } }
+        if (me) { try { await this.reload(); } catch (e) { assertValid(); this.host.notify(`Name/responsibility synchronization failed: ${String(e)}`); } }
+        assertValid();
         try {
           if (me) await this.report();
-          else await this.transmit(coordinator(config).name, 'registration', { port: this.endpoint.port, projectDirectory: await directory(this.store.root, this.host.cwd) });
-        } catch (e) { this.host.notify(`Coordinator unreachable/registration failed; worker remains reachable: ${String(e)}. No retry. Anonymous registration repeat is an unresolved contract; use explicit Pi /reload to restart this extension, not report_status.`); }
+          else {
+            const projectDirectory = await directory(this.store.root, this.host.cwd);
+            assertValid();
+            await this.transmit(coordinator(config).name, 'registration', { port: this.endpoint.port, projectDirectory });
+          }
+        } catch (e) { assertValid(); this.host.notify(`Coordinator unreachable/registration failed; worker remains reachable: ${String(e)}. No retry. Anonymous registration repeat is an unresolved contract; use explicit Pi /reload to restart this extension, not report_status.`); }
+        assertValid();
         this.host.notify(`Intercom worker ready at 127.0.0.1:${this.endpoint.port}; waiting for explicit work.`);
       }
-    } catch (e) { await this.close(); throw e; }
+      record('runtime.ready', { port: this.endpoint.port, role: me?.coordinator ? 'coordinator' : me ? 'worker' : 'anonymous', busy: this.host.busy(), outcome: 'ready' });
+    } catch (e) {
+      if (generation === this.generation) {
+        record('runtime.failed', { errorCode: observationError(e), outcome: 'failed' });
+        await this.close();
+      }
+      throw e;
+    }
   }
   async close(): Promise<void> {
-    this.active = false;
+    if (this.closing) return this.closing;
+    this.recordObservation('runtime.closed');
+    const observer = this.observer; this.observer = undefined;
+    this.active = false; this.generation++;
     const endpoint = this.endpoint; this.endpoint = undefined;
-    if (endpoint) await endpoint.close();
     this.responsibility = undefined;
+    const closing = (async () => {
+      try { if (endpoint) await endpoint.close(); }
+      finally {
+        if (observer) {
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          try {
+            // Only shutdown waits, and only for this bounded deadline. Already-issued I/O cannot be cancelled.
+            await Promise.race([
+              Promise.resolve().then(() => observer.close()).catch(() => {}),
+              new Promise<void>(resolve => { timer = setTimeout(resolve, LOG_LIMITS.closeTimeoutMs); }),
+            ]);
+          } finally { if (timer) clearTimeout(timer); }
+        }
+      }
+    })();
+    this.closing = closing;
+    try { await closing; } finally { if (this.closing === closing) this.closing = undefined; }
   }
   async state(): Promise<{ id: string; config: Config; me?: Agent }> {
+    const assertValid = this.validity();
     const id = this.id(), config = await this.store.read();
-    this.id();
+    assertValid();
     return { id, config, me: config.agents.find(a => a.sessionId === id) };
   }
+  /** Persist an actual dashboard bind; saved discovery metadata, not a live-status assertion. */
+  async recordDashboardPort(boundPort: number): Promise<void> {
+    const record = this.captureObserver(), assertValid = this.validity();
+    const { id, config } = await this.state();
+    assertValid(); requireCoordinator(config, id); port(boundPort);
+    await this.store.update(id, c => { requireCoordinator(c, id).dashboardPort = boundPort; }, assertValid);
+    record('config.changed', { outcome: 'written' });
+  }
   async reload(): Promise<void> {
+    const record = this.captureObserver();
+    const assertValid = this.validity();
     const { me } = await this.state();
+    assertValid();
     if (!me) fail('worker not configured; configure_worker must run before reload_worker');
     this.responsibility = { ...me };
     await this.host.setName(me.name);
+    assertValid();
+    record('config.reloaded', { role: me.coordinator ? 'coordinator' : 'worker' });
     this.host.notify(`Intercom responsibility loaded for ${me.name}; no work turn started.`);
   }
   async transmit(to: string, kind: Kind, payload: Record<string, unknown> = {}): Promise<void> {
+    const record = this.captureObserver();
+    const assertValid = this.validity();
     const { id, config } = await this.state();
-    const target = named(config, to);
-    await (this.options.send ?? send)(target.port, { version: 1, from: id, to: target.sessionId, kind, payload });
+    assertValid();
+    const target = named(config, to), correlationId = randomUUID();
+    const metadata = { peerSessionId: target.sessionId, peerName: target.name, correlationId, kind };
+    record('transport.send', { ...metadata, outcome: 'attempted' });
+    try {
+      await (this.options.send ?? send)(target.port, { version: 1, from: id, to: target.sessionId, kind, payload, correlationId });
+      record('transport.receipt', { ...metadata, outcome: 'http_receipt' });
+    } catch (error) {
+      record('transport.failed', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+      throw error;
+    }
   }
   async report(): Promise<void> {
+    const assertValid = this.validity();
     const { config, me } = await this.state();
+    assertValid();
     if (me?.coordinator) fail('report_status is worker-only');
     if (!this.endpoint) fail('endpoint unavailable');
     await this.transmit(coordinator(config).name, 'status', { port: this.endpoint.port, busy: this.host.busy() });
   }
   async receive(message: Envelope): Promise<void> {
+    const record = this.captureObserver();
+    const metadata = { peerSessionId: message.from, correlationId: message.correlationId, kind: message.kind };
+    record('transport.received', metadata);
+    try { await this.handleReceive(message); }
+    catch (error) {
+      record('transport.rejected', { ...metadata, outcome: 'handler_failed', errorCode: observationError(error) });
+      throw error;
+    }
+  }
+  private async handleReceive(message: Envelope): Promise<void> {
+    const record = this.captureObserver();
+    const assertValid = this.validity();
     const { id, config, me } = await this.state();
+    assertValid();
     if (message.to !== id) fail('recipient session ID mismatch (stale endpoint)');
     const sender = config.agents.find(a => a.sessionId === message.from);
     const busy = this.host.busy();
+    const metadata = { peerSessionId: message.from, peerName: sender?.name, correlationId: message.correlationId, kind: message.kind, busy };
     const notify = (purpose: string, content: string) => {
-      this.id();
-      this.host.deliver(`[Intercom ${purpose} from ${sender?.name ?? 'unconfigured worker'} (${message.from})]\n${content}`, busy);
+      assertValid();
+      record('host.submission', { ...metadata, outcome: 'attempted' });
+      try {
+        this.host.deliver(`[Intercom ${purpose} from ${sender?.name ?? 'unconfigured worker'} (${message.from})]\n${content}`, busy);
+        // A synchronous return is not Pi queue acceptance or model completion.
+        record('host.submission', { ...metadata, outcome: 'returned' });
+      } catch (error) {
+        record('host.submission', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+        throw error;
+      }
     };
     if (message.kind === 'registration' || message.kind === 'status') {
       requireCoordinator(config, id);
@@ -99,12 +220,15 @@ export class Intercom {
       if (message.kind === 'registration') {
         const projectDirectory = await directory(this.store.root, message.payload.projectDirectory as string);
         // No pending map, placeholder or configuration mutation.
+        record('registration.received', { ...metadata, port: message.payload.port as number });
         notify('registration', JSON.stringify({ sessionId: message.from, port: message.payload.port, projectDirectory }) + '\nThis is connection information, not a work assignment. Configure explicitly, then reload separately.');
       } else {
         if (sender) await this.store.update(id, c => {
           const entry = c.agents.find(a => a.sessionId === message.from && !a.coordinator);
           if (entry) entry.port = message.payload.port as number;
-        });
+        }, assertValid);
+        record('status.received', { ...metadata, busy: message.payload.busy as boolean, port: message.payload.port as number });
+        if (sender) record('config.changed', { operation: 'port_update', peerSessionId: message.from, port: message.payload.port as number, outcome: 'written' });
         notify('status', JSON.stringify({ sessionId: message.from, port: message.payload.port, busy: message.payload.busy, configured: !!sender }));
       }
       return;
@@ -120,16 +244,26 @@ export class Intercom {
     if (message.kind === 'reload') { await this.reload(); return; }
     if (message.kind === 'request_status') {
       // Independent one-way report, never a synchronous status in the HTTP response.
-      setImmediate(() => { if (this.active) void this.report().catch(e => this.host.notify(`Status report failed: ${String(e)}`)); });
+      setImmediate(() => {
+        try { assertValid(); } catch { return; } // Closed/replaced requests cannot report for a new lifecycle.
+        void this.report().catch(e => {
+          try { assertValid(); } catch { return; }
+          this.host.notify(`Status report failed: ${String(e)}`);
+        });
+      });
       return;
     }
     fail('unsupported control');
   }
   async tool(operation: string, args: Record<string, unknown>): Promise<unknown> {
+    const record = this.captureObserver();
+    const assertValid = this.validity();
     const { id, config, me } = await this.state();
+    assertValid();
     if (operation === 'list') {
       if (!me) fail('anonymous intercom_list permissions unresolved (TODO); no coordinator privileges');
-      return config;
+      const dashboardPort = coordinator(config).dashboardPort;
+      return { ...config, dashboardUrl: dashboardPort === undefined ? null : `http://127.0.0.1:${dashboardPort}/` };
     }
     if (operation === 'report_status') { await this.report(); return { accepted: true }; }
     if (operation === 'send') {
@@ -139,15 +273,18 @@ export class Intercom {
     requireCoordinator(config, id);
     if (operation === 'stop_worker' || operation === 'close_worker') fail(UNSUPPORTED_CANCELLATION);
     if (operation === 'configure_worker') {
-      await this.store.configure(id, args as unknown as Omit<Agent, 'coordinator'>);
+      await this.store.configure(id, args as unknown as Omit<Agent, 'coordinator'>, assertValid);
+      record('config.changed', { operation: 'configure_worker', peerSessionId: args.sessionId as string, peerName: args.name as string, outcome: 'written' });
       return { written: true, reloaded: false };
     }
     if (operation === 'set_multiplexer') {
-      await this.store.update(id, c => { c.multiplexer = args.multiplexer as Config['multiplexer']; }); return { written: true };
+      await this.store.update(id, c => { c.multiplexer = args.multiplexer as Config['multiplexer']; }, assertValid);
+      record('config.changed', { operation: 'set_multiplexer', outcome: 'written' }); return { written: true };
     }
     if (operation === 'create_worker') {
       const relative = await directory(this.store.root, (args.projectDirectory as string | undefined) ?? '.');
-      return this.options.launch({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative) });
+      assertValid();
+      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative) });
     }
     const target = named(config, args.to as string);
     if (target.coordinator) fail('operation requires a worker target');
@@ -157,13 +294,28 @@ export class Intercom {
     }
     if (operation === 'resume_worker') {
       const relative = await directory(this.store.root, target.projectDirectory);
-      return this.options.launch({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), sessionId: target.sessionId });
+      assertValid();
+      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), sessionId: target.sessionId });
     }
     if (operation === 'remove_worker') {
       // No live process claim: the caller must explicitly ensure closure first.
-      await this.store.update(id, c => { c.agents = c.agents.filter(a => a.sessionId !== target.sessionId); });
+      await this.store.update(id, c => { c.agents = c.agents.filter(a => a.sessionId !== target.sessionId); }, assertValid);
+      record('config.changed', { operation: 'remove_worker', peerSessionId: target.sessionId, peerName: target.name, outcome: 'removed' });
       return { removed: true, processStopped: false, sessionDeleted: false };
     }
     fail(`unknown operation ${operation}`);
   }
+  private async launchObserved(request: LaunchRequest): Promise<unknown> {
+    const record = this.captureObserver();
+    const metadata: EventMetadata = { operation: request.sessionId ? 'resume_worker' : 'create_worker', peerSessionId: request.sessionId };
+    record('launch.result', { ...metadata, outcome: 'attempted' });
+    try {
+      const result = await this.options.launch(request);
+      record('launch.result', { ...metadata, outcome: 'returned' });
+      return result;
+    } catch (error) {
+      record('launch.result', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+      throw error;
+    }
+  }
 }

package/src/transport.ts

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