@comput/pi-intercom 0.3.0 → 0.4.2

package/src/reports.ts

@@ -0,0 +1,122 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+
+export type ReportStatus = 'blocked' | 'needs_decision' | 'ready_for_review' | 'clear';
+export interface WorkerReport {
+  version: 1;
+  sessionId: string;
+  status: ReportStatus;
+  summary: string;
+  updatedAt: string;
+}
+const MAX_BYTES = 8 * 1024;
+const MAX_IDS = 256;
+const statuses = new Set<ReportStatus>(['blocked', 'needs_decision', 'ready_for_review', 'clear']);
+const controls = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/;
+function validId(id: unknown): id is string {
+  return typeof id === 'string' && id.length > 0 && id.length <= 256 && id.trim().length > 0 && !/[\x00-\x1f\x7f-\x9f]/.test(id);
+}
+function validate(value: unknown): WorkerReport | undefined {
+  if (!value || typeof value !== 'object') return;
+  const v = value as Record<string, unknown>;
+  if (v.version !== 1 || !validId(v.sessionId) || !statuses.has(v.status as ReportStatus)) return;
+  if (typeof v.summary !== 'string' || v.summary.length > 2000 || controls.test(v.summary)) return;
+  if (v.status === 'clear' ? v.summary !== '' : !v.summary.trim()) return;
+  if (typeof v.updatedAt !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(v.updatedAt)) return;
+  const timestamp = Date.parse(v.updatedAt);
+  if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== v.updatedAt) return;
+  return { version: 1, sessionId: v.sessionId, status: v.status as ReportStatus, summary: v.summary, updatedAt: v.updatedAt };
+}
+function filename(id: string): string {
+  return `${createHash('sha256').update(id).digest('hex')}.json`;
+}
+/** Reject links at the root and both extension-owned directory components. */
+async function directory(root: string, create: boolean, assertCurrent?: () => void): Promise<string> {
+  if ((await lstat(root)).isSymbolicLink()) throw new Error('unsafe root');
+  let current = await realpath(root);
+  for (const segment of ['.pi-intercom', 'reports']) {
+    current = path.join(current, segment);
+    if (create) {
+      assertCurrent?.();
+      try { await mkdir(current, { mode: 0o700 }); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error; }
+    }
+    const info = await lstat(current);
+    if (!info.isDirectory() || info.isSymbolicLink() || path.relative(current, await realpath(current)) !== '') throw new Error('unsafe directory');
+  }
+  return current;
+}
+async function regularOrAbsent(file: string): Promise<void> {
+  try {
+    const info = await lstat(file);
+    if (!info.isFile() || info.isSymbolicLink()) throw new Error('unsafe file');
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+}
+
+/** Persist only the explicitly authored public report; clear is an atomic tombstone. */
+export async function saveWorkerReport(root: string, report: WorkerReport, assertCurrent?: () => void): Promise<void> {
+  let temporary: string | undefined;
+  let ownsTemporary = false;
+  let dir: string | undefined;
+  try {
+    const safe = validate(report);
+    if (!safe) throw new Error('invalid report');
+    const content = JSON.stringify(safe) + '\n';
+    if (Buffer.byteLength(content) > MAX_BYTES) throw new Error('oversized report');
+    assertCurrent?.();
+    dir = await directory(root, true, assertCurrent);
+    const target = path.join(dir, filename(safe.sessionId));
+    await regularOrAbsent(target);
+    temporary = path.join(dir, `.${filename(safe.sessionId)}.${randomUUID()}.tmp`);
+    assertCurrent?.();
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+    ownsTemporary = true;
+    try { assertCurrent?.(); await handle.writeFile(content, 'utf8'); }
+    finally { await handle.close(); }
+    if (await directory(root, false) !== dir) throw new Error('directory changed');
+    await regularOrAbsent(target);
+    assertCurrent?.();
+    await rename(temporary, target);
+    temporary = undefined;
+  } catch { throw new Error('Worker report could not be saved.'); }
+  finally {
+    if (temporary && ownsTemporary && dir) {
+      // Cleanup only our own unpublished temporary file, even if authorization expired.
+      try { if (await directory(root, false) === dir) await unlink(temporary); } catch { /* No raw filesystem errors or unsafe cleanup. */ }
+    }
+  }
+}
+
+/** Read at most 256 configured IDs; no directory scan, repair, transport, or host access. */
+export async function readWorkerReports(root: string, sessionIds: readonly string[]): Promise<WorkerReport[]> {
+  const reports: WorkerReport[] = [];
+  let dir: string;
+  try { dir = await directory(root, false); } catch { return reports; }
+  const seen = new Set<string>();
+  for (const id of sessionIds.slice(0, MAX_IDS)) {
+    if (!validId(id) || seen.has(id)) continue;
+    seen.add(id);
+    try {
+      if (await directory(root, false) !== dir) break;
+      const file = path.join(dir, filename(id));
+      const info = await lstat(file);
+      if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_BYTES) continue;
+      const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+      let text: string;
+      try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > MAX_BYTES) continue;
+        // One extra byte detects concurrent growth, while keeping reads bounded.
+        const buffer = Buffer.alloc(MAX_BYTES + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > MAX_BYTES) continue;
+        text = buffer.subarray(0, bytesRead).toString('utf8');
+      } finally { await handle.close(); }
+      const report = validate(JSON.parse(text));
+      if (report?.sessionId === id) reports.push(report);
+    } catch { /* Missing, unsafe, malformed or concurrently replaced evidence is unavailable. */ }
+  }
+  return reports;
+}

