@comput/pi-intercom 0.5.2 → 0.8.1

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/reminders.ts

@@ -0,0 +1,69 @@
+export const REMINDER_INTERVAL_MS = 5 * 60 * 1000;
+export const REMINDER_TEXT = 'Intercom reminder: Review outstanding delegated work and worker reports. If follow-up is needed, take the next appropriate action. Do not assume workers have finished or stopped.\n\nIf there is genuinely nothing to follow up on, call intercom_stop_reminders. Otherwise, reminders continue every five minutes; a new worker call resets the timer.\n\nThis reminder does not authorize new work, retries, worker closure, or publication.';
+
+export interface ReminderClock {
+  schedule(callback: () => void, milliseconds: number): () => void;
+}
+const clock: ReminderClock = {
+  schedule(callback, milliseconds) {
+    const timer = setTimeout(callback, milliseconds);
+    timer.unref();
+    return () => clearTimeout(timer);
+  },
+};
+interface ReminderHost {
+  isCoordinator(): Promise<boolean>;
+  busy(): boolean;
+  deliver(text: string): void;
+}
+/** Ephemeral reminder only: never worker actions, network retries or a backlog. */
+export class CoordinatorReminders {
+  private generation = 0;
+  private tick = 0;
+  private checking = false;
+  private disposed = false;
+  private cancel?: () => void;
+  private detachOwner?: () => void;
+  constructor(private readonly host: ReminderHost, private readonly timer: ReminderClock = clock) {}
+  arm(signal?: AbortSignal): void {
+    if (this.disposed || signal?.aborted) return;
+    this.stop();
+    const generation = this.generation;
+    if (signal) {
+      const abort = () => { if (this.generation === generation) this.stop(); };
+      signal.addEventListener('abort', abort, { once: true });
+      this.detachOwner = () => signal.removeEventListener('abort', abort);
+    }
+    this.schedule(generation);
+  }
+  stop(): void {
+    this.generation++; this.tick++;
+    this.cancel?.(); this.cancel = undefined;
+    this.detachOwner?.(); this.detachOwner = undefined;
+  }
+  dispose(): void { this.stop(); this.disposed = true; }
+  private current(generation: number, tick: number): boolean {
+    return !this.disposed && this.generation === generation && this.tick === tick;
+  }
+  private schedule(generation: number): void {
+    this.cancel = this.timer.schedule(() => {
+      if (this.disposed || generation !== this.generation) return;
+      this.cancel = undefined;
+      const tick = ++this.tick;
+      this.schedule(generation);
+      // A slow role read never creates concurrent reads or a queued reminder.
+      // Advancing tick also invalidates any read from the preceding interval.
+      if (this.checking) return;
+      this.checking = true;
+      void (async () => {
+        try {
+          const coordinator = await this.host.isCoordinator();
+          if (!this.current(generation, tick)) return;
+          if (!coordinator) { this.stop(); return; }
+          if (!this.host.busy()) this.host.deliver(REMINDER_TEXT);
+        } catch { /* Unknown role/read/delivery outcome: no blind immediate replay. */ }
+        finally { this.checking = false; }
+      })();
+    }, REMINDER_INTERVAL_MS);
+  }
+}

package/src/runtime.ts

@@ -1,14 +1,17 @@
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
 import { LocalObserver, LOG_LIMITS, observationError, type Observer, type EventType, type EventMetadata } from './observability.js';
-import { ConfigStore, coordinator, directory, fail, named, port, requireCoordinator, type Agent, type Config } from './config.js';
+import { ConfigStore, coordinator, directory, fail, named, port, requireCoordinator, text, validateConfig, type Agent, type Config } from './config.js';
 import { listen, send, reportPayload, type Endpoint, type Envelope, type Kind } from './transport.js';
 import { saveWorkerReport } from './reports.js';
 import { readObservationSnapshot } from './snapshot.js';
 import { workerStatusPage } from './worker-status.js';
 import { probeWorker, probeWorkers } from './connections.js';
+import { HandoffWorkflow, HANDOFF_KINDS, fencedClose, type CloseProvider, type HandoffKind } from './handoff.js';
+import { CoordinatorReminders, type ReminderClock } from './reminders.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;
@@ -17,7 +20,7 @@ export interface Host {
   setName(name: string): Promise<void>;
   notify(text: string): void;
 }
