@comput/pi-intercom 0.5.2 → 0.6.1

package/src/handoff.ts

@@ -0,0 +1,280 @@
+import { randomUUID } from 'node:crypto';
+import type { Agent, Config } from './config.js';
+
+export interface WorkerPaneIdentity {
+  workspaceId: string; paneId: string; terminalId: string; sessionId: string;
+  sessionFile: string; pid: number; processStart: string;
+}
+export interface CloseProvider {
+  getIdentity(): Promise<WorkerPaneIdentity>;
+  inspect(identity: WorkerPaneIdentity, expectedSessionId: string, assertCurrent: () => void): Promise<void>;
+  close(identity: WorkerPaneIdentity, expectedSessionId: string, assertCurrent: () => void, beforeSubmit: () => Promise<void>): Promise<{ paneClosed: boolean; workerExited: boolean }>;
+}
+export type CloseReason = 'timeout' | 'interrupted' | 'delivery_failed' | 'identity_failed' | 'save_failed' | 'worker_changed' | 'worker_busy' | 'commit_rejected' | 'close_unverified' | 'close_failed';
+export type CloseState = 'requested' | 'awaiting_handoff' | 'awaiting_settlement' | 'ready' | 'closing' | 'closed' | 'failed' | 'timed_out' | 'interrupted' | 'uncertain';
+export interface Handoff { version: 1; summary: string; updatedAt: string; jobId: string }
+export interface CloseJob { jobId: string; state: CloseState; createdAt: string; updatedAt: string; deadlineAt: string; reason?: CloseReason }
+export type HandoffKind = 'close_prepare' | 'close_identity' | 'close_request' | 'handoff_report' | 'close_ready' | 'close_commit';
+export const HANDOFF_KINDS: readonly string[] = ['close_prepare', 'close_identity', 'close_request', 'handoff_report', 'close_ready', 'close_commit'];
+const states: CloseState[] = ['requested', 'awaiting_handoff', 'awaiting_settlement', 'ready', 'closing', 'closed', 'failed', 'timed_out', 'interrupted', 'uncertain'];
+const reasons: CloseReason[] = ['timeout', 'interrupted', 'delivery_failed', 'identity_failed', 'save_failed', 'worker_changed', 'worker_busy', 'commit_rejected', 'close_unverified', 'close_failed'];
+export const pendingClose = (job?: CloseJob) => !!job && ['requested', 'awaiting_handoff', 'awaiting_settlement', 'ready', 'closing'].includes(job.state);
+export const fencedClose = (job?: CloseJob) => pendingClose(job) || job?.state === 'uncertain';
+function requireValue(ok: unknown): asserts ok { if (!ok) throw new Error('PiIntercom: invalid handoff protocol/state'); }
+const string = (value: unknown, max: number) => typeof value === 'string' && !!value.trim() && value.length <= max && !value.includes('\0');
+const token = (value: unknown) => typeof value === 'string' && /^[a-zA-Z0-9-]{1,128}$/.test(value);
+const timestamp = (value: unknown) => typeof value === 'string' && value.length <= 32 && Number.isFinite(Date.parse(value));
+export function validateIdentity(value: unknown): asserts value is WorkerPaneIdentity {
+  const v = value as WorkerPaneIdentity;
+  requireValue(v && ['workspaceId', 'paneId', 'terminalId', 'sessionId', 'processStart'].every(k => string(v[k as keyof WorkerPaneIdentity], 256)) && string(v.sessionFile, 4096) && Number.isSafeInteger(v.pid) && v.pid > 0);
+}
+export function validateHandoff(value: unknown): asserts value is Handoff {
+  const v = value as Handoff;
+  requireValue(v && v.version === 1 && token(v.jobId) && string(v.summary, 4000) && timestamp(v.updatedAt));
+  requireValue(Object.keys(v).every(k => ['version', 'jobId', 'summary', 'updatedAt'].includes(k)));
+}
+export function validateCloseJob(value: unknown): asserts value is CloseJob {
+  const v = value as CloseJob;
+  requireValue(v && token(v.jobId) && states.includes(v.state) && timestamp(v.createdAt) && timestamp(v.updatedAt) && timestamp(v.deadlineAt) && (v.reason === undefined || reasons.includes(v.reason)));
+  requireValue(Object.keys(v).every(k => ['jobId', 'state', 'createdAt', 'updatedAt', 'deadlineAt', 'reason'].includes(k)));
+}
+export function validateHandoffPayload(kind: string, p: Record<string, unknown>): void {
+  requireValue(token(p.jobId));
+  const keys: Record<string, string[]> = {
+    close_prepare: ['jobId', 'deadlineAt'], close_identity: ['jobId', 'instanceId', 'identity'],
+    close_request: ['jobId', 'instanceId'], handoff_report: ['jobId', 'instanceId', 'summary'],
+    close_ready: ['jobId', 'instanceId', 'readyNonce'], close_commit: ['jobId', 'instanceId', 'readyNonce'],
+  };
+  requireValue(!!keys[kind] && Object.keys(p).every(k => keys[kind].includes(k)));
+  if (kind === 'close_prepare') requireValue(timestamp(p.deadlineAt));
+  else requireValue(token(p.instanceId));
+  if (kind === 'close_identity') validateIdentity(p.identity);
+  if (kind === 'handoff_report') requireValue(string(p.summary, 4000));
+  if (kind === 'close_ready' || kind === 'close_commit') requireValue(token(p.readyNonce));
+}
+interface Context {
+  state(): Promise<{ id: string; config: Config; me?: Agent }>;
+  assertCurrent(): void;
+  update(mutate: (config: Config) => void, guard?: () => void): Promise<void>;
+  send(sessionId: string, kind: HandoffKind, payload: Record<string, unknown>): Promise<void>;
+  deliver(message: string): void;
+  busy(): boolean;
+  provider?: CloseProvider;
+  timeoutMs?: number;
+}
+interface Pending {
+  target: Agent; job: CloseJob; timer: ReturnType<typeof setTimeout>;
+  identity?: WorkerPaneIdentity; instanceId?: string; initialized?: Promise<void>; processing: boolean; closing: boolean; ended: boolean;
+}
+interface WorkerPending {
+  jobId: string; coordinatorId: string; deadline: number; requested: boolean;
+  saved: boolean; reporting: boolean; invalidated: boolean; epoch: number;
+  readyNonce?: string; toolCallId?: string; committed: boolean; timer: ReturnType<typeof setTimeout>;
+}
+/** Extension-owned asynchronous protocol. No host abort, shutdown, automatic retries or guessed pane targets. */
+export class HandoffWorkflow {
+  private readonly instanceId = randomUUID();
+  private jobs = new Map<string, Pending>();
+  private worker?: WorkerPending;
+  private epoch = 0;
+  private disposed = false;
+  private readonly timeout: number;
+  constructor(private readonly ctx: Context) {
+    this.timeout = Number.isFinite(ctx.timeoutMs) ? Math.max(1, Math.min(120000, ctx.timeoutMs!)) : 120000;
+  }
+  private valid() { requireValue(!this.disposed); this.ctx.assertCurrent(); }
+  private background(work: () => Promise<void>) { setImmediate(() => { if (!this.disposed) void work().catch(() => {}); }); }
+  dispose(): void {
+    this.disposed = true;
+    for (const p of this.jobs.values()) { p.ended = true; clearTimeout(p.timer); }
+    this.jobs.clear();
+    if (this.worker) clearTimeout(this.worker.timer);
+    this.worker = undefined;
+  }
+  async recover(): Promise<void> {
+    const { me, config } = await this.ctx.state();
+    if (!me?.coordinator || !config.agents.some(a => pendingClose(a.closeJob))) return;
+    await this.ctx.update(c => {
+      for (const a of c.agents) if (pendingClose(a.closeJob)) {
+        a.closeJob = { ...a.closeJob!, state: a.closeJob!.state === 'closing' ? 'uncertain' : 'interrupted', reason: 'interrupted', updatedAt: new Date().toISOString() };
+      }
+    });
+  }
+  private assertJob(p: Pending) {
+    this.valid();
+    requireValue(!p.ended && this.jobs.get(p.target.sessionId) === p && Date.now() < Date.parse(p.job.deadlineAt));
+  }
+  private target(c: Config, p: Pending): Agent {
+    this.assertJob(p);
+    const a = c.agents.find(a => a.sessionId === p.target.sessionId && !a.coordinator);
+    requireValue(a && a.closeJob?.jobId === p.job.jobId && pendingClose(a.closeJob) && a.port === p.target.port && a.projectDirectory === p.target.projectDirectory);
+    return a;
+  }
+  private async transition(p: Pending, state: CloseState, reason?: CloseReason): Promise<void> {
+    await this.ctx.update(c => {
+      const a = this.target(c, p);
+      a.closeJob = { ...a.closeJob!, state, updatedAt: new Date().toISOString(), ...(reason ? { reason } : {}) };
+      p.job = { ...a.closeJob };
+    }, () => this.assertJob(p));
+  }
+  private async finish(p: Pending, state: CloseState, reason?: CloseReason): Promise<void> {
+    if (p.ended) return;
+    p.ended = true; clearTimeout(p.timer);
+    // Keep the in-memory fence if persistence fails. Reload recovers durable intent.
+    try {
+      this.valid();
+      await this.ctx.update(c => {
+        const a = c.agents.find(a => a.sessionId === p.target.sessionId && !a.coordinator);
+        requireValue(a?.closeJob?.jobId === p.job.jobId);
+        a.closeJob = { ...a.closeJob, state, updatedAt: new Date().toISOString(), ...(reason ? { reason } : {}) };
+      });
+      this.jobs.delete(p.target.sessionId);
+    } catch { /* Failure never authorizes pane closure or replay. */ }
+  }
+  async request(target: Agent): Promise<CloseJob> {
+    this.valid(); requireValue(this.ctx.provider);
+    const existing = this.jobs.get(target.sessionId);
+    if (existing) { await existing.initialized; return { ...existing.job }; }
+    requireValue(!fencedClose(target.closeJob) && this.jobs.size < 16);
+    const now = Date.now();
+    const job: CloseJob = { jobId: randomUUID(), state: 'requested', createdAt: new Date(now).toISOString(), updatedAt: new Date(now).toISOString(), deadlineAt: new Date(now + this.timeout).toISOString() };
+    const p: Pending = { target: { ...target }, job, timer: undefined as unknown as ReturnType<typeof setTimeout>, processing: false, closing: false, ended: false };
+    // Install the fence synchronously, before the first asynchronous config write.
+    this.jobs.set(target.sessionId, p);
+    try {
+      p.initialized = this.ctx.update(c => {
+        const a = c.agents.find(a => a.sessionId === target.sessionId && !a.coordinator);
+        requireValue(a && !fencedClose(a.closeJob) && a.port === target.port && a.projectDirectory === target.projectDirectory && c.multiplexer === 'herdr');
+        a.closeJob = { ...job };
+      }, () => this.assertJob(p));
+      await p.initialized;
+    } catch (error) { this.jobs.delete(target.sessionId); throw error; }
+    p.timer = setTimeout(() => { void this.finish(p, p.closing ? 'uncertain' : 'timed_out', 'timeout'); }, Math.max(0, Date.parse(job.deadlineAt) - Date.now()));
+    this.background(async () => {
+      try { this.assertJob(p); await this.ctx.send(target.sessionId, 'close_prepare', { jobId: job.jobId, deadlineAt: job.deadlineAt }); }
+      catch { await this.finish(p, 'failed', 'delivery_failed'); }
+    });
+    return { ...job };
+  }
+  workerStarted(): void {
+    this.epoch++;
+    const w = this.worker;
+    if (w && (w.saved || w.reporting)) { w.invalidated = true; w.readyNonce = undefined; }
+  }
+  workerSettled(successfulToolCallIds: ReadonlySet<string>): void {
+    const w = this.worker;
+    if (!w || !w.saved || w.reporting || w.invalidated || w.readyNonce || w.committed || this.ctx.busy() || w.epoch !== this.epoch || !w.toolCallId || !successfulToolCallIds.has(w.toolCallId)) return;
+    w.readyNonce = randomUUID();
+    this.background(async () => {
+      this.assertWorker(w);
+      requireValue(!this.ctx.busy() && w.epoch === this.epoch && !w.invalidated);
+      await this.ctx.send(w.coordinatorId, 'close_ready', { jobId: w.jobId, instanceId: this.instanceId, readyNonce: w.readyNonce });
+    });
+  }
+  private assertWorker(w: WorkerPending) {
+    this.valid(); requireValue(this.worker === w && Date.now() < w.deadline);
+  }
+  get workerClosing(): boolean { return !!this.worker; }
+  isClosing(sessionId: string): boolean { return this.jobs.has(sessionId); }
+  async report(jobId: unknown, summary: unknown, toolCallId?: string): Promise<{ saved: true; closure: 'awaiting_turn_settlement' }> {
+    requireValue(string(summary, 4000) && string(toolCallId, 256));
+    const w = this.worker; requireValue(w && w.jobId === jobId && w.requested && !w.reporting && !w.saved && !w.invalidated);
+    this.assertWorker(w); w.reporting = true; w.toolCallId = toolCallId;
+    const reportEpoch = this.epoch;
+    try {
+      await this.ctx.send(w.coordinatorId, 'handoff_report', { jobId: w.jobId, instanceId: this.instanceId, summary });
+      this.assertWorker(w); requireValue(!w.invalidated && this.epoch === reportEpoch);
+      w.saved = true; w.epoch = reportEpoch;
+      return { saved: true, closure: 'awaiting_turn_settlement' };
+    } finally { w.reporting = false; }
+  }
+  async receive(kind: HandoffKind, from: string, payload: Record<string, unknown>): Promise<void> {
+    validateHandoffPayload(kind, payload);
+    const { config, me } = await this.ctx.state(); this.valid();
+    const sender = config.agents.find(a => a.sessionId === from);
+    const coordinatorMessage = ['close_prepare', 'close_request', 'close_commit'].includes(kind);
+    requireValue(me && sender && (coordinatorMessage ? sender.coordinator && !me.coordinator : me.coordinator && !sender.coordinator));
+    if (coordinatorMessage) {
+      requireValue(this.ctx.provider && me.closeJob?.jobId === payload.jobId && pendingClose(me.closeJob));
+      if (kind === 'close_prepare') {
+        requireValue(!this.worker);
+        const deadline = Date.parse(payload.deadlineAt as string);
+        requireValue(deadline > Date.now() && deadline <= Date.now() + 120000);
+        const w: WorkerPending = { jobId: payload.jobId as string, coordinatorId: from, deadline, requested: false, saved: false, reporting: false, invalidated: false, epoch: this.epoch, committed: false, timer: undefined as unknown as ReturnType<typeof setTimeout> };
+        this.worker = w;
+        w.timer = setTimeout(() => { if (this.worker === w) this.worker = undefined; }, deadline - Date.now());
+        this.background(async () => {
+          try {
+            const identity = await this.ctx.provider!.getIdentity(); validateIdentity(identity);
+            this.assertWorker(w); requireValue(identity.sessionId === me.sessionId);
+            await this.ctx.send(from, 'close_identity', { jobId: w.jobId, instanceId: this.instanceId, identity });
+          } catch { if (this.worker === w) { clearTimeout(w.timer); this.worker = undefined; } }
+        });
+        return;
+      }
+      const w = this.worker;
+      requireValue(w && w.jobId === payload.jobId && payload.instanceId === this.instanceId && from === w.coordinatorId);
+      this.assertWorker(w);
+      if (kind === 'close_request') {
+        requireValue(!w.requested); w.requested = true;
+        this.ctx.deliver(`Coordinator requests a handoff for owned-pane closure. Job ID: ${w.jobId}. Stop taking new assignments, summarize completed work, remaining work, validation and important files in intercom_report_handoff({jobId:"${w.jobId}",summary:...}) (public summary, max 4000 characters; no credentials or private reasoning), then finish this turn and wait. Do not exit, shut down, close a pane or start further work. Pane closure is asynchronous and is not proof all child processes terminated.`);
+        return;
+      }
+      requireValue(w.saved && !w.reporting && !w.invalidated && !w.committed && !this.ctx.busy() && w.epoch === this.epoch && w.readyNonce === payload.readyNonce);
+      w.committed = true; return;
+    }
+    const p = this.jobs.get(from); requireValue(p && p.job.jobId === payload.jobId);
+    this.assertJob(p);
+    if (kind === 'close_identity') {
+      requireValue(!p.identity && !p.processing && p.job.state === 'requested');
+      const identity = payload.identity as WorkerPaneIdentity;
+      requireValue(identity.sessionId === from);
+      p.identity = { ...identity }; p.instanceId = payload.instanceId as string; p.processing = true;
+      this.background(async () => {
+        try {
+          await this.ctx.provider!.inspect(p.identity!, from, () => this.assertJob(p));
+          this.assertJob(p);
+          await this.transition(p, 'awaiting_handoff');
+          await this.ctx.send(from, 'close_request', { jobId: p.job.jobId, instanceId: p.instanceId });
+        } catch { await this.finish(p, 'failed', 'identity_failed'); }
+        finally { p.processing = false; }
+      });
+      return;
+    }
+    requireValue(payload.instanceId === p.instanceId);
+    if (kind === 'handoff_report') {
+      requireValue(p.job.state === 'awaiting_handoff' || p.job.state === 'awaiting_settlement');
+      try {
+        await this.ctx.update(c => {
+          const a = this.target(c, p);
+          if (a.handoff?.jobId === p.job.jobId) requireValue(a.handoff.summary === payload.summary);
+          else a.handoff = { version: 1, jobId: p.job.jobId, summary: payload.summary as string, updatedAt: new Date().toISOString() };
+          a.closeJob = { ...a.closeJob!, state: 'awaiting_settlement', updatedAt: new Date().toISOString() };
+        }, () => this.assertJob(p));
+        this.assertJob(p); p.job = { ...p.job, state: 'awaiting_settlement' };
+      } catch (error) { await this.finish(p, 'failed', 'save_failed'); throw error; }
+      return;
+    }
+    requireValue(kind === 'close_ready' && p.job.state === 'awaiting_settlement' && !p.closing && !p.processing);
+    p.processing = true;
+    this.background(async () => {
+      let failure: CloseReason = 'identity_failed';
+      try {
+        await this.transition(p, 'ready');
+        await this.ctx.provider!.inspect(p.identity!, from, () => this.assertJob(p));
+        this.assertJob(p);
+        failure = 'save_failed'; await this.transition(p, 'closing');
+        this.assertJob(p); failure = 'close_failed';
+        let commitAttempted = false;
+        const result = await this.ctx.provider!.close(p.identity!, from, () => this.assertJob(p), async () => {
+          this.assertJob(p); requireValue(!commitAttempted); commitAttempted = true;
+          failure = 'commit_rejected';
+          await this.ctx.send(from, 'close_commit', { jobId: p.job.jobId, instanceId: p.instanceId, readyNonce: payload.readyNonce });
+          this.assertJob(p); p.closing = true; failure = 'close_failed';
+        });
+        this.assertJob(p); requireValue(p.closing);
+        await this.finish(p, result.paneClosed && result.workerExited ? 'closed' : 'uncertain', result.paneClosed && result.workerExited ? undefined : 'close_unverified');
+      } catch { await this.finish(p, p.closing ? 'uncertain' : 'failed', failure); }
+    });
+  }
+}

