@comput/pi-intercom 0.5.1 → 0.6.1

package/references/observability.md

@@ -4,7 +4,7 @@ Intercom's terminal monitor is a standalone Node/pi-tui process above the coordi
 
 ## Terminal-first monitoring
 
-Coordinator startup checks its saved monitor ownership and either preserves the existing pane or creates one above the coordinator. Workers do not create monitors. The pane is named `Intercom monitor`; its generic label alone is not proof of ownership. Machine-local `monitor-*.json` files record the coordinator/workspace/pane identities and partial-launch state. Uncertain operations are fenced rather than blindly repeated.
+Coordinator startup checks its saved monitor ownership only when the roster contains a worker, and either preserves the existing pane or creates one above the coordinator. An empty roster skips monitor setup; configuring the first worker triggers setup, and retained disconnected workers count. Existing monitor panes are not automatically closed when the roster becomes empty. Worker sessions do not create monitors. Coordinator Pi/Herdr names are preserved rather than overwritten with the internal Coordinator role. The pane is named `Intercom monitor`; its generic label alone is not proof of ownership. Machine-local `monitor-*.json` files record the coordinator/workspace/pane identities and partial-launch state. Uncertain operations are fenced rather than blindly repeated.
 
 The monitor refreshes from disk and performs bounded loopback identity checks, then schedules the next pass approximately three seconds after completion. It never launches model turns or resends messages. Probes do not write config or observation logs; cancelling the monitor aborts in-flight probes. Arrow keys select a worker; Enter toggles its details; Escape closes details before quitting, while q/Ctrl+C always quit the monitor only. Selection follows the worker's session ID across roster reorder. Details show configured responsibility, observations and explicit public worker reports, not inferred task state or approval controls.
 
@@ -58,7 +58,17 @@ Activity phases are `working`, `thinking`, `responding`, `tool`, `idle`. Details
 
 Checks expire to unknown after 30 seconds. Monitor batches rotate to avoid starvation; skipped checks may retain previous unexpired evidence. Saved-port changes/removal invalidate cached checks. Shared classification/sorting preserves config order within connected-or-unknown and disconnected groups. UI selection follows session ID across these order changes.
 
-Closing a worker does not remove config. Explicit resume uses the saved session ID, name and responsibility and requires user-confirmed closure (`confirmClosed:true`). A live matching health endpoint rejects duplicate resume. In-flight/uncertain submissions are fenced within this coordinator runtime until a later configured status announcement; preflight announcements do not qualify, and uncertain launch errors preserve the fence. Config/identity/lifecycle are rechecked before launch. These safeguards do not guarantee cross-process uniqueness, survive coordinator restart or certify OS process death. No automatic close, retry, restart or work assignment occurs.
+Closing a worker does not remove config. Explicit resume uses the saved session ID, name and responsibility and requires user-confirmed closure (`confirmClosed:true`). A live matching health endpoint rejects duplicate resume. In-flight/uncertain submissions are fenced within this coordinator runtime until a later configured status announcement; preflight announcements do not qualify, and uncertain launch errors preserve the fence. Config/identity/lifecycle are rechecked before launch. These safeguards do not guarantee cross-process uniqueness, survive coordinator restart or certify OS process death. Connectivity monitoring never automatically closes, retries, restarts or assigns work. An explicit close request (0.6.1) may separately initiate the handoff workflow described below.
+
+## Public handoff and background pane-close jobs (0.6.1)
+
+`Agent.handoff` saves only `{version, jobId, summary, updatedAt}`; the summary is explicitly public worker-authored context, at most 4000 characters. `Agent.closeJob` stores bounded workflow ID/state/timestamps and a fixed reason. Both remain alongside registration after a close. No PID, private session path, terminal ID or readiness nonce is saved in these public config fields. Config validation rejects extra metadata fields; snapshot/status views explicitly project supported fields. Old saved handoffs may precede a newer failed close job; they are not merged or treated as current acceptance.
+
+Explicit `close_worker` returns acceptance while the coordinator extension continues in the background. It requests a correlated handoff, awaits atomic config-save acknowledgment, then requires a successful exact report tool-result ID in the current branch plus final `agent_settled`. The adapter reads only tool-result metadata (role, toolCallId, isError), never arguments, results or reasoning content. New input/agent starts invalidate readiness. No model polling on the coordinator is required.
+
+Closing intent is durable before mutation. After final Linux Herdr pane/session/PID/start-identity checks, a nonce-bound worker commit is checked immediately before one pane-close command. No summary alone, timeout, save failure or busy/stale worker permits a close. Job deadlines are checked again at config publication and before pane mutation. Failed/uncertain outcomes preserve registration/handoff. Interrupted jobs are not replayed after reload; closing intent recovers as uncertain.
+
+The monitor and JSON status expose public handoff age and close workflow separately from connectivity/activity/reports. `closed` means this workflow verified pane absence and original worker-process exit; it does not certify all descendants terminated. The workflow is available in npm 0.6.1 for Linux Herdr only. See README for retained race/flush limits and operator recovery requirements.
 
 ## Read-only JSON status
 
