@comput/pi-intercom 0.5.1 → 0.6.1

package/src/monitor-view.ts

@@ -1,8 +1,9 @@
 import { stripVTControlCharacters } from 'node:util';
 import { truncateToWidth, visibleWidth } from 'pi-intercom-tui';
-import type { ObservationSnapshot } from './snapshot.js';
+import { publicCloseMetadata, type ObservationSnapshot } from './snapshot.js';
 import { workerObservation } from './worker-status.js';
 import { currentConnection, sortWorkersByConnection } from './connections.js';
+import { INTERCOM_VERSION } from './version.js';
 
 const safe = (value: string) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f\u2028-\u202e\u2066-\u2069]/g, ' ');
 const clip = (value: string, width: number) => stripVTControlCharacters(truncateToWidth(safe(value), Math.max(0, width)));
@@ -73,7 +74,9 @@ export function renderMonitor(snapshot: ObservationSnapshot | undefined, width:
     const selectedIndex = Math.min(workers.length - 1, Math.max(-1, options.selectedIndex ?? -1));
     const showDetails = Boolean(options.details && selectedIndex >= 0 && height >= 8);
     const selectedReport = snapshot.reports?.find(report => report.sessionId === workers[selectedIndex]?.sessionId && reportLabels[report.status]);
-    const detailBudget = showDetails ? Math.min(selectedReport ? 15 : 8, height - 5) : 0;
+    const selectedSaved = workers[selectedIndex] ? publicCloseMetadata(workers[selectedIndex]) : {};
+    const hasSaved = !!(selectedSaved.handoff || selectedSaved.closeJob);
+    const detailBudget = showDetails ? Math.min(hasSaved ? 22 : selectedReport ? 15 : 8, height - 5) : 0;
     const available = Math.max(0, height - lines.length - 2 - detailBudget);
     const needsOverflow = workers.length > available;
     const count = Math.min(workers.length, Math.max(0, available - (needsOverflow && available > 1 ? 1 : 0)));
@@ -93,7 +96,32 @@ export function renderMonitor(snapshot: ObservationSnapshot | undefined, width:
       const selected = start + offset === selectedIndex;
       const report = snapshot.reports?.find(report => report.sessionId === worker.sessionId && reportLabels[report.status]);
       lines.push(table(worker.name, connection.state, activity, age, evidence, report ? reportLabels[report.status] : '—', tone, selected));
-      if (selected && showDetails && report) {
+      if (selected && showDetails && hasSaved) {
+        const savedAge = (timestamp: string) => {
+          const elapsed = now - Date.parse(timestamp);
+          return elapsed < 0 || !Number.isFinite(elapsed) ? 'clock uncertain' : ageLabel(elapsed) + (elapsed > snapshot.staleAfterMs ? ' (old)' : '');
+        };
+        const { handoff, closeJob } = selectedSaved;
+        const context = [
+          ...(closeJob ? [line(`  Close workflow: ${closeJob.state}${closeJob.reason ? ` · ${closeJob.reason}` : ''} · ${savedAge(closeJob.updatedAt)}`)] : []),
+          line(handoff ? `  Saved handoff (public): ${savedAge(handoff.updatedAt)}` : '  Saved handoff: none'),
+        ];
+        selectedDetail = [
+          ...context,
+          ...(handoff ? wrapSummary(`Handoff: ${handoff.summary}`, Math.max(0, width - 2), Math.min(4, Math.max(0, detailBudget - context.length))).map(text => line(`  ${text}`)) : []),
+          ...(handoff ? [line(`  Handoff saved: ${handoff.updatedAt}`)] : []),
+          ...(report ? [
+            line(`  Report: ${reportLabels[report.status]} · ${savedAge(report.updatedAt)}`),
+            line('  Self-reported, pending review'),
+            ...wrapSummary(`Summary: ${report.summary}`, Math.max(0, width - 2), 2).map(text => line(`  ${text}`)),
+          ] : []),
+          ...connectionDetails,
+          line(`  Responsibility: ${worker.description || 'Not specified'}`),
+          line(`  Observed status: ${activity} · ${age}`),
+          line(`  Last activity: ${evidence}`),
+          ...(closeJob ? [line(`  Close updated: ${closeJob.updatedAt}`), line('  Workflow state is not proof all child processes terminated')] : []),
+        ];
+      } else if (selected && showDetails && report) {
         const elapsed = now - Date.parse(report.updatedAt);
         const reportAge = !Number.isFinite(elapsed) || elapsed < 0 ? 'clock uncertain' : ageLabel(elapsed) + (elapsed > snapshot.staleAfterMs ? ' (old)' : '');
         const contextRows = detailBudget >= 8 ? [
@@ -124,7 +152,23 @@ export function renderMonitor(snapshot: ObservationSnapshot | undefined, width:
   const partial = snapshot && (snapshot.truncated || snapshot.errors.length);
   const controls = options.details ? 'q quit · Esc back · ↑↓ select' : 'q quit · ↑↓ select · Enter details';
   const hasReports = snapshot?.reports?.some(report => reportLabels[report.status] && snapshot.config?.agents.some(agent => !agent.coordinator && agent.sessionId === report.sessionId));
-  const footer = width < 18 ? 'q quit' : `  ${controls}${partial ? ' · Partial observations' : ''}${hasReports ? ' · Reports: self-reported, pending review' : ''}`;
+  const version = `v${safe(INTERCOM_VERSION)}`;
+  const fullVersion = `Intercom ${version}`;
+  const label = width >= visibleWidth(controls) + visibleWidth(fullVersion) + 4 ? fullVersion : version;
+  const room = width - visibleWidth(label) - 2;
+  let footer = width < 6 ? 'q' : 'q quit';
+  if (room >= 6) {
+    const compactControls = options.details ? 'q quit · Esc · ↑↓' : 'q quit · ↑↓ · Enter';
+    const prefix = room >= 8 ? '  ' : '';
+    const available = room - prefix.length;
+    const hint = visibleWidth(controls) <= available ? controls : visibleWidth(compactControls) <= available ? compactControls : 'q quit';
+    const caveats = `${partial ? ' · Partial observations' : ''}${hasReports ? ' · Reports: self-reported, pending review' : ''}`;
+    // Lower-priority caveats may truncate, but never consume the quit hint or
+    // the reserved version label. Keep the version flush with the right edge.
+    const left = prefix + hint + clip(caveats, Math.max(0, available - visibleWidth(hint)));
+    footer = left + ' '.repeat(Math.max(2, width - visibleWidth(left) - visibleWidth(label))) + label;
+  }
+  lines.splice(Math.max(0, height - 1));
   while (lines.length < height - 1) lines.push('');
   lines.push(dim(line(footer)));
   return lines.slice(0, height);

package/src/observability.ts

@@ -10,7 +10,7 @@ export const EVENT_TYPES = ['runtime.starting', 'runtime.ready', 'runtime.closed
 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', 'report', 'registration', 'status', 'request_status', 'reload', 'stop', 'close'] as const;
+const KINDS = ['message', 'report', 'registration', 'status', 'request_status', 'reload', 'stop', 'close', 'close_prepare', 'close_identity', 'close_request', 'handoff_report', 'close_ready', 'close_commit'] as const;
 const OPERATIONS = ['configure_worker', 'set_multiplexer', 'remove_worker', 'create_worker', 'resume_worker', 'port_update', 'initialize'] as const;
 export interface EventMetadata {
   peerSessionId?: string;

package/src/pane-close.ts

@@ -0,0 +1,138 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { constants } from 'node:fs';
+import { open, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import type { Run } from './launcher.js';
+import type { CloseProvider, WorkerPaneIdentity } from './handoff.js';
+
+interface ProcessIdentity { start: string; state: string }
+export interface PaneCloseOptions {
+  sessionId(): string;
+  sessionFile(): string | undefined;
+  env?: NodeJS.ProcessEnv;
+  platform?: string;
+  pid?: number;
+  run?: Run;
+  processIdentity?: (pid: number) => Promise<ProcessIdentity | undefined>;
+  verifySession?: (file: string, id: string) => Promise<void>;
+  verificationMs?: number;
+}
+const rejected = () => new Error('PiIntercom: worker pane identity could not be verified; no close submitted.');
+const exec: Run = async (file, args) => (await promisify(execFile)(file, args, {
+  windowsHide: true, timeout: 4000, maxBuffer: 1024 * 1024,
+})).stdout;
+
+/** Linux process start ticks distinguish a reused PID from the original worker. */
+export async function linuxProcessIdentity(pid: number): Promise<ProcessIdentity | undefined> {
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw rejected();
+  let stat: string;
+  try { stat = await readFile(`/proc/${pid}/stat`, 'utf8'); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return; throw rejected(); }
+  const fields = stat.slice(stat.lastIndexOf(')') + 2).trim().split(/\s+/);
+  if (!/^[0-9]+$/.test(fields[19] ?? '') || !/^[A-Za-z]$/.test(fields[0] ?? '')) throw rejected();
+  return { start: fields[19], state: fields[0] };
+}
+async function verifySessionHeader(file: string, id: string): Promise<void> {
+  if (!path.isAbsolute(file) || file.length > 4096 || file.includes('\0')) throw rejected();
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    if (!(await handle.stat()).isFile()) throw rejected();
+    // Inspect only the first session-header line, never transcript messages.
+    const buffer = Buffer.alloc(4096);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const end = buffer.subarray(0, bytesRead).indexOf(10);
+    if (end < 0) throw rejected();
+    const header = JSON.parse(buffer.subarray(0, end).toString('utf8'));
+    if (header?.type !== 'session' || header.id !== id) throw rejected();
+  } finally { await handle.close(); }
+}
+const alive = (identity: ProcessIdentity | undefined, start: string) =>
+  !!identity && identity.start === start && !['Z', 'X', 'x'].includes(identity.state);
+
+/** Linux Herdr only. Identity-checked best effort; Herdr has no atomic compare-and-close API. */
+export function createCloseProvider(options: PaneCloseOptions): CloseProvider | undefined {
+  const env = options.env ?? process.env;
+  if ((options.platform ?? process.platform) !== 'linux' || env.HERDR_ENV !== '1' || !env.HERDR_PANE_ID) return;
+  const run = options.run ?? exec;
+  const processIdentity = options.processIdentity ?? linuxProcessIdentity;
+  const verifySession = options.verifySession ?? verifySessionHeader;
+  const ownPid = options.pid ?? process.pid;
+  const verificationMs = Math.max(0, Math.min(2000, options.verificationMs ?? 1500));
+  async function query(args: string[]): Promise<any> {
+    const output = await run('herdr', args);
+    if (Buffer.byteLength(output) > 1024 * 1024) throw rejected();
+    return JSON.parse(output)?.result;
+  }
+  async function caller(): Promise<any> {
+    const pane = (await query(['pane', 'current', '--current']))?.pane;
+    if (!pane || typeof pane.pane_id !== 'string' || typeof pane.workspace_id !== 'string' || typeof pane.terminal_id !== 'string') throw rejected();
+    return pane;
+  }
+  async function verifyPane(pane: any, identity: WorkerPaneIdentity): Promise<void> {
+    if (!pane || pane.pane_id !== identity.paneId || pane.workspace_id !== identity.workspaceId ||
+      pane.terminal_id !== identity.terminalId || pane.agent !== 'pi' ||
+      pane.agent_session?.source !== 'herdr:pi' || pane.agent_session?.kind !== 'path' ||
+      typeof pane.agent_session.value !== 'string' || !path.isAbsolute(identity.sessionFile) ||
+      !Number.isSafeInteger(identity.pid) || identity.pid <= 0 || !/^[0-9]+$/.test(identity.processStart)) throw rejected();
+    if (await realpath(pane.agent_session.value) !== await realpath(identity.sessionFile)) throw rejected();
+    await verifySession(identity.sessionFile, identity.sessionId);
+    const info = (await query(['pane', 'process-info', '--pane', identity.paneId]))?.process_info;
+    if (info?.pane_id !== identity.paneId || !Array.isArray(info.foreground_processes) ||
+      !info.foreground_processes.some((p: { pid?: number }) => p.pid === identity.pid) ||
+      !alive(await processIdentity(identity.pid), identity.processStart)) throw rejected();
+  }
+  async function inspect(identity: WorkerPaneIdentity, expectedSessionId: string, assertCurrent: () => void): Promise<void> {
+    assertCurrent();
+    if (identity.sessionId !== expectedSessionId || expectedSessionId === options.sessionId() || identity.pid === ownPid) throw rejected();
+    const own = await caller();
+    assertCurrent();
+    if (own.pane_id === identity.paneId || own.workspace_id !== identity.workspaceId) throw rejected();
+    await verifyPane((await query(['pane', 'get', identity.paneId]))?.pane, identity);
+    assertCurrent();
+  }
+  return {
+    async getIdentity() {
+      try {
+        const sessionId = options.sessionId(), sessionFile = options.sessionFile();
+        if (!sessionFile) throw rejected();
+        const pane = await caller();
+        const process = await processIdentity(ownPid);
+        if (!process || !alive(process, process.start)) throw rejected();
+        const identity: WorkerPaneIdentity = { workspaceId: pane.workspace_id, paneId: pane.pane_id,
+          terminalId: pane.terminal_id, sessionId, sessionFile, pid: ownPid, processStart: process.start };
+        await verifyPane(pane, identity);
+        if (options.sessionId() !== sessionId || options.sessionFile() !== sessionFile) throw rejected();
+        return identity;
+      } catch { throw rejected(); }
+    },
+    async inspect(identity, expectedSessionId, assertCurrent) {
+      try { await inspect(identity, expectedSessionId, assertCurrent); } catch { throw rejected(); }
+    },
+    async close(identity, expectedSessionId, assertCurrent, beforeSubmit) {
+      try { await inspect(identity, expectedSessionId, assertCurrent); } catch { throw rejected(); }
+      assertCurrent();
+      // Revalidate worker settlement only AFTER potentially slow ownership reads.
+      // Herdr still has no atomic cross-process identity/idle compare-and-close.
+      await beforeSubmit();
+      assertCurrent();
+      // Exactly one explicit pane target. No tab/workspace close, retry, or force kill.
+      // A CLI timeout can mean the mutation happened: caller must persist uncertainty.
+      try { await run('herdr', ['pane', 'close', identity.paneId]); }
+      catch { throw new Error('PiIntercom: pane close outcome uncertain; inspect before any retry.'); }
+      let paneClosed = false, workerExited = false;
+      try {
+        const panes = (await query(['pane', 'list', '--workspace', identity.workspaceId]))?.panes;
+        paneClosed = Array.isArray(panes) && panes.every(p => typeof p?.pane_id === 'string') &&
+          !panes.some(p => p.pane_id === identity.paneId);
+        const deadline = Date.now() + verificationMs;
+        do {
+          workerExited = !alive(await processIdentity(identity.pid), identity.processStart);
+          if (workerExited || Date.now() >= deadline) break;
+          await new Promise(resolve => setTimeout(resolve, 50));
+        } while (true);
+      } catch { /* Verification failure is uncertainty, never an automatic retry. */ }
+      return { paneClosed, workerExited };
+    },
+  };
+}

package/src/runtime.ts

@@ -7,8 +7,9 @@ import { saveWorkerReport } from './reports.js';
 import { readObservationSnapshot } from './snapshot.js';
 import { workerStatusPage } from './worker-status.js';
 import { probeWorker, probeWorkers } from './connections.js';
+import { HandoffWorkflow, HANDOFF_KINDS, fencedClose, type CloseProvider, type HandoffKind } from './handoff.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 const UNSUPPORTED_CANCELLATION = 'Unsupported Pi host: stop_worker and legacy graceful-close control 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. close_worker uses a separate supported-provider owned-pane closure contract, not graceful cancellation. See references/implementation-blocker.md. A verified supported host API is required for graceful cancellation (no version-only override).';
 export interface Host {
   sessionId(): string;
   cwd: string;
@@ -25,6 +26,9 @@ export interface RuntimeOptions {
   probe?: typeof probeWorker;
   store?: (root: string) => ConfigStore;
   observe?: (root: string, sessionId: string) => Observer;
+  closeProvider?: CloseProvider;
+  /** Test seam; production defaults to 120 seconds, values above that are capped. */
+  closeTimeoutMs?: number;
 }
 export class Intercom {
   store!: ConfigStore;
@@ -39,6 +43,9 @@ export class Intercom {
   private pendingReports = 0;
   private probeController = new AbortController();
   private resumeFences = new Map<string, { inFlight: boolean; submitted: boolean; announced: boolean }>();
+  private handoff?: HandoffWorkflow;
+  workerStarted(): void { this.handoff?.workerStarted(); }
+  workerSettled(successfulToolCallIds: ReadonlySet<string>): void { this.handoff?.workerSettled(successfulToolCallIds); }
   private captureObserver(): (event: EventType, metadata?: EventMetadata) => void {
     const observer = this.observer;
     return (event, metadata = {}) => {
@@ -91,7 +98,23 @@ export class Intercom {
       const config = await this.store.read();
       assertValid();
       const me = config.agents.find(a => a.sessionId === this.id());
+      this.handoff = new HandoffWorkflow({
+        state: () => this.state(), assertCurrent: assertValid,
+        update: async (mutate, guard) => {
+          await this.store.update(this.initialId, mutate, () => { assertValid(); guard?.(); });
+        },
+        send: async (sessionId, kind, payload) => {
+          const state = await this.state(); assertValid();
+          const target = state.config.agents.find(a => a.sessionId === sessionId);
+          if (!target) fail('handoff recipient no longer configured');
+          await (this.options.send ?? send)(target.port, { version: 1, kind, from: state.id, to: sessionId, payload, correlationId: randomUUID() });
+          assertValid();
+        },
+        deliver: message => { assertValid(); this.host.deliver(message, this.host.busy()); },
+        busy: () => this.host.busy(), provider: this.options.closeProvider, timeoutMs: this.options.closeTimeoutMs,
+      });
       if (me?.coordinator) {
+        await this.handoff.recover(); assertValid();
         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();
@@ -128,6 +151,7 @@ export class Intercom {
     const observer = this.observer; this.observer = undefined;
     this.active = false; this.generation++;
     this.probeController.abort();
+    this.handoff?.dispose(); this.handoff = undefined;
     const endpoint = this.endpoint; this.endpoint = undefined;
     this.responsibility = undefined;
     const closing = (async () => {
@@ -170,7 +194,8 @@ export class Intercom {
     assertValid();
     if (!me) fail('worker not configured; configure_worker must run before reload_worker');
     this.responsibility = { ...me };
-    await this.host.setName(me.name);
+    // Coordinator is a routing identity, not ownership of the user's Pi/tab title.
+    if (!me.coordinator) 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.`);
@@ -181,6 +206,7 @@ export class Intercom {
     const { id, config } = await this.state();
     assertValid();
     const target = named(config, to), correlationId = randomUUID();
+    if (['message', 'reload'].includes(kind) && (this.handoff?.isClosing(target.sessionId) || fencedClose(target.closeJob))) fail('worker close is active or uncertain; new Intercom work is fenced');
     const metadata = { peerSessionId: target.sessionId, peerName: target.name, correlationId, kind };
     record('transport.send', { ...metadata, outcome: 'attempted' });
     try {
@@ -232,6 +258,10 @@ export class Intercom {
         throw error;
       }
     };
+    if (HANDOFF_KINDS.includes(message.kind)) {
+      if (!this.handoff || !me || (!me.coordinator && !this.responsibility)) fail('handoff requires a configured, responsibility-loaded worker');
+      await this.handoff.receive(message.kind as HandoffKind, message.from, message.payload); return;
+    }
     if (message.kind === 'registration' || message.kind === 'status') {
       requireCoordinator(config, id);
       if (sender?.coordinator) fail('coordinator cannot report as worker');
@@ -281,12 +311,16 @@ export class Intercom {
     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');
+      if (this.handoff?.workerClosing || fencedClose(me.closeJob)) fail('worker close is active or uncertain; new Intercom work is fenced');
       notify('agent message', message.payload.message as string); return;
     }
     if (!sender?.coordinator) fail('control requires current coordinator sender session ID');
     if (me?.coordinator) fail('worker control cannot target coordinator');
     if (message.kind === 'stop' || message.kind === 'close') fail(UNSUPPORTED_CANCELLATION);
-    if (message.kind === 'reload') { await this.reload(); return; }
+    if (message.kind === 'reload') {
+      if (this.handoff?.workerClosing || fencedClose(me?.closeJob)) fail('worker close is active or uncertain; reload is fenced');
+      await this.reload(); return;
+    }
     if (message.kind === 'request_status') {
       // Independent one-way report, never a synchronous status in the HTTP response.
       setImmediate(() => {
@@ -300,7 +334,7 @@ export class Intercom {
     }
     fail('unsupported control');
   }
-  async tool(operation: string, args: Record<string, unknown>): Promise<unknown> {
+  async tool(operation: string, args: Record<string, unknown>, toolCallId?: string): Promise<unknown> {
     const record = this.captureObserver();
     const assertValid = this.validity();
     const { id, config, me } = await this.state();
@@ -322,6 +356,10 @@ export class Intercom {
       if (!me) fail('anonymous intercom_list permissions unresolved (TODO); no coordinator privileges');
       return { ...config, agents: config.agents.map(({ dashboardPort: _retired, ...agent }) => agent) };
     }
+    if (operation === 'report_handoff') {
+      if (!me || me.coordinator || !this.responsibility || !this.handoff) fail('report_handoff requires a configured, responsibility-loaded worker');
+      return this.handoff.report(args.jobId, args.summary, toolCallId);
+    }
     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');
@@ -331,12 +369,19 @@ export class Intercom {
     }
     if (operation === 'send') {
       if (!me || !this.responsibility) fail('anonymous/unloaded worker cannot send agent messages (permissions TODO)');
+      const recipient = named(config, args.to as string);
+      if (this.handoff?.workerClosing || fencedClose(me.closeJob) || this.handoff?.isClosing(recipient.sessionId) || fencedClose(recipient.closeJob)) fail('worker close is active or uncertain; new Intercom work is fenced');
       await this.transmit(args.to as string, 'message', { message: args.message }); return { accepted: true, completion: 'not awaited' };
     }
     requireCoordinator(config, id);
-    if (operation === 'stop_worker' || operation === 'close_worker') fail(UNSUPPORTED_CANCELLATION);
+    if (operation === 'stop_worker') fail(UNSUPPORTED_CANCELLATION);
     if (operation === 'configure_worker') {
-      await this.store.configure(id, args as unknown as Omit<Agent, 'coordinator'>, assertValid);
+      const assertConfigurable = () => {
+        assertValid();
+        if (this.handoff?.isClosing(args.sessionId as string) || this.resumeFences.has(args.sessionId as string)) fail('worker lifecycle operation is in flight; configuration is fenced');
+      };
+      assertConfigurable();
+      await this.store.configure(id, args as unknown as Omit<Agent, 'coordinator'>, assertConfigurable);
       record('config.changed', { operation: 'configure_worker', peerSessionId: args.sessionId as string, peerName: args.name as string, outcome: 'written' });
       return { written: true, reloaded: false };
     }
@@ -351,6 +396,12 @@ export class Intercom {
     }
     const target = named(config, args.to as string);
     if (target.coordinator) fail('operation requires a worker target');
+    if (operation === 'close_worker') {
+      if (!this.options.closeProvider || !this.handoff || config.multiplexer !== 'herdr') fail('Owned-pane close requires supported Linux Herdr provider; no closure attempted');
+      if (this.resumeFences.has(target.sessionId)) fail('resume is in flight; close is fenced');
+      return { job: await this.handoff.request(target), completion: 'not awaited', contract: 'best-effort owned-pane closure; not all-child-process termination' };
+    }
+    if (['reload_worker', 'resume_worker', 'remove_worker'].includes(operation) && (this.handoff?.isClosing(target.sessionId) || fencedClose(target.closeJob))) fail('worker close is active or uncertain; operation is fenced');
     if (operation === 'reload_worker' || operation === 'request_status') {
       await this.transmit(target.name, operation === 'reload_worker' ? 'reload' : 'request_status');
       return { accepted: true, completion: 'not awaited' };
@@ -373,6 +424,7 @@ export class Intercom {
         requireCoordinator(fresh.config, id);
         const current = fresh.config.agents.find(agent => agent.sessionId === target.sessionId && !agent.coordinator);
         if (!current || current.port !== target.port || current.projectDirectory !== target.projectDirectory) fail('Worker configuration changed during resume check; no launch submitted.');
+        if (this.handoff?.isClosing(target.sessionId) || fencedClose(current.closeJob)) fail('worker close is active or uncertain; resume is fenced');
         fence.submitted = true;
         const result = await this.launchObserved({ multiplexer: fresh.config.multiplexer, cwd, sessionId: current.sessionId });
         completed = true;
@@ -384,7 +436,11 @@ export class Intercom {
     }
     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); }, assertValid);
+      await this.store.update(id, c => {
+        const current = c.agents.find(a => a.sessionId === target.sessionId);
+        if (this.handoff?.isClosing(target.sessionId) || this.resumeFences.has(target.sessionId) || fencedClose(current?.closeJob)) fail('worker lifecycle operation is active or uncertain; removal is fenced');
+        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 };
     }

package/src/snapshot.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { validateConfig, type Config } from './config.js';
 import { readWorkerReports, type WorkerReport } from './reports.js';
 import type { WorkerConnection } from './connections.js';
+import { validateHandoff, validateCloseJob, type Handoff, type CloseJob } from './handoff.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;
@@ -21,6 +22,26 @@ export interface ObservationSnapshot {
   errors: string[];
 }
 
+/** Public saved context only; reject malformed/private protocol metadata. */
+export function publicCloseMetadata(agent: { handoff?: unknown; closeJob?: unknown }): { handoff?: Handoff; closeJob?: CloseJob } {
+  const result: { handoff?: Handoff; closeJob?: CloseJob } = {};
+  try {
+    if (agent.handoff !== undefined) {
+      validateHandoff(agent.handoff);
+      const { version, summary, updatedAt, jobId } = agent.handoff;
+      result.handoff = { version, summary, updatedAt, jobId };
+    }
+  } catch { /* Invalid optional context is not public evidence. */ }
+  try {
+    if (agent.closeJob !== undefined) {
+      validateCloseJob(agent.closeJob);
+      const { jobId, state, createdAt, updatedAt, deadlineAt, reason } = agent.closeJob;
+      result.closeJob = { jobId, state, createdAt, updatedAt, deadlineAt, ...(reason ? { reason } : {}) };
+    }
+  } catch { /* Never expose arbitrary errors or private protocol fields. */ }
+  return result;
+}
+
 // 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> {
@@ -65,7 +86,7 @@ export async function readObservationSnapshot(root: string): Promise<Observation
     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,
+      projectDirectory: a.projectDirectory, port: a.port, ...publicCloseMetadata(a),
     })) };
   } catch { result.errors.push('config_unavailable'); }
   try {

package/src/transport.ts

@@ -1,10 +1,11 @@
 import http from 'node:http';
 import { fail, port, text } from './config.js';
 import type { ReportStatus } from './reports.js';
+import { HANDOFF_KINDS, validateHandoffPayload, type HandoffKind } from './handoff.js';
 
 export const BODY_LIMIT = 64 * 1024;
 export const RECEIPT_TIMEOUT = 5000;
-export type Kind = 'message' | 'report' | 'registration' | 'status' | 'request_status' | 'reload' | 'stop' | 'close';
+export type Kind = 'message' | 'report' | 'registration' | 'status' | 'request_status' | 'reload' | 'stop' | 'close' | HandoffKind;
 export interface Envelope {
   version: 1;
   kind: Kind;
@@ -23,12 +24,13 @@ export function reportPayload(payload: Record<string, unknown>): { status: Repor
 }
 export function envelope(value: unknown): Envelope {
   const m = value as Envelope;
-  if (!m || m.version !== 1 || !['message', 'report', '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', ...HANDOFF_KINDS].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 (HANDOFF_KINDS.includes(m.kind)) validateHandoffPayload(m.kind, 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/version.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+
+// Both src/ and dist/ sit directly below this package's own manifest. Capture
+// once at process startup, not from cwd or on each render after an update.
+function packageVersion(): string {
+  try {
+    const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    const version: unknown = manifest.version;
+    if (typeof version === 'string' && version.length <= 64 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version)) return version;
+  } catch { /* A display label must never prevent the monitor starting. */ }
+  return 'unknown';
+}
+export const INTERCOM_VERSION = packageVersion();

package/src/worker-status.ts

@@ -1,4 +1,4 @@
-import type { ObservationSnapshot } from './snapshot.js';
+import { publicCloseMetadata, type ObservationSnapshot } from './snapshot.js';
 import { currentConnection, sortWorkersByConnection } from './connections.js';
 
 const labels: Record<string, string> = {
@@ -49,14 +49,21 @@ export function workerStatusPage(snapshot: ObservationSnapshot, options: { name?
   }
   const workers: Array<{ sessionId: string; [key: string]: unknown }> = [];
   const result = { version: 1, source: 'local-observations', generatedAt: new Date(now).toISOString(),
-    statusMeaning: 'Activity is last observed, not task completion. Connectivity is a separate endpoint check, never proof of termination. Reports are self-reported, not approval.',
+    statusMeaning: 'Activity is last observed, not task completion. Connectivity is a separate endpoint check, never proof of termination. Reports are self-reported, not approval. Handoff is saved public context, not task completion; closeJob is workflow state, never proof that all child processes terminated.',
     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 saved = publicCloseMetadata(agent);
+    const ageSeconds = (timestamp: string) => {
+      const age = now - Date.parse(timestamp);
+      return Number.isFinite(age) && age >= 0 ? Math.floor(age / 1000) : null;
+    };
     const entry = { sessionId: agent.sessionId, name: agent.name, ...workerObservation(snapshot, agent.sessionId, now),
       connection: currentConnection(agent.sessionId, snapshot.connections, now),
+      handoff: saved.handoff ? { ...saved.handoff, ageSeconds: ageSeconds(saved.handoff.updatedAt), selfReported: true } : null,
+      closeJob: saved.closeJob ? { ...saved.closeJob, ageSeconds: ageSeconds(saved.closeJob.updatedAt) } : null,
       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 };