package/src/index.ts

@@ -7,6 +7,7 @@ import { Intercom, UNSUPPORTED_CANCELLATION } from './runtime.js';
 import { launchers } from './launcher.js';
 import { ensureMonitorPane } from './monitor-launcher.js';
 import { createActivityTracker } from './activity.js';
+import { createCloseProvider } from './pane-close.js';
 
 const to = Type.Object({ to: Type.String({ minLength: 1, maxLength: 128 }) });
 const tools: [string, string, TSchema][] = [
@@ -20,9 +21,10 @@ const tools: [string, string, TSchema][] = [
   ['report_work', 'Configured, responsibility-loaded workers only. Store one public report (blocked, needs_decision, ready_for_review) and notify the coordinator; clear retires it. Summary required except clear (omit or empty). Never include private reasoning, credentials, raw tool payloads, or secrets. Receipt is not approval, verified completion, or permission for follow-up work.', Type.Object({ status: Type.String({ enum: ['blocked', 'needs_decision', 'ready_for_review', 'clear'] }), summary: Type.Optional(Type.String({ maxLength: 2000 })) })],
   ['report_status', 'Worker only (including anonymous). Send runtime sessionId/port/busy report to coordinator. This is NOT registration and creates no config entry.', Type.Object({})],
   ['stop_worker', UNSUPPORTED_CANCELLATION, to],
-  ['close_worker', UNSUPPORTED_CANCELLATION, to],
+  ['close_worker', 'Coordinator only. Begin a background save-handoff-and-close job for a configured worker in Linux Herdr. Requests a public summary, saves it in config, waits for successful tool persistence and final turn settlement, then attempts one verified pane close. Returns job acceptance, not completion. Registration/session history are retained. Check worker_status/list for closeJob; failure/timeout/uncertainty never authorizes retry. Not graceful abort or an all-descendants termination guarantee; Windows/non-Herdr unsupported.', to],
+  ['report_handoff', 'Configured worker only, in response to its pending close request. Submit the matching jobId and concise public resume handoff (current work, completed work, unfinished items, blockers, next step). Never include secrets, private reasoning or raw tool payloads. Saved receipt is not closure: finish the response and wait; the extension requires final turn settlement before pane closure.', Type.Object({ jobId: Type.String({ minLength: 1, maxLength: 128 }), summary: Type.String({ minLength: 1, maxLength: 4000 }) })],
   ['resume_worker', 'Coordinator only. Resume saved session/name/responsibility after the user explicitly confirms the old session was closed: set confirmClosed:true only for that confirmation, never infer it from disconnected status. A matching live health endpoint blocks launch. In-flight/uncertain attempts are fenced until worker status arrives; otherwise inspect process and reload coordinator before considering retry. No cross-process uniqueness guarantee, automatic assignment, replacement or removal.', Type.Object({ to: Type.String({ minLength: 1, maxLength: 128 }), confirmClosed: Type.Boolean() })],
-  ['remove_worker', 'Coordinator only. Remove config entry only; never stop process or delete session files. A running worker must be explicitly closed before removal. Stop/close are disabled on current host: arrange explicit user closure first.', to],
+  ['remove_worker', 'Coordinator only. Remove config entry only; never stop process or delete session files. A running worker must be explicitly closed before removal. Retain registration to resume it later; remove only to forget it. Pending or uncertain close jobs block removal.', to],
   ['set_multiplexer', 'Coordinator only. Set herdr (default, Windows/Linux) or none (separate visible Windows terminals; unsupported on Linux) for future launches. Never move/restart existing workers or fall back.', Type.Object({ multiplexer: Type.String({ enum: ['herdr', 'none'] }) })],
 ];
 
@@ -55,6 +57,35 @@ export default function intercomExtension(pi: ExtensionAPI): void {
     extension: fileURLToPath(import.meta.url),
     sessionExists: async (cwd, id) => (await SessionManager.list(cwd, resumeSessionDirectory(cwd))).some(s => s.id === id),
   });