@@ -81,7 +91,7 @@ Readers consider only configured workers, at most 256 IDs and 8 KiB per file. Un
 - `agent_settled` supplies the idle boundary, not `agent_end`. Activity observations are not availability guarantees or assignment states.
 - `status.received` describes the reporting peer, not the event writer's own activity. It is not used as the writer's status.
 - Launch submission does not establish readiness. A correlation ID is not deduplication or a reply promise.
-- Stop/close remain disabled. Monitoring adds no cancellation, recovery, retries, commit or rollback.
+- Graceful stop remains disabled. The explicit handoff-and-pane-close workflow is separate from monitoring; monitoring adds no cancellation, recovery, retries, commit or rollback.
 
 ## Storage bounds and failure behavior
 

package/src/config.ts

@@ -1,6 +1,7 @@
 import { mkdir, readFile, realpath, rename, unlink, open, link, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { fencedClose, validateHandoff, validateCloseJob, type Handoff, type CloseJob } from './handoff.js';
 
 export interface Agent {
   sessionId: string;
@@ -11,6 +12,8 @@ export interface Agent {
   /** Legacy browser dashboard field, accepted for migration only; removed at coordinator startup. */
   dashboardPort?: number;
   projectDirectory: string;
+  handoff?: Handoff;
+  closeJob?: CloseJob;
 }
 export interface Config { version: 1; multiplexer: 'herdr' | 'none'; agents: Agent[] }
 export const DEFAULT_DESCRIPTION = 'Coordinate workers, delegate work, and manage shared configuration.';
@@ -35,6 +38,8 @@ export function validateConfig(value: unknown): Config {
     text(a.sessionId, 'sessionId', 256); text(a.name, 'name', 128); text(a.description, 'description');
     if (a.name !== a.name.trim() || /[\r\n\x00-\x1f]/.test(a.name)) fail('invalid name');
     port(a.port); relativeDirectory(a.projectDirectory);
+    if (a.handoff !== undefined) { if (a.coordinator) fail('handoff is worker-only'); validateHandoff(a.handoff); }
+    if (a.closeJob !== undefined) { if (a.coordinator) fail('closeJob is worker-only'); validateCloseJob(a.closeJob); }
     if (a.dashboardPort !== undefined) {
       if (!a.coordinator) fail('dashboardPort is coordinator-only');
       port(a.dashboardPort);
@@ -63,10 +68,19 @@ export async function directory(root: string, requested: string): Promise<string
   if (!(await stat(target)).isDirectory()) fail('projectDirectory is not a directory');
   return rel.split(path.sep).join('/') || '.';
 }
+export interface ConfigStoreOptions {
+  /** Publication seams for deterministic platform/race tests. */
+  platform?: NodeJS.Platform;
+  rename?: (from: string, to: string) => Promise<void>;
+  delay?: (milliseconds: number) => Promise<void>;
+  now?: () => number;
+}
+const RENAME_DELAYS = [10, 20, 40, 80] as const;
+const RENAME_BUDGET_MS = 250;
 export class ConfigStore {
   readonly file: string;
   private tail: Promise<unknown> = Promise.resolve();
-  constructor(readonly root: string) { this.file = path.join(root, '.pi-intercom', 'config.json'); }
+  constructor(readonly root: string, private readonly options: ConfigStoreOptions = {}) { this.file = path.join(root, '.pi-intercom', 'config.json'); }
   async read(): Promise<Config> {
     // Missing, malformed and unreadable files propagate; never overwrite them.
     return validateConfig(JSON.parse(await readFile(this.file, 'utf8')));
@@ -113,6 +127,29 @@ export class ConfigStore {
       await unlink(temp); return true;
     } catch (error) { await unlink(temp).catch(() => {}); throw error; }
   }
+  private async publish(temp: string, assertValid: () => void): Promise<void> {
+    const replace = this.options.rename ?? rename;
+    const now = this.options.now ?? (() => performance.now());
+    const delay = this.options.delay ?? (milliseconds => new Promise<void>(resolve => setTimeout(resolve, milliseconds)));
+    const started = now();
+    let originalError: unknown;
+    for (let attempt = 0; ; attempt++) {
+      // Windows readers can briefly deny replace-rename. Retry only publication
+      // of this already synced/closed temp, never the mutation or any OS action
+      // outside config persistence. The elapsed budget bounds retry initiation,
+      // not the duration of an already-submitted OS rename.
+      assertValid();
+      if (attempt > 0 && now() - started >= RENAME_BUDGET_MS) throw originalError;
+      try { await replace(temp, this.file); return; }
+      catch (error) {
+        if ((this.options.platform ?? process.platform) !== 'win32' || (error as NodeJS.ErrnoException).code !== 'EPERM') throw error;
+        originalError ??= error;
+        const backoff = RENAME_DELAYS[attempt];
+        if (backoff === undefined || now() - started + backoff >= RENAME_BUDGET_MS) throw originalError;
+        await delay(backoff);
+      }
+    }
+  }
   async update(id: string, mutate: (config: Config) => void | Promise<void>, assertValid: () => void = () => {}): Promise<Config> {
     const operation = this.tail.then(async () => {
       assertValid();
@@ -120,8 +157,9 @@ export class ConfigStore {
       await mutate(c); assertValid(); validateConfig(c);
       const temp = await this.temporary(c);
       try {
-        // Last check before publication; an already submitted OS rename cannot be undone.
-        assertValid(); await rename(temp, this.file);
+        // Every publication attempt checks the lifecycle/deadline guard; an
+        // already submitted OS rename still cannot be undone.
+        await this.publish(temp, assertValid);
       } catch (error) { await unlink(temp).catch(() => {}); throw error; }
       return c;
     });
@@ -133,7 +171,14 @@ export class ConfigStore {
       const projectDirectory = await directory(this.root, values.projectDirectory);
       const a: Agent = { sessionId: values.sessionId, name: values.name, description: values.description, port: values.port, projectDirectory, coordinator: false };
       const index = c.agents.findIndex(old => old.sessionId === a.sessionId);
-      if (index < 0) c.agents.push(a); else c.agents[index] = a;
+      if (index < 0) c.agents.push(a);
+      else {
+        const old = c.agents[index];
+        if (fencedClose(old.closeJob)) fail('worker close is active or uncertain; configuration is fenced');
+        if (old.handoff) a.handoff = old.handoff;
+        if (old.closeJob) a.closeJob = old.closeJob;
+        c.agents[index] = a;
+      }
     }, assertValid);
   }
 }

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: {} };
       },
     });
   }