@comput/pi-intercom 0.5.2 → 0.8.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,10 +7,11 @@ 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][] = [
-  ['create_worker', 'Coordinator only. Launch one anonymous worker in projectDirectory (default root). No assignment, configuration, or registration wait.', Type.Object({ projectDirectory: Type.Optional(Type.String()) })],
+  ['create_worker', 'Coordinator only. Launch one anonymous worker at the coordinator root. projectDirectory defaults to root and must resolve to that same directory; subfolder launches cannot use a parent config and are refused. No assignment, configuration, or registration wait.', Type.Object({ projectDirectory: Type.Optional(Type.String()) })],
   ['configure_worker', 'Coordinator only. Write explicit reported connection details and responsibility to config. Does not notify, reload, or start work. Use reload_worker separately.', Type.Object({ sessionId: Type.String(), port: Type.Integer({ minimum: 1, maximum: 65535 }), projectDirectory: Type.String(), name: Type.String({ minLength: 1, maxLength: 128 }), description: Type.String({ minLength: 1, maxLength: 4096 }) })],
   ['reload_worker', 'Coordinator only. Ask worker to reread responsibility and synchronize names. NOT Pi extension reload, cancellation, restart, or work assignment.', to],
   ['send', 'Configured sessions only. Send an explicit work/progress/findings message by recipient name. Idle delivery starts a turn; busy delivery steers at supported boundaries. Receipt is not an agent reply. Progress questions do not cancel assignments.', Type.Object({ to: Type.String(), message: Type.String({ minLength: 1, maxLength: 48000 }) })],
@@ -18,11 +19,13 @@ const tools: [string, string, TSchema][] = [
   ['list', 'Configured sessions only. Read current saved names, responsibilities, session IDs, roles and ports. No live probing. Output limited to 50 KiB/2000 lines; full data remains in config.json.', Type.Object({})],
   ['request_status', 'Coordinator only. Ask worker extension to send an independent sessionId/port/busy report without a model turn on worker. No synchronous status reply.', to],
   ['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 })) })],
+  ['stop_reminders', 'Coordinator only. Disable the five-minute orchestration reminders until the next worker-directed call. Use when there is genuinely nothing to follow up on. Stops only reminders, not workers, close jobs or model work. Reminder state is session-local and clears on shutdown/reload.', Type.Object({})],
   ['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],
-  ['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],
+  ['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. Saved subfolder launches are refused rather than relocated, because a worker cannot use a parent config. 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. 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'] }) })],
 ];
 
@@ -44,6 +47,10 @@ class PiConfigStore extends ConfigStore {
   }
 }
 export default function intercomExtension(pi: ExtensionAPI): void {
+  pi.registerFlag('intercom-root', {
+    type: 'string',
+    description: 'Explicit Intercom root must equal this session cwd; parent configuration is never allowed, even with this flag.',
+  });
   let runtime: Intercom | undefined;
   let context: ExtensionContext | undefined;
   let generation = 0;
@@ -55,6 +62,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();
@@ -65,6 +101,10 @@ export default function intercomExtension(pi: ExtensionAPI): void {
     context = ctx;
     if (!['win32', 'linux'].includes(process.platform) || ctx.mode !== 'tui') throw new Error('PiIntercom requires Windows or Linux interactive Pi. No resources started.');
     if (!ctx.isProjectTrusted()) throw new Error('PiIntercom requires project trust before honoring shared project configuration.');
+    // Flags become available at session_start, not extension factory time. Never
+    // infer workspace authority from ancestors or inherited environment values.
+    const workspaceRoot = pi.getFlag('intercom-root');
+    if (workspaceRoot !== undefined && typeof workspaceRoot !== 'string') throw new Error('PiIntercom: intercom-root must be an explicit absolute path.');
     runtime = new Intercom({
       cwd: ctx.cwd,
       sessionId: () => context!.sessionManager.getSessionId(),
@@ -74,7 +114,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), workspaceRoot,
+      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 +133,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 +147,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 +161,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,17 +189,23 @@ 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({
       name: `intercom_${operation}`, label: `Intercom ${operation}`, description, parameters,
+      // Handoff readiness requires this call's successful transcript tool result.
+      // Pi1.x enforces model-only for nested calls;0.84 ignores this optional field
+      // and has no nested-tool API. Never substitute a parent result as proof.
+      exposure: operation === 'report_handoff' ? 'model-only' : 'direct',
       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, signal);
+        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/launcher.ts

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import path from 'node:path';
 import { fail } from './config.js';
 import type { LaunchRequest } from './runtime.js';
 
@@ -23,9 +24,16 @@ export function launchers(options: LauncherOptions) {
   async function launch(request: LaunchRequest): Promise<unknown> {
     const platform = options.platform ?? process.platform;
     if (platform !== 'win32' && platform !== 'linux') fail('launchers support Windows and Linux only');
+    const paths = platform === 'win32' ? path.win32 : path.posix;
+    if (typeof request.workspaceRoot !== 'string' || !request.workspaceRoot.trim() || request.workspaceRoot.includes('\0') || !paths.isAbsolute(request.workspaceRoot)) fail('worker launch requires an explicit absolute workspace root');
+    // Runtime performs authoritative realpath equality before reading config.
+    // Defend direct launcher calls too, without filesystem access or cwd rewrites.
+    const samePath = (value: string) => platform === 'win32' ? paths.resolve(value).toLowerCase() : paths.resolve(value);
+    if (typeof request.cwd !== 'string' || !paths.isAbsolute(request.cwd) || samePath(request.workspaceRoot) !== samePath(request.cwd)) fail('worker workspace root must equal its working directory; parent workspace access is not allowed');
     if (platform === 'linux' && request.multiplexer === 'none') fail('Linux worker launching requires Herdr; none is Windows-only. No terminal fallback');
     if (request.sessionId && !await options.sessionExists(request.cwd, request.sessionId)) fail('saved Pi session not found in project directory; never-used sessions may not be persisted. Config unchanged; no replacement launched');
-    const args = ['-e', options.extension, ...(request.sessionId ? ['--session', request.sessionId] : [])];
+    // Explicit per-child CLI scope cannot widen cwd or leak from a parent shell environment.
+    const args = ['-e', options.extension, '--intercom-root', request.workspaceRoot, ...(request.sessionId ? ['--session', request.sessionId] : [])];
     if (request.multiplexer === 'herdr') {
       if (env.HERDR_ENV !== '1' || !env.HERDR_WORKSPACE_ID) fail('Herdr launcher requires this Pi to run inside a Herdr-managed workspace; no fallback');
       let created: { result?: { root_pane?: { pane_id?: string }; tab?: { tab_id?: string } } };

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;