+  let monitorTask: { runtime: Intercom; generation: number; dirty: boolean; promise: Promise<void> } | undefined;
+  async function ensureCoordinatorMonitor(current: Intercom, ctx: ExtensionContext, started: number): Promise<void> {
+    const isCurrent = () => started === generation && runtime === current;
+    if (!isCurrent()) return;
+    if (monitorTask?.runtime === current && monitorTask.generation === started) {
+      monitorTask.dirty = true;
+      return monitorTask.promise;
+    }
+    const check = async () => {
+      try {
+        const { config, me, id } = await current.state();
+        if (!isCurrent() || !me?.coordinator || !config.agents.some(agent => !agent.coordinator)) return;
+        const monitor = await ensureMonitorPane({
+          root: current.store.root, sessionId: id,
+          script: fileURLToPath(new URL('../dist/monitor.js', import.meta.url)),
+          assertCurrent: () => { if (!isCurrent()) throw new Error('Coordinator session changed'); },
+        });
+        if (isCurrent()) ctx.ui.notify(`Intercom status monitor: ${monitor.outcome}${monitor.pane ? ` (${monitor.pane})` : ''}`, 'info');
+      } catch (error) {
+        if (isCurrent()) ctx.ui.notify(String(error), 'warning');
+      }
+    };
+    const task = { runtime: current, generation: started, dirty: false, promise: Promise.resolve() };
+    monitorTask = task;
+    task.promise = (async () => {
+      do { task.dirty = false; await check(); } while (task.dirty && isCurrent());
+    })();
+    try { await task.promise; } finally { if (monitorTask === task) monitorTask = undefined; }
+  }
   pi.on('session_start', async (_event, ctx) => {
     const started = ++generation;
     activity.reset();
@@ -74,7 +105,13 @@ export default function intercomExtension(pi: ExtensionAPI): void {
       deliver: content => pi.sendUserMessage(content, { deliverAs: 'steer' }),
       setName: async name => { if (pi.getSessionName() !== name) pi.setSessionName(name); await launcher.syncName(name); },
       notify: text => ctx.ui.notify(text, 'info'),
-    }, { launch: launcher.launch, store: root => new PiConfigStore(root) });
+    }, {
+      launch: launcher.launch, store: root => new PiConfigStore(root),
+      closeProvider: createCloseProvider({
+        sessionId: () => context!.sessionManager.getSessionId(),
+        sessionFile: () => context!.sessionManager.getSessionFile(),
+      }),
+    });
     const current = runtime;
     try { await current.start(); }
     catch (e) { if (runtime === current) runtime = undefined; ctx.ui.notify(String(e), 'error'); return; }