-export interface LaunchRequest { multiplexer: 'herdr' | 'none'; cwd: string; sessionId?: string }
+export interface LaunchRequest { multiplexer: 'herdr' | 'none'; cwd: string; workspaceRoot: string; sessionId?: string }
 export interface RuntimeOptions {
   launch(request: LaunchRequest): Promise<unknown>;
   listen?: typeof listen;
@@ -25,6 +28,12 @@ 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;
+  reminderClock?: ReminderClock;
+  /** Explicit launcher-provided root must equal canonical cwd; no parent-root exception. */
+  workspaceRoot?: string;
 }
 export class Intercom {
   store!: ConfigStore;
@@ -32,6 +41,8 @@ export class Intercom {
   private active = false;
   private generation = 0;
   private initialId = '';
+  private configuredRoot?: string;
+  private configuredFile?: string;
   responsibility?: Agent;
   private observer?: Observer;
   private closing?: Promise<void>;
@@ -39,6 +50,12 @@ export class Intercom {
   private pendingReports = 0;
   private probeController = new AbortController();
   private resumeFences = new Map<string, { inFlight: boolean; submitted: boolean; announced: boolean }>();
+  private handoff?: HandoffWorkflow;
+  private reminders?: CoordinatorReminders;
+  private reminderRevision = 0;
+  private reminderInvocation = 0;
+  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 = {}) => {
@@ -50,6 +67,7 @@ export class Intercom {
   private id(): string {
     const id = this.host.sessionId();
     if (!this.active || id !== this.initialId) fail('session is inactive or replaced');
+    if (this.configuredRoot !== undefined && (this.store.root !== this.configuredRoot || this.store.file !== this.configuredFile)) fail('config store boundary changed');
     return id;
   }
   private validity(): () => void {
@@ -64,19 +82,27 @@ export class Intercom {
     if (this.closing) await this.closing;
     if (this.active) fail('runtime already active');
     this.initialId = this.host.sessionId(); this.active = true;
+    this.configuredRoot = undefined; this.configuredFile = undefined;
     this.probeController = new AbortController();
     this.resumeFences.clear();
     const generation = ++this.generation, assertValid = this.validity();
     let record = this.captureObserver();
     try {
-      const discovered = await ConfigStore.discover(this.host.cwd);
+      const discovered = this.options.workspaceRoot !== undefined
+        ? await ConfigStore.workspace(this.host.cwd, this.options.workspaceRoot)
+        : await ConfigStore.discover(this.host.cwd);
+      assertValid();
+      const root = discovered?.root ?? await realpath(this.host.cwd);
+      assertValid();
+      this.store = this.options.store?.(root) ?? discovered ?? new ConfigStore(root);
+      if (this.store.root !== root || this.store.file !== path.join(root, '.pi-intercom', 'config.json')) fail('config store must retain validated session root');
+      this.configuredRoot = root; this.configuredFile = this.store.file;
+      await this.store.validateRoot(root); assertValid();
+      const previous = discovered ? await this.store.read() : undefined;
       assertValid();
-      this.store = this.options.store?.(discovered?.root ?? this.host.cwd) ?? discovered ?? new ConfigStore(this.host.cwd);
       try { this.observer = this.options.observe ? this.options.observe(this.store.root, this.initialId) : new LocalObserver(this.store.root, this.initialId); } catch { /* Logging is optional on failure. */ }
       record = this.captureObserver();
       record('runtime.starting');
-      const previous = discovered ? await this.store.read() : undefined;
-      assertValid();
       const own = previous?.agents.find(a => a.sessionId === this.id());
       const endpoint = await (this.options.listen ?? listen)(own?.port, m => { assertValid(); return this.receive(m); }, () => {
         assertValid();
@@ -91,7 +117,28 @@ export class Intercom {
       const config = await this.store.read();
       assertValid();
       const me = config.agents.find(a => a.sessionId === this.id());
+      this.reminders = new CoordinatorReminders({
+        isCoordinator: async () => { const fresh = await this.state(); assertValid(); return fresh.me?.coordinator === true; },
+        busy: () => this.host.busy(),
+        deliver: message => { assertValid(); this.host.deliver(message, false); },
+      }, this.options.reminderClock);
+      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 +175,9 @@ export class Intercom {
     const observer = this.observer; this.observer = undefined;
     this.active = false; this.generation++;
     this.probeController.abort();
+    this.handoff?.dispose(); this.handoff = undefined;
+    this.reminderRevision = ++this.reminderInvocation;
+    this.reminders?.dispose(); this.reminders = undefined;
     const endpoint = this.endpoint; this.endpoint = undefined;
     this.responsibility = undefined;
     const closing = (async () => {
@@ -170,7 +220,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 +232,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 +284,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 +337,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 +360,17 @@ 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, reminderSignal?: AbortSignal): Promise<unknown> {
+    // Reserve invocation order before state/directory awaits, but only VALID
+    // reminder actions advance the accepted revision. Invalid/nonworker calls
+    // must not supersede a pending stop or suppress an older valid preflight.
+    const invocation = ++this.reminderInvocation;
+    const armReminder = () => {
+      if (invocation >= this.reminderRevision && !reminderSignal?.aborted) {
+        this.reminderRevision = invocation;
+        this.reminders?.arm(reminderSignal);
+      }
+    };
     const record = this.captureObserver();
     const assertValid = this.validity();
     const { id, config, me } = await this.state();
@@ -322,6 +392,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 +405,37 @@ 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);
+      text(args.message, 'message', 48000);
+      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');
+      if (me.coordinator && !recipient.coordinator) armReminder();
       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_reminders') {
+      const current = invocation >= this.reminderRevision;
+      if (current) { this.reminderRevision = invocation; this.reminders?.stop(); }
+      return { stopped: current };
+    }
+    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();
+      // Validate the candidate without writing, so invalid input never arms a
+      // reminder; persistence failures after valid initiation still do.
+      const relative = await directory(this.store.root, args.projectDirectory as string);
+      assertConfigurable();
+      const candidate: Agent = { sessionId: args.sessionId as string, name: args.name as string, description: args.description as string,
+        port: args.port as number, projectDirectory: relative, coordinator: false };
+      if (candidate.sessionId === id) fail('cannot configure coordinator as worker');
+      const previous = config.agents.find(a => a.sessionId === candidate.sessionId);
+      if (fencedClose(previous?.closeJob)) fail('worker close is active or uncertain; configuration is fenced');
+      validateConfig({ ...config, agents: [...config.agents.filter(a => a.sessionId !== candidate.sessionId), candidate] });
+      armReminder();
+      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 };
     }
@@ -347,34 +446,51 @@ export class Intercom {
     if (operation === 'create_worker') {
       const relative = await directory(this.store.root, (args.projectDirectory as string | undefined) ?? '.');
       assertValid();
-      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative) });
+      if (relative !== '.') fail('worker working directory must equal the config root; subdirectory launches would read a forbidden parent config');
+      armReminder();
+      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), workspaceRoot: this.store.root });
     }
     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');
+      if (fencedClose(target.closeJob) && !this.handoff.isClosing(target.sessionId)) fail('worker close is active or uncertain; close is fenced');
+      armReminder();
+      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') {
+      armReminder();
       await this.transmit(target.name, operation === 'reload_worker' ? 'reload' : 'request_status');
       return { accepted: true, completion: 'not awaited' };
     }
     if (operation === 'resume_worker') {
       if (args.confirmClosed !== true) fail('Resume requires explicit user confirmation that the previous worker session is closed (confirmClosed:true). Disconnected alone is not proof of closure.');
       if (this.resumeFences.has(target.sessionId)) fail('Resume already in flight or awaiting worker status; outcome may be uncertain. Inspect the worker before any retry; no automatic relaunch.');
+      const relative = await directory(this.store.root, target.projectDirectory);
+      assertValid();
+      if (relative !== '.') fail('worker working directory must equal the config root; subdirectory resumes would read a forbidden parent config');
+      const cwd = path.resolve(this.store.root, relative);
+      // Directory validation is read-only; recheck admission after that await.
+      if (this.resumeFences.has(target.sessionId)) fail('Resume already in flight or awaiting worker status; outcome may be uncertain. Inspect the worker before any retry; no automatic relaunch.');
+      if (this.handoff?.isClosing(target.sessionId)) fail('worker close is active or uncertain; resume is fenced');
       const fence = { inFlight: true, submitted: false, announced: false };
       this.resumeFences.set(target.sessionId, fence);
+      armReminder();
       let completed = false;
       try {
         const connection = await (this.options.probe ?? probeWorker)(target, { signal: this.probeController.signal });
         assertValid();
         if (connection.state === 'connected') fail('Worker endpoint is still connected; refusing to resume the same session twice.');
-        const relative = await directory(this.store.root, target.projectDirectory);
-        assertValid();
-        const cwd = path.resolve(this.store.root, relative);
         const fresh = await this.state();
         assertValid();
         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 });
+        const result = await this.launchObserved({ multiplexer: fresh.config.multiplexer, cwd, workspaceRoot: this.store.root, sessionId: current.sessionId });
         completed = true;
         return result;
       } finally {
@@ -384,7 +500,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/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 };