package/src/runtime.ts

@@ -2,7 +2,10 @@ import path from 'node:path';
 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';
+import { listen, send, reportPayload, type Endpoint, type Envelope, type Kind } from './transport.js';
+import { saveWorkerReport } from './reports.js';
+import { readObservationSnapshot } from './snapshot.js';
+import { workerStatusPage } from './worker-status.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).';
 export interface Host {
@@ -30,6 +33,8 @@ export class Intercom {
   responsibility?: Agent;
   private observer?: Observer;
   private closing?: Promise<void>;
+  private reportWrites: Promise<void> = Promise.resolve();
+  private pendingReports = 0;
   private captureObserver(): (event: EventType, metadata?: EventMetadata) => void {
     const observer = this.observer;
     return (event, metadata = {}) => {
@@ -139,12 +144,13 @@ export class Intercom {
     assertValid();
     return { id, config, me: config.agents.find(a => a.sessionId === id) };
   }
-  /** Persist an actual dashboard bind; saved discovery metadata, not a live-status assertion. */
-  async recordDashboardPort(boundPort: number): Promise<void> {
+  /** Accept old configs, but retire the removed browser dashboard's discovery metadata. */
+  async retireDashboardMetadata(): 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);
+    assertValid();
+    if (requireCoordinator(config, id).dashboardPort === undefined) return;
+    await this.store.update(id, c => { delete requireCoordinator(c, id).dashboardPort; }, assertValid);
     record('config.changed', { outcome: 'written' });
   }
   async reload(): Promise<void> {
@@ -233,6 +239,27 @@ export class Intercom {
       }
       return;
     }
+    if (message.kind === 'report') {
+      requireCoordinator(config, id);
+      if (!sender || sender.coordinator) fail('work reports require a configured worker sender');
+      const payload = reportPayload(message.payload);
+      if (this.pendingReports >= 64) fail('report queue full; no report stored');
+      this.pendingReports++;
+      const pending = this.reportWrites.then(async () => {
+        assertValid();
+        const fresh = await this.state();
+        requireCoordinator(fresh.config, id);
+        if (!fresh.config.agents.some(agent => agent.sessionId === message.from && !agent.coordinator)) fail('reporting worker is no longer configured');
+        await saveWorkerReport(this.store.root, { version: 1, sessionId: message.from, ...payload, updatedAt: new Date().toISOString() }, assertValid);
+        assertValid();
+        try {
+          notify('worker report', `Report: ${payload.status}\n${payload.summary}\nThis is a worker-authored public report, not approval or verified completion. Evaluate it before deciding any next step. Clearing retires the report only; it does not resume or complete work.`);
+        } catch { fail('Report stored, but coordinator notification failed or became uncertain; do not blindly resend'); }
+      });
+      this.reportWrites = pending.catch(() => {}).finally(() => { this.pendingReports--; });
+      await pending;
+      return;
+    }
     if (message.kind === 'message') {
       if (!sender || !me) fail('agent messaging requires configured sender and recipient; anonymous permissions TODO');
       if (!this.responsibility) fail('worker must load responsibility before receiving work');
@@ -260,12 +287,23 @@ export class Intercom {
     const assertValid = this.validity();
     const { id, config, me } = await this.state();
     assertValid();
+    if (operation === 'worker_status') {
+      if (!me) fail('worker_status requires a configured session');
+      const snapshot = await readObservationSnapshot(this.store.root);
+      assertValid();
+      return workerStatusPage(snapshot, { name: args.name as string | undefined, offset: args.offset as number | undefined, limit: args.limit as number | undefined });
+    }
     if (operation === 'list') {
       if (!me) fail('anonymous intercom_list permissions unresolved (TODO); no coordinator privileges');
-      const dashboardPort = coordinator(config).dashboardPort;
-      return { ...config, dashboardUrl: dashboardPort === undefined ? null : `http://127.0.0.1:${dashboardPort}/` };
+      return { ...config, agents: config.agents.map(({ dashboardPort: _retired, ...agent }) => agent) };
     }
     if (operation === 'report_status') { await this.report(); return { accepted: true }; }
+    if (operation === 'report_work') {
+      if (!me || me.coordinator || !this.responsibility) fail('report_work requires a configured, responsibility-loaded worker');
+      const payload = reportPayload(args);
+      await this.transmit(coordinator(config).name, 'report', payload);
+      return { accepted: true, coordinatorEvaluation: 'not awaited' };
+    }
     if (operation === 'send') {
       if (!me || !this.responsibility) fail('anonymous/unloaded worker cannot send agent messages (permissions TODO)');
       await this.transmit(args.to as string, 'message', { message: args.message }); return { accepted: true, completion: 'not awaited' };

package/src/{dashboard.ts → snapshot.ts}

@@ -1,19 +1,19 @@
-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 { readWorkerReports, type WorkerReport } from './reports.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 {
+export interface ObservationSnapshot {
   version: 1;
   generatedAt: string;
   staleAfterMs: number;
   config: Pick<Config, 'multiplexer' | 'agents'> | null;
   events: Observation[];
+  reports?: WorkerReport[];
   truncated: boolean;
   errors: string[];
 }
@@ -53,8 +53,9 @@ async function boundedRead(file: string, limit: number, tail = false): Promise<{
   } 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: [] };
+/** Bounded, sanitized local evidence, independent of any UI or HTTP server. */
+export async function readObservationSnapshot(root: string): Promise<ObservationSnapshot> {
+  const result: ObservationSnapshot = { 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));
@@ -62,7 +63,6 @@ export async function readDashboardSnapshot(root: string): Promise<DashboardSnap
     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 {
@@ -100,59 +100,8 @@ export async function readDashboardSnapshot(root: string): Promise<DashboardSnap
     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'); }
+  result.reports = result.config
+    ? await readWorkerReports(root, result.config.agents.filter(agent => !agent.coordinator).map(agent => agent.sessionId))
+    : [];
   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/transport.ts

@@ -1,9 +1,10 @@
 import http from 'node:http';
 import { fail, port, text } from './config.js';
+import type { ReportStatus } from './reports.js';
 
 export const BODY_LIMIT = 64 * 1024;
 export const RECEIPT_TIMEOUT = 5000;
-export type Kind = 'message' | 'registration' | 'status' | 'request_status' | 'reload' | 'stop' | 'close';
+export type Kind = 'message' | 'report' | 'registration' | 'status' | 'request_status' | 'reload' | 'stop' | 'close';
 export interface Envelope {
   version: 1;
   kind: Kind;
@@ -13,13 +14,21 @@ export interface Envelope {
   /** Optional diagnostics correlation only; never authentication or agent identity. */
   correlationId?: string;
 }
+export function reportPayload(payload: Record<string, unknown>): { status: ReportStatus; summary: string } {
+  if (!['blocked', 'needs_decision', 'ready_for_review', 'clear'].includes(payload.status as string)) fail('invalid report status');
+  const status = payload.status as ReportStatus;
+  const summary = payload.summary ?? '';
+  if (typeof summary !== 'string' || summary.length > 2000 || (status !== 'clear' && !summary.trim()) || (status === 'clear' && summary !== '')) fail('report requires a public summary of 1–2000 characters, or empty summary for clear');
+  return { status, summary };
+}
 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');
+  if (!m || m.version !== 1 || !['message', 'report', '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 === 'report') reportPayload(m.payload);
   if (m.kind === 'registration' || m.kind === 'status') port(m.payload.port);
   if (m.kind === 'registration') text(m.payload.projectDirectory, 'projectDirectory');
   if (m.kind === 'status' && typeof m.payload.busy !== 'boolean') fail('invalid busy flag');

package/src/worker-status.ts

@@ -0,0 +1,66 @@
+import type { ObservationSnapshot } from './snapshot.js';
+
+const labels: Record<string, string> = {
+  processing: 'Processing', thinking: 'Thinking', responding: 'Writing response',
+  reading_files: 'Reading files', editing_files: 'Editing files', running_command: 'Running command',
+  using_tool: 'Using a tool', multiple_tools: 'Running multiple tools', settled: 'Turn settled',
+};
+export function workerObservation(snapshot: ObservationSnapshot, sessionId: string, now = Date.now()) {
+  const events = snapshot.events.filter(e => e.sessionId === sessionId &&
+    ['runtime.ready', 'host.activity', 'runtime.closed'].includes(e.event) &&
+    (e.event === 'runtime.closed' || typeof e.busy === 'boolean') && Number.isFinite(Date.parse(e.timestamp)));
+  const latest = events.reduce<(typeof events)[number] | undefined>((best, e) =>
+    !best || Date.parse(e.timestamp) > Date.parse(best.timestamp) ? e : best, undefined);
+  let observedStatus = 'unknown', lastActivity = 'no observation';
+  let observationAgeSeconds: number | null = null, stale: boolean | null = null;
+  let evidence = 'missing';
+  if (latest) {
+    const elapsed = now - Date.parse(latest.timestamp);
+    if (elapsed < 0) { evidence = 'clock_uncertain'; lastActivity = 'clock uncertain'; }
+    else {
+      observationAgeSeconds = Math.floor(elapsed / 1000);
+      stale = elapsed > snapshot.staleAfterMs;
+      const ties = events.filter(e => e.timestamp === latest.timestamp);
+      const conflict = ties.some(e => (e.event === 'runtime.closed') !== (latest.event === 'runtime.closed') || e.busy !== latest.busy || (e.phase && latest.phase && e.phase !== latest.phase));
+      if (conflict) { evidence = 'conflicting'; lastActivity = 'conflicting records'; }
+      else {
+        evidence = stale ? 'stale' : 'recent';
+        observedStatus = latest.event === 'runtime.closed' ? 'closed' : !latest.busy ? 'idle' : latest.phase === 'thinking' ? 'thinking' : 'working';
+        const detail = events.filter(e => e.writerId === latest.writerId && e.detail && !['processing', 'settled'].includes(e.detail) && Date.parse(e.timestamp) <= Date.parse(latest.timestamp))
+          .reduce<(typeof events)[number] | undefined>((best, e) => !best || e.timestamp > best.timestamp ? e : best, undefined);
+        lastActivity = latest.event === 'runtime.closed' ? 'Runtime closed'
+          : (detail?.detail ? labels[detail.detail] : latest.detail ? labels[latest.detail] : latest.busy ? 'Processing' : 'No active turn');
+      }
+    }
+  }
+  return { observedStatus, lastActivity, observedAt: latest?.timestamp ?? null, observationAgeSeconds, stale, evidence };
+}
+
+/** Bounded JSON data for agents/any presentation layer. No Telegram, UI, probing or model calls. */
+export function workerStatusPage(snapshot: ObservationSnapshot, options: { name?: string; offset?: number; limit?: number } = {}, now = Date.now()) {
+  const offset = options.offset ?? 0, limit = options.limit ?? 10;
+  if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 20) throw new Error('Invalid pagination: offset >= 0, limit 1–20');
+  if (options.name !== undefined && (typeof options.name !== 'string' || !options.name.trim())) throw new Error('Worker name must be nonblank');
+  let roster = snapshot.config?.agents.filter(a => !a.coordinator) ?? [];
+  if (options.name !== undefined) {
+    roster = roster.filter(a => a.name.toLowerCase() === options.name!.toLowerCase());
+    if (snapshot.config && !roster.length) throw new Error('Worker name not found in the retained snapshot');
+  }
+  const workers: Array<Record<string, unknown>> = [];
+  const result = { version: 1, source: 'local-observations', generatedAt: new Date(now).toISOString(),
+    statusMeaning: 'Last observed, not live liveness or task completion. Reports are self-reported, not approval.',
+    truncated: snapshot.truncated, errors: snapshot.errors, totalInSnapshot: roster.length, offset,
+    nextOffset: null as number | null, workers };
+  for (const agent of roster.slice(offset, offset + limit)) {
+    const report = snapshot.reports?.find(r => r.sessionId === agent.sessionId && r.status !== 'clear');
+    const reportAge = report ? now - Date.parse(report.updatedAt) : NaN;
+    const entry = { sessionId: agent.sessionId, name: agent.name, ...workerObservation(snapshot, agent.sessionId, now),
+      report: report ? { status: report.status, summary: report.summary, updatedAt: report.updatedAt,
+        ageSeconds: Number.isFinite(reportAge) && reportAge >= 0 ? Math.floor(reportAge / 1000) : null,
+        selfReported: true } : null };
+    workers.push(entry);
+    if (Buffer.byteLength(JSON.stringify(result, null, 2)) > 40000) { workers.pop(); break; }
+  }
+  if (offset + workers.length < roster.length) result.nextOffset = offset + workers.length;
+  return result;
+}

package/dashboard/app.js

@@ -1,182 +0,0 @@
-'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();
-})();