@@ -87,13 +124,7 @@ export default function intercomExtension(pi: ExtensionAPI): void {
           ctx.ui.notify(`Legacy dashboard metadata cleanup failed; messaging remains available: ${String(error)}`, 'warning');
         }
         if (started !== generation) return;
-        const monitor = await ensureMonitorPane({
-          root: current.store.root, sessionId: ctx.sessionManager.getSessionId(),
-          script: fileURLToPath(new URL('../dist/monitor.js', import.meta.url)),
-          assertCurrent: () => { if (started !== generation || runtime !== current) throw new Error('Coordinator session changed'); },
-        });
-        if (started !== generation) return;
-        ctx.ui.notify(`Intercom status monitor: ${monitor.outcome}${monitor.pane ? ` (${monitor.pane})` : ''}`, 'info');
+        await ensureCoordinatorMonitor(current, ctx, started);
       }
     } catch (error) {
       if (started !== generation) return;
@@ -107,8 +138,13 @@ export default function intercomExtension(pi: ExtensionAPI): void {
     runtime = undefined; context = undefined;
     await oldRuntime?.close();
   });
+  pi.on('input', (_event, ctx) => {
+    context = ctx;
+    runtime?.workerStarted(); // New owner input invalidates a pending close-readiness epoch.
+  });
   pi.on('agent_start', async (_event, ctx) => {
     context = ctx;
+    runtime?.workerStarted();
     activityOutcome = 'started';
     try { activity.start(); } finally { activityOutcome = 'snapshot'; }
   });
