@comput/pi-intercom 0.6.1 → 0.9.0

package/src/monitor-launcher.ts

@@ -2,17 +2,38 @@ import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { access, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { run, shQuote, psQuote, encoded, type Run } from './launcher.js';
+import { ensureCoreMonitorPane, closeCoreMonitorPane } from './core-monitor.js';
+import { withCoreSession, type CoreCall } from './herdr-core.js';
 
 interface Pane { pane_id: string; tab_id: string; workspace_id?: string; label?: string }
-interface RecordState { version: 1; sessionId: string; workspace: string; caller: string; pane?: string; stage: string }
+export type MonitorPlacement = 'coordinator-tab' | 'new-tab';
+interface RecordState { version: 1; sessionId: string; workspace: string; caller: string; pane?: string; tab?: string; placement?: MonitorPlacement; stage: string }
 export interface MonitorLaunchOptions {
   root: string; sessionId: string; script: string;
   node?: string; platform?: string; env?: NodeJS.ProcessEnv; run?: Run;
+  placement?: MonitorPlacement;
+  coreCall?: CoreCall;
   assertCurrent?(): void;
 }
 /** Pane ownership is separate from agent config. Pending records fence uncertain
  * mutations across reloads; neither errors nor absence of readiness cause retries. */
 export async function ensureMonitorPane(options: MonitorLaunchOptions): Promise<{ outcome: string; pane?: string }> {
+  if ((options.env ?? process.env).HC_TERMINAL_ID !== undefined) {
+    const open = (call: CoreCall) => ensureCoreMonitorPane({ ...options, placement: options.placement ?? 'coordinator-tab', call });
+    return options.coreCall ? open(options.coreCall) : withCoreSession(open);
+  }
+  return monitorPane(options, false);
+}
+export async function closeMonitorPane(options: MonitorLaunchOptions): Promise<{ outcome: string; pane?: string }> {
+  if ((options.env ?? process.env).HC_TERMINAL_ID !== undefined) {
+    const close = (call: CoreCall) => closeCoreMonitorPane({ ...options, call });
+    return options.coreCall ? close(options.coreCall) : withCoreSession(close);
+  }
+  return monitorPane(options, true);
+}
+async function monitorPane(options: MonitorLaunchOptions, closing: boolean): Promise<{ outcome: string; pane?: string }> {
+  const placement = options.placement ?? 'coordinator-tab';
+  if (!['coordinator-tab', 'new-tab'].includes(placement)) throw new Error('Invalid monitor placement');
   const env = options.env ?? process.env;
   if (env.HERDR_ENV !== '1') return { outcome: 'unavailable: coordinator is not inside Herdr' };
   if (!env.HERDR_PANE_ID) throw new Error('Monitor requires caller pane identity; no focused-pane fallback');
@@ -25,41 +46,59 @@ export async function ensureMonitorPane(options: MonitorLaunchOptions): Promise<
     const output = await exec('herdr', args);
     check();
     // pane run acknowledges command submission with an empty stdout on current Herdr.
-    if (!output.trim() && args[1] === 'run') return {};
+    if (!output.trim() && ['run', 'close'].includes(args[1])) return {};
     return JSON.parse(output).result;
   };
   const caller = (await call(['pane', 'current', '--current']))?.pane as Pane;
-  if (!caller?.pane_id || !caller.tab_id || !caller.workspace_id) throw new Error('Missing current Herdr pane identity');
+  if (!caller?.pane_id || !caller.tab_id || !caller.workspace_id) throw new Error('Missing current Herdr caller pane identity');
+  // Herdr documents inherited moved-pane aliases for --current. Preserve that
+  // resolution for opening; destructive close conservatively requires exact ID.
+  if (closing && caller.pane_id !== env.HERDR_PANE_ID) throw new Error('Mismatched current Herdr caller pane identity; refusing close');
   const label = 'Intercom monitor';
   const legacyMarker = `Intercom monitor [${options.sessionId}]`;
   const key = createHash('sha256').update(options.sessionId).digest('hex').slice(0, 24);
   const directory = path.join(options.root, '.pi-intercom');
+  check();
   await mkdir(directory, { recursive: true });
+  check();
   const file = path.join(directory, `monitor-${key}.json`), lock = `${file}.lock`;
   check();
   try { await writeFile(lock, '', { flag: 'wx', mode: 0o600 }); }
   catch { throw new Error(`Monitor launch locked; inspect ${lock} before recovery. No pane created.`); }
   let state: RecordState | undefined;
   const save = async () => {
+    check();
     const temporary = `${file}.${randomUUID()}.tmp`;
     try {
       await writeFile(temporary, JSON.stringify(state), { flag: 'wx', mode: 0o600 });
+      check();
       await rename(temporary, file);
     } finally { await unlink(temporary).catch(() => {}); }
   };
   try {
+    check();
     try {
       state = JSON.parse(await readFile(file, 'utf8'));
-      if (state?.version !== 1 || state.sessionId !== options.sessionId || typeof state.stage !== 'string') throw new Error('Invalid monitor ownership record');
+      check();
+      if (state?.version !== 1 || state.sessionId !== options.sessionId || typeof state.stage !== 'string' ||
+        typeof state.workspace !== 'string' || typeof state.caller !== 'string' ||
+        (state.placement !== undefined && !['coordinator-tab', 'new-tab'].includes(state.placement)) ||
+        (state.tab !== undefined && typeof state.tab !== 'string') ||
+        (state.pane !== undefined && typeof state.pane !== 'string') ||
+        (state.placement === 'new-tab' && ['submitted', 'observed'].includes(state.stage) && !state.tab)) throw new Error('Invalid monitor ownership record');
     } catch (e) { if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e; }
     const panes = (await call(['pane', 'list', '--workspace', caller.workspace_id]))?.panes as Pane[];
-    if (!Array.isArray(panes) || panes.some(p => !p?.pane_id || !p.tab_id)) throw new Error('Invalid Herdr pane inventory');
+    if (!Array.isArray(panes) || panes.some(p => !p?.pane_id || !p.tab_id || p.workspace_id && p.workspace_id !== caller.workspace_id) || new Set(panes.map(p => p.pane_id)).size !== panes.length || !panes.some(p => p.pane_id === caller.pane_id && p.tab_id === caller.tab_id)) throw new Error('Invalid Herdr pane inventory');
     const matches = panes.filter(p => p.label === legacyMarker ||
       (state && state.workspace === caller.workspace_id && state.pane === p.pane_id));
     if (matches.length > 1) throw new Error('Multiple monitor markers; inspect panes. No automatic changes.');
     if (matches.length === 1) {
       const pane = matches[0];
-      if (pane.pane_id === caller.pane_id || pane.tab_id !== caller.tab_id) throw new Error('Monitor marker is on caller or moved to another tab; no duplicate created');
+      if (panes.some(other => other.pane_id !== pane.pane_id && other.label === label)) throw new Error('Multiple monitor labels in workspace; inspect panes. No automatic changes.');
+      const savedPlacement = state?.placement ?? 'coordinator-tab';
+      if (pane.pane_id === caller.pane_id || pane.tab_id !== (state?.tab ?? caller.tab_id) ||
+        (savedPlacement === 'coordinator-tab' ? pane.tab_id !== caller.tab_id : pane.tab_id === caller.tab_id)) throw new Error('Monitor marker is on caller or moved to another tab; no automatic changes');
+      if (!closing && savedPlacement !== placement) throw new Error('Monitor already exists in a different placement; close it first before opening elsewhere');
       if (state && (state.workspace !== caller.workspace_id || state.caller !== caller.pane_id || (state.pane && state.pane !== pane.pane_id))) {
         throw new Error('Monitor ownership differs from current caller; no automatic changes');
       }
@@ -67,35 +106,70 @@ export async function ensureMonitorPane(options: MonitorLaunchOptions): Promise<
         throw new Error(`Monitor partial launch needs inspection (${state.stage}); no retry or duplicate`);
       }
       if (!state) {
-        state = { version: 1, sessionId: options.sessionId, workspace: caller.workspace_id, caller: caller.pane_id, pane: pane.pane_id, stage: 'observed' };
+        if (closing) throw new Error('Legacy monitor marker has no saved ownership; manual inspection required, no automatic close');
+        state = { version: 1, sessionId: options.sessionId, workspace: caller.workspace_id, caller: caller.pane_id, pane: pane.pane_id, tab: pane.tab_id, placement: 'coordinator-tab', stage: 'observed' };
         await save();
       }
+      if (closing) {
+        if (state.stage !== 'submitted') throw new Error('Legacy observed monitor lacks launcher-created ownership proof; refusing close');
+        if (pane.label !== label && pane.label !== legacyMarker) throw new Error('Owned monitor label changed; refusing to close a potentially reused pane');
+        state.stage = 'close_pending'; await save();
+        const finalCaller = (await call(['pane', 'current', '--current']))?.pane as Pane;
+        const finalPanes = (await call(['pane', 'list', '--workspace', caller.workspace_id]))?.panes as Pane[];
+        if (finalCaller?.pane_id !== caller.pane_id || finalCaller.tab_id !== caller.tab_id || finalCaller.workspace_id !== caller.workspace_id ||
+          !Array.isArray(finalPanes) || finalPanes.some(p => !p?.pane_id || !p.tab_id || p.workspace_id && p.workspace_id !== caller.workspace_id) ||
+          new Set(finalPanes.map(p => p.pane_id)).size !== finalPanes.length ||
+          !finalPanes.some(p => p.pane_id === caller.pane_id && p.tab_id === caller.tab_id) ||
+          finalPanes.filter(p => p.pane_id === pane.pane_id && p.tab_id === pane.tab_id && p.label === pane.label).length !== 1 ||
+          finalPanes.some(p => p.pane_id !== pane.pane_id && [label, legacyMarker].includes(p.label ?? ''))) throw new Error('Monitor ownership changed before close; pending outcome fenced, inspect manually');
+        // Herdr has no compare-and-close primitive: this minimizes but cannot
+        // eliminate an external topology race between inventory and pane close.
+        await call(['pane', 'close', pane.pane_id]);
+        const remaining = (await call(['pane', 'list', '--workspace', caller.workspace_id]))?.panes as Pane[];
+        if (!Array.isArray(remaining) || remaining.some(p => !p?.pane_id || !p.tab_id || p.workspace_id && p.workspace_id !== caller.workspace_id) || new Set(remaining.map(p => p.pane_id)).size !== remaining.length || remaining.some(p => p.pane_id === pane.pane_id) || !remaining.some(p => p.pane_id === caller.pane_id && p.tab_id === caller.tab_id)) throw new Error('Monitor pane absence not confirmed; close outcome uncertain, do not retry');
+        state.stage = 'closed'; await save();
+        return { outcome: 'monitor pane absence observed; no claim about child processes', pane: pane.pane_id };
+      }
       if (pane.label !== label) await call(['pane', 'rename', pane.pane_id, label]);
       return { outcome: 'existing pane preserved; process readiness not checked', pane: pane.pane_id };
     }
-    if (panes.some(p => p.tab_id === caller.tab_id && p.label === label)) {
-      throw new Error('Unowned monitor label in coordinator tab; inspect before creating another pane');
+    if (panes.some(p => p.label === label)) {
+      throw new Error('Unowned monitor label in workspace; inspect before creating or closing a pane');
     }
-    if (state && (!['submitted', 'observed'].includes(state.stage) || state.workspace !== caller.workspace_id || panes.some(p => p.pane_id === state!.pane))) {
+    if (state && (!['submitted', 'observed', 'closed'].includes(state.stage) || state.workspace !== caller.workspace_id || state.caller !== caller.pane_id || panes.some(p => p.pane_id === state!.pane))) {
       throw new Error(`Monitor ownership/partial launch needs inspection (${state.stage}, pane ${state.pane ?? 'unknown'}); no retry or duplicate`);
     }
+    if (closing) return { outcome: 'no owned monitor pane present; no close submitted' };
     await access(options.script); // Missing build must not leave a new empty pane.
     check();
-    state = { version: 1, sessionId: options.sessionId, workspace: caller.workspace_id, caller: caller.pane_id, stage: 'split_pending' };
+    state = { version: 1, sessionId: options.sessionId, workspace: caller.workspace_id, caller: caller.pane_id, placement, tab: placement === 'coordinator-tab' ? caller.tab_id : undefined, stage: placement === 'new-tab' ? 'tab_pending' : 'split_pending' };
     await save();
     // Small top quarter after swapping pane identities. Verify actual geometry below.
-    const split = await call(['pane', 'split', '--pane', caller.pane_id, '--direction', 'down', '--ratio', '0.25', '--cwd', options.root, '--no-focus']);
-    const pane = split?.pane?.pane_id;
-    if (typeof pane !== 'string' || pane === caller.pane_id) throw new Error('Split returned no distinct pane ID');
+    const created = placement === 'new-tab'
+      ? await call(['tab', 'create', '--workspace', caller.workspace_id, '--cwd', options.root, '--label', label, '--no-focus'])
+      : await call(['pane', 'split', '--pane', caller.pane_id, '--direction', 'down', '--ratio', '0.25', '--cwd', options.root, '--no-focus']);
+    const pane = placement === 'new-tab' ? created?.root_pane?.pane_id : created?.pane?.pane_id;
+    if (typeof pane !== 'string' || pane === caller.pane_id || panes.some(p => p.pane_id === pane)) throw new Error('Creation returned no distinct new pane ID');
+    if (placement === 'new-tab') {
+      const tab = created?.tab?.tab_id;
+      if (typeof tab !== 'string' || tab === caller.tab_id || panes.some(p => p.tab_id === tab)) throw new Error('Creation returned no distinct new tab ID');
+      state.tab = tab;
+    }
     state.pane = pane; state.stage = 'rename_pending'; await save();
     await call(['pane', 'rename', pane, label]);
-    state.stage = 'swap_pending'; await save();
-    const swapped = await call(['pane', 'swap', '--source-pane', caller.pane_id, '--target-pane', pane]);
-    if (swapped?.swap?.changed !== true) throw new Error('Herdr did not confirm pane swap');
-    const layout = (await call(['pane', 'layout', '--pane', caller.pane_id]))?.layout;
-    const top = layout?.panes?.find((p: { pane_id: string }) => p.pane_id === pane)?.rect;
-    const bottom = layout?.panes?.find((p: { pane_id: string }) => p.pane_id === caller.pane_id)?.rect;
-    if (!top || !bottom || top.y >= bottom.y || layout.focused_pane_id !== caller.pane_id) throw new Error('Monitor geometry/focus not confirmed; inspect panes before recovery');
+    if (placement === 'coordinator-tab') {
+      state.stage = 'swap_pending'; await save();
+      const swapped = await call(['pane', 'swap', '--source-pane', caller.pane_id, '--target-pane', pane]);
+      if (swapped?.swap?.changed !== true) throw new Error('Herdr did not confirm pane swap');
+      const layout = (await call(['pane', 'layout', '--pane', caller.pane_id]))?.layout;
+      const top = layout?.panes?.find((p: { pane_id: string }) => p.pane_id === pane)?.rect;
+      const bottom = layout?.panes?.find((p: { pane_id: string }) => p.pane_id === caller.pane_id)?.rect;
+      if (!top || !bottom || top.y >= bottom.y || layout.focused_pane_id !== caller.pane_id) throw new Error('Monitor geometry/focus not confirmed; inspect panes before recovery');
+    } else {
+      const inventory = (await call(['pane', 'list', '--workspace', caller.workspace_id]))?.panes as Pane[];
+      const current = (await call(['pane', 'current', '--current']))?.pane as Pane;
+      if (!Array.isArray(inventory) || inventory.some(p => !p?.pane_id || !p.tab_id || p.workspace_id && p.workspace_id !== caller.workspace_id) || new Set(inventory.map(p => p.pane_id)).size !== inventory.length || inventory.filter(p => p?.pane_id === pane && p.tab_id === state!.tab).length !== 1 || !inventory.some(p => p.pane_id === caller.pane_id && p.tab_id === caller.tab_id) || current?.pane_id !== caller.pane_id || current.tab_id !== caller.tab_id || current.workspace_id !== caller.workspace_id) throw new Error('New monitor tab/caller identity not confirmed; inspect before recovery');
+    }
     state.stage = 'run_pending'; await save();
     const args = [options.script, '--root', options.root];
     const command = platform === 'win32'

package/src/pane-close.ts

@@ -5,6 +5,7 @@ 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';
+import { createCoreCloseProvider } from './core-pane-close.js';
 
 interface ProcessIdentity { start: string; state: string }
 export interface PaneCloseOptions {
@@ -53,6 +54,7 @@ const alive = (identity: ProcessIdentity | undefined, start: string) =>
 /** 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 (env.HC_TERMINAL_ID !== undefined) return createCoreCloseProvider(options);
   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;

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,13 +1,15 @@
 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, monitorSettings, validateMonitorSettings, type MonitorSettings, 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 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 {
@@ -18,7 +20,12 @@ 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 MonitorRequest { root: string; sessionId: string; assertCurrent(): void }
+export interface MonitorOperations {
+  open(request: MonitorRequest & { placement: MonitorSettings['placement'] }): Promise<unknown>;
+  close(request: MonitorRequest): Promise<unknown>;
+}
 export interface RuntimeOptions {
   launch(request: LaunchRequest): Promise<unknown>;
   listen?: typeof listen;
@@ -29,6 +36,10 @@ export interface RuntimeOptions {
   closeProvider?: CloseProvider;
   /** Test seam; production defaults to 120 seconds, values above that are capped. */
   closeTimeoutMs?: number;
+  reminderClock?: ReminderClock;
+  monitor?: MonitorOperations;
+  /** Explicit launcher-provided root must equal canonical cwd; no parent-root exception. */
+  workspaceRoot?: string;
 }
 export class Intercom {
   store!: ConfigStore;
@@ -36,6 +47,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>;
@@ -44,6 +57,9 @@ export class Intercom {
   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 {
@@ -57,6 +73,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 {
@@ -71,19 +88,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();
@@ -98,6 +123,11 @@ 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) => {
@@ -152,6 +182,8 @@ export class Intercom {
     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 () => {
@@ -178,6 +210,32 @@ export class Intercom {
     assertValid();
     return { id, config, me: config.agents.find(a => a.sessionId === id) };
   }
+  async getMonitorSettings(): Promise<MonitorSettings> {
+    const assertValid = this.validity();
+    const { id, config } = await this.state();
+    assertValid(); requireCoordinator(config, id);
+    return monitorSettings(config);
+  }
+  /** Automatic admission is internal: explicit open remains allowed with disabled auto-open or no workers. */
+  async autoOpenMonitor(assertAdmission: () => void = () => {}): Promise<unknown> { return this.operateMonitor('open_monitor', {}, true, assertAdmission); }
+  private async operateMonitor(operation: 'open_monitor' | 'close_monitor', args: Record<string, unknown>, automatic = false, assertAdmission: () => void = () => {}): Promise<unknown> {
+    const lifecycle = this.validity();
+    const assertValid = () => { lifecycle(); assertAdmission(); };
+    assertValid();
+    if (Object.keys(args).some(key => operation === 'close_monitor' || key !== 'placement')) fail('invalid monitor operation arguments');
+    if (operation === 'open_monitor' && !automatic && !['coordinator-tab', 'new-tab'].includes(args.placement as string)) fail('explicit monitor placement is required; ask the user if unknown');
+    const fresh = await this.state(); assertValid(); requireCoordinator(fresh.config, fresh.id);
+    const settings = monitorSettings(fresh.config);
+    if (automatic && (!settings.autoOpen || !fresh.config.agents.some(agent => !agent.coordinator))) return { outcome: 'automatic monitor skipped' };
+    if (!this.options.monitor) fail('monitor adapter unavailable; no pane action attempted');
+    const request: MonitorRequest = { root: this.store.root, sessionId: fresh.id, assertCurrent: assertValid };
+    const result = operation === 'open_monitor'
+      ? await this.options.monitor.open({ ...request, placement: (automatic ? settings.placement : args.placement) as MonitorSettings['placement'] })
+      : await this.options.monitor.close(request);
+    assertValid();
+    const after = await this.state(); assertValid(); requireCoordinator(after.config, fresh.id);
+    return result;
+  }
   /** Accept old configs, but retire the removed browser dashboard's discovery metadata. */
   async retireDashboardMetadata(): Promise<void> {
     const record = this.captureObserver(), assertValid = this.validity();
@@ -334,7 +392,17 @@ export class Intercom {
     }
     fail('unsupported control');
   }
-  async tool(operation: string, args: Record<string, unknown>, toolCallId?: string): 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();
@@ -370,10 +438,31 @@ 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 === 'configure_monitor') {
+      const keys = Object.keys(args);
+      if (!keys.length || keys.some(key => !['autoOpen', 'placement'].includes(key))) fail('configure_monitor requires autoOpen and/or placement only');
+      validateMonitorSettings({ ...monitorSettings(config), ...args });
+      const updated = await this.store.update(id, current => {
+        current.monitor = { ...monitorSettings(current), ...args } as MonitorSettings;
+        validateMonitorSettings(current.monitor);
+      }, assertValid);
+      assertValid();
+      return { written: true, monitor: monitorSettings(updated), paneEffects: false };
+    }
+    if (operation === 'open_monitor' || operation === 'close_monitor') {
+      return this.operateMonitor(operation, args);
+    }
+    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') {
       const assertConfigurable = () => {
@@ -381,6 +470,17 @@ export class Intercom {
         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 };
@@ -392,33 +492,43 @@ 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);
@@ -426,7 +536,7 @@ export class Intercom {
         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 {