@@ -116,6 +152,15 @@ export default function intercomExtension(pi: ExtensionAPI): void {
     context = ctx;
     activityOutcome = 'settled';
     try { activity.settled(); } finally { activityOutcome = 'snapshot'; }
+    // Settlement is notification-only and follows tool-result persistence. Inspect
+    // only entry kinds and successful tool call IDs, never message/reasoning bodies.
+    const successful = new Set<string>();
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === 'message' && entry.message.role === 'toolResult' && !entry.message.isError) {
+        successful.add(entry.message.toolCallId);
+      }
+    }
+    runtime?.workerSettled(successful);
   });
   pi.on('message_update', (event, ctx) => {
     context = ctx;
@@ -135,7 +180,7 @@ export default function intercomExtension(pi: ExtensionAPI): void {
     if (!runtime) return;
     const { me } = await runtime.state();
     const loaded = runtime.responsibility;
-    return { systemPrompt: event.systemPrompt + '\n\nPiIntercom: communicates; Pi decides orchestration. Responsibility is not a work assignment. Do not implement unrelated work from findings. After assigned work, report as instructed and wait; do not autonomously exit. Progress questions require reporting and continuing unless explicitly redirected. stop_worker/close_worker are disabled due to host cancellation blocker.\n' + (me && loaded ? `Identity: ${loaded.name} (${me.sessionId}). Responsibility: ${loaded.description}.` : 'Anonymous/unloaded worker: wait for coordinator configuration and separate reload; do not treat registration as authorization to work.') };
+    return { systemPrompt: event.systemPrompt + '\n\nPiIntercom: communicates; Pi decides orchestration. Responsibility is not a work assignment. Do not implement unrelated work from findings. After assigned work, report as instructed and wait; do not autonomously exit. Progress questions require reporting and continuing unless explicitly redirected. stop_worker remains disabled due to the host cancellation blocker. close_worker is a separate Linux Herdr background handoff-and-pane-close workflow: do not self-exit, remove registration, force kill or infer completion from job acceptance.\n' + (me && loaded ? `Identity: ${loaded.name} (${me.sessionId}). Responsibility: ${loaded.description}.` : 'Anonymous/unloaded worker: wait for coordinator configuration and separate reload; do not treat registration as authorization to work.') };
   });
   for (const [operation, description, parameters] of tools) {
     pi.registerTool({
@@ -143,9 +188,11 @@ export default function intercomExtension(pi: ExtensionAPI): void {
       async execute(_id, args, signal, _update, ctx) {
         signal?.throwIfAborted(); context = ctx;
         if (!runtime) throw new Error('PiIntercom not initialized; inspect startup error.');
-        const result = await runtime.tool(operation, args as Record<string, unknown>);
+        const current = runtime, started = generation;
+        const result = await current.tool(operation, args as Record<string, unknown>, _id);
+        if (operation === 'configure_worker') await ensureCoordinatorMonitor(current, ctx, started);
         const output = truncateHead(JSON.stringify(result, null, 2));
-        return { content: [{ type: 'text', text: output.content + (output.truncated ? `\n[Truncated; full shared configuration: ${runtime.store.file}]` : '') }], details: {} };
+        return { content: [{ type: 'text', text: output.content + (output.truncated ? `\n[Truncated; full shared configuration: ${current.store.file}]` : '') }], details: {} };
       },
     });
   }

package/src/monitor-view.ts

@@ -1,6 +1,6 @@
 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';
@@ -74,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)));
@@ -94,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 ? [

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 };
+    },
+  };
+}