@comput/pi-intercom 0.6.1 → 0.9.0

package/src/herdr-core.ts

@@ -0,0 +1,287 @@
+import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { createConnection } from 'node:net';
+import { isAbsolute, join } from 'node:path';
+import { homedir } from 'node:os';
+import { lstat } from 'node:fs/promises';
+import type { Readable, Writable } from 'node:stream';
+
+export type CoreCall = (method: string, params: Record<string, unknown>) => Promise<any>;
+const failure = (message: string) => new Error(`PiIntercom Herdr core: ${message}`);
+const MAX_BYTES = 1024 * 1024;
+
+const CORE_VERSION = '0.1.18';
+const object = (value: any): value is Record<string, any> => value !== null && typeof value === 'object' && !Array.isArray(value);
+const identity = (value: any): boolean => object(value) && typeof value.id === 'string' && value.id.length > 0 &&
+  value.id.length <= 256 && typeof value.name === 'string';
+const statusValid = (value: any): boolean => object(value) && value.version === CORE_VERSION && identity(value.core) &&
+  Number.isSafeInteger(value.pid) && value.pid > 0;
+const sameCore = (a: any, b: any): boolean => a.id === b.id && a.name === b.name;
+const READ_METHODS = new Set(['hello', 'server.status', 'terminal.get', 'terminal.list', 'doc.get']);
+
+export interface CoreSessionOptions {
+  /** Explicit documented HC_SOCKET endpoint; no endpoint discovery or path guessing. */
+  endpoint?: string;
+  /** Test-only trusted seams. Supplying startClient requires readStatus. */
+  startClient?: () => ChildProcessWithoutNullStreams;
+  readStatus?: () => Promise<unknown>;
+  /** Tests may shorten, never extend, the ten-second whole-operation deadline. */
+  timeoutMs?: number;
+}
+
+/** Resolve only documented Unix defaults. An existing config may override the
+ * socket, so require explicit HC_SOCKET rather than silently ignoring that file. */
+export async function defaultCoreEndpoint(env: NodeJS.ProcessEnv = process.env, home = homedir(), uid = process.getuid?.()): Promise<string> {
+  if (env.HC_SOCKET !== undefined) {
+    if (!env.HC_SOCKET || !isAbsolute(env.HC_SOCKET) || env.HC_SOCKET.includes('\0')) throw failure('invalid explicit HC_SOCKET');
+    return env.HC_SOCKET;
+  }
+  const session = env.HC_SESSION ?? 'default';
+  if (!/^[a-zA-Z0-9_-]+$/.test(session) || session.trim() !== session || session.length > 64) throw failure('unsupported HC_SESSION; set explicit HC_SOCKET');
+  const config = join(env.XDG_CONFIG_HOME || join(home, '.config'), 'herdr-core', 'config.toml');
+  try { await lstat(config); throw failure('core config may override socket; set explicit HC_SOCKET'); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  let runtime = env.XDG_RUNTIME_DIR;
+  if (!runtime && uid !== undefined) {
+    const candidate = `/run/user/${uid}`;
+    try { if ((await lstat(candidate)).isDirectory()) runtime = candidate; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  }
+  const base = runtime ? join(runtime, 'herdr-core') : join(env.XDG_STATE_HOME || join(home, '.local', 'state'), 'herdr-core', session);
+  if (!isAbsolute(base)) throw failure('core endpoint root must be absolute');
+  return join(base, `${session}.sock`);
+}
+
+function cliStatus(): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    execFile('hc', ['server', 'status', '--json'], { windowsHide: true, timeout: 3000, maxBuffer: MAX_BYTES, encoding: 'utf8' }, (error, stdout) => {
+      if (error) return reject(failure('existing core status preflight failed'));
+      try { resolve(JSON.parse(stdout)); } catch { reject(failure('invalid core status preflight')); }
+    });
+  });
+}
+
+/** One bounded, sequential operation on ONE verified connection; never reconnects.
+ * Core v0.1.18 schema hello + server.status bind protocol, version, permanent core
+ * identity and (with CLI preflight) pid before the callback can send requests.
+ * This is not cryptographic authentication or a boot nonce; local endpoint access
+ * is the upstream trust boundary. The call handle expires with the callback.
+ *
+ * IMPORTANT: v0.1.18 cli.rs/server + platform/unix.rs status_may_start_core() show
+ * `hc server status` ITSELF autostarts on Unix. Unix therefore connects directly
+ * via HC_SOCKET or documented defaults (only when no config override can exist),
+ * without starting a process.
+ * Public contract: herdr-core v0.1.18 schema/README.md "Connecting" and
+ * docs/security.md "State and endpoints". No undocumented endpoint discovery.
+ * On Windows only, status is require_existing; preflight precedes hc connect.
+ * That check is NOT atomic start avoidance: core could disappear before connect.
+ * Use an explicit endpoint even on Windows when strict no-autostart is required.
+ */
+export async function withCoreSession<T>(operation: (call: CoreCall) => Promise<T>, options: CoreSessionOptions = {}): Promise<T> {
+  const timeoutMs = options.timeoutMs ?? 10000;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 10000) throw failure('invalid session deadline');
+  let input: Writable | undefined, output: Readable | undefined, cleanup: (() => void) | undefined;
+  let closed = false, fatal: Error | undefined, mutationAttempted = false;
+  let pending: { id: string; resolve: (value: any) => void; reject: (error: Error) => void } | undefined;
+  let rejectSession!: (error: Error) => void;
+  const failed = new Promise<never>((_, reject) => { rejectSession = reject; });
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    try { cleanup?.(); } catch { /* Closing our transport must not mask the result. */ }
+  };
+  const fail = (reason: string) => {
+    if (closed || fatal) return;
+    fatal = Object.assign(failure(`${reason}; session unusable; ${mutationAttempted ? 'outcome uncertain; ' : ''}do not replay`), { uncertain: mutationAttempted });
+    pending?.reject(fatal); pending = undefined;
+    rejectSession(fatal);
+    close();
+  };
+  const timer = setTimeout(() => fail('operation timed out'), timeoutMs);
+  let methods: Set<string> | undefined, requests = 0, bytes = 0, buffer = '';
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const call: CoreCall = (method, params) => {
+    if (closed || fatal) return Promise.reject(fatal ?? failure('session is closed; do not replay'));
+    if (pending || ++requests > 64 || (methods && !methods.has(method))) {
+      fail('concurrent, excessive or unsupported API request');
+      return Promise.reject(fatal);
+    }
+    const id = randomUUID();
+    let request: string;
+    try { request = `${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`; }
+    catch { fail('invalid API request'); return Promise.reject(fatal); }
+    if (Buffer.byteLength(request) > MAX_BYTES) { fail('API request exceeded limit'); return Promise.reject(fatal); }
+    return new Promise((resolve, reject) => {
+      pending = { id, resolve, reject };
+      if (!READ_METHODS.has(method)) mutationAttempted = true;
+      try { input!.write(request, error => { if (error) fail('API request transport failed'); }); }
+      catch { fail('API request transport failed'); }
+    });
+  };
+  const run = async () => {
+    let before: any;
+    const endpoint = options.endpoint ?? process.env.HC_SOCKET ?? (!options.startClient && process.platform !== 'win32' ? await defaultCoreEndpoint() : undefined);
+    if (options.startClient || !endpoint) {
+      if (options.startClient && !options.readStatus) throw failure('test client requires status preflight');
+      if (!options.startClient && process.platform !== 'win32') throw failure('explicit HC_SOCKET required: Unix hc server status/connect may autostart; no client started');
+      before = await (options.readStatus ?? cliStatus)();
+      if (closed) throw fatal;
+      if (!statusValid(before)) throw failure('unsupported core status/version; no client started');
+      const child = options.startClient ? options.startClient() : spawn('hc', ['connect'], { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+      input = child.stdin; output = child.stdout;
+      cleanup = () => { child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); child.kill(); };
+      child.on('error', () => fail('could not start hc API client'));
+      child.on('close', () => fail('API client ended without operation completion'));
+      child.stderr.on('error', () => fail('API diagnostic transport failed'));
+      child.stderr.on('data', () => {}); // Never expose process diagnostics or credentials.
+    } else {
+      if (!isAbsolute(endpoint) || endpoint.includes('\0')) throw failure('explicit absolute local core endpoint required');
+      const socket = createConnection(endpoint);
+      input = output = socket;
+      cleanup = () => { socket.destroy(); };
+      socket.on('close', () => fail('API connection closed'));
+    }
+    input.on('error', () => fail('API request transport failed'));
+    output.on('error', () => fail('API response transport failed'));
+    output.on('end', () => fail('API response EOF; operation not completed'));
+    output.on('data', (chunk: Buffer) => {
+      if (closed) return;
+      if (!pending) return fail('unsolicited API response data');
+      bytes += chunk.length;
+      if (bytes > MAX_BYTES) return fail('API response exceeded operation limit');
+      try { buffer += decoder.decode(chunk, { stream: true }); }
+      catch { return fail('invalid API response UTF-8'); }
+      const end = buffer.indexOf('\n');
+      if (end < 0) return;
+      try { decoder.decode(); } catch { return fail('invalid trailing API response UTF-8'); }
+      const line = buffer.slice(0, end);
+      // Sequential request/reply only: reject unsolicited/trailing data, including
+      // a partial next response, BEFORE allowing the callback's next mutation.
+      if (buffer.slice(end + 1).trim()) return fail('trailing API response data');
+      buffer = '';
+      let message: any;
+      try { message = JSON.parse(line); } catch { return fail('invalid API response'); }
+      if (!object(message) || !pending || message.id !== pending.id) return fail('uncorrelated API response');
+      if (message.jsonrpc !== '2.0' || Object.hasOwn(message, 'error') || !Object.hasOwn(message, 'result')) return fail('API rejected request');
+      const current = pending; pending = undefined;
+      current.resolve(message.result);
+    });
+    const hello = await call('hello', { generation: 1, framed: false });
+    if (!object(hello) || hello.generation !== 1 || hello.version !== CORE_VERSION || hello.framed !== false ||
+      !identity(hello.core) || !Array.isArray(hello.methods) || !hello.methods.every((v: unknown) => typeof v === 'string') ||
+      !Array.isArray(hello.features) || !hello.features.every((v: unknown) => typeof v === 'string') ||
+      (before && !sameCore(hello.core, before.core))) throw failure('unsupported or changed core handshake');
+    methods = new Set(hello.methods);
+    const status = await call('server.status', {});
+    if (!statusValid(status) || !sameCore(status.core, hello.core) || (before && status.pid !== before.pid)) throw failure('core instance changed before operation');
+    const result = await operation(call);
+    if (fatal) throw fatal; // Catching a request failure never rehabilitates a session.
+    if (pending) { fail('callback left an unfinished API request'); throw fatal; }
+    return result;
+  };
+  try { return await Promise.race([run(), failed]); }
+  catch (error) {
+    if (mutationAttempted && !(error instanceof Error && 'uncertain' in error)) {
+      throw Object.assign(failure('operation failed after mutation; outcome uncertain; do not replay'), { uncertain: true, cause: error });
+    }
+    throw error;
+  }
+  finally { clearTimeout(timer); close(); }
+}
+
+/** Standalone compatibility API: one call per bounded session. Multi-call operations
+ * MUST use withCoreSession, not repeated coreCall invocations. */
+export const coreCall: CoreCall = (method, params) => withCoreSession(call => call(method, params));
+
+export function terminalAddress(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || (!/^t[0-9a-z]+$/.test(value) || value.trim() !== value)) throw failure('explicit local HC_TERMINAL_ID required');
+}
+
+/** SOURCE-BACKED PRIVATE FORMAT, not a stable app API or production-readiness claim.
+ * herdr-app v0.1.13 src/mirror.rs Document/SharedSpace/SharedTab and src/layout.rs
+ * Node/Kind/Content define this opaque core doc. There is NO app-version handshake:
+ * core 0.1.18 alone cannot establish app compatibility. An upstream versioned
+ * layout contract is still needed. Tested subset: rows/columns, terminal/mod blocks,
+ * and mod-only floats (src/layout.rs Float), whose IDs are checked too. Reject
+ * stacks, terminal floats and dynamic context/agent content anywhere, including
+ * unrelated tabs, rather than silently miss aliases.
+ * Unknown metadata is preserved verbatim, not interpreted as a layout extension.
+ * Private focus state is separate and is never inferred or changed here. */
+export function locateTerminalTab(document: any, terminal: string): { space: any; tab: any; pane: any } {
+  terminalAddress(terminal);
+  if (!object(document) || !Array.isArray(document.spaces) || document.spaces.length > 256) throw failure('unsupported app layout document');
+  const matches: { space: any; tab: any; pane: any }[] = [];
+  const ids = new Set<string>(); let count = 0;
+  const unique = (id: unknown) => {
+    if (typeof id !== 'string' || !id || id.length > 256 || ids.has(id)) throw failure('ambiguous layout identity');
+    ids.add(id);
+  };
+  for (const space of document.spaces) {
+    if (!object(space)) throw failure('unsupported layout space');
+    unique(space.id);
+    if (!Array.isArray(space.tabs) || space.tabs.length > 512) throw failure('invalid layout tabs');
+    for (const tab of space.tabs) {
+      if (!object(tab)) throw failure('unsupported layout tab');
+      unique(tab.id);
+      if (typeof tab.name !== 'string') throw failure('invalid tab name');
+      const visit = (node: any, depth: number) => {
+        if (++count > 4096 || depth > 64 || !object(node) || typeof node.id !== 'string') throw failure('layout bounds exceeded');
+        // The app uses the tab ID again for its root container.
+        if (node !== tab.root || node.id !== tab.id) unique(node.id);
+        if (Object.hasOwn(node, 'floating')) {
+          if (!Array.isArray(node.floating)) throw failure('unsupported floating layout; no layout changes');
+          for (const floating of node.floating) {
+            if (++count > 4096 || !object(floating) || !object(floating.content) ||
+              typeof floating.content.mod !== 'string' || ['terminal', 'tab', 'context', 'agent'].some(key => Object.hasOwn(floating.content, key)) ||
+              ['children', 'floating', 'type'].some(key => Object.hasOwn(floating, key)) ||
+              (Object.hasOwn(floating, 'edge') && !['top', 'right', 'bottom', 'left'].includes(floating.edge)) ||
+              (Object.hasOwn(floating, 'align') && !['start', 'center', 'end'].includes(floating.align))) {
+              throw failure('unsupported floating layout (only mod floats supported); no layout changes');
+            }
+            unique(floating.id);
+          }
+        }
+        if (node.type === 'block') {
+          if (Object.hasOwn(node, 'children') || !object(node.content)) throw failure('unsupported block shape');
+          const tags = ['terminal', 'mod', 'tab', 'context', 'agent'].filter(key => Object.hasOwn(node.content, key));
+          if (tags.length !== 1 || !['terminal', 'mod'].includes(tags[0]) || typeof node.content[tags[0]] !== 'string') throw failure('unsupported block content');
+          if (tags[0] === 'terminal') terminalAddress(node.content.terminal);
+          if (node.content.terminal === terminal) matches.push({ space, tab, pane: node });
+        } else if (['row', 'column'].includes(node.type) && Array.isArray(node.children) && !Object.hasOwn(node, 'content')) {
+          for (const child of node.children) visit(child, depth + 1);
+        } else throw failure('unsupported layout node (only row/column/block supported)');
+      };
+      visit(tab.root, 0);
+    }
+  }
+  if (matches.length !== 1) throw failure('terminal does not map to exactly one app pane; no layout changes');
+  return matches[0];
+}
+
+/** Change only the owning tab name using the app's optimistic document protocol.
+ * Success proves shared state, not that an attached Windows window has rendered it. */
+export async function renameCoreTab(terminal: string, name: string, call?: CoreCall): Promise<void> {
+  terminalAddress(terminal);
+  if (typeof name !== 'string' || !name.trim() || name.length > 128 || /[\x00-\x1f\x7f]/.test(name)) throw failure('invalid worker tab name');
+  // Default production rename is one operation, never a chain of reconnecting calls.
+  // An injected call remains supported for tests or an enclosing withCoreSession.
+  if (!call || call === coreCall) return withCoreSession(session => renameCoreTab(terminal, name, session));
+  const record = await call('terminal.get', { terminal });
+  if (record?.address !== terminal || record.state !== 'live' || !Number.isSafeInteger(record.created_ms) || record.created_ms <= 0) throw failure('worker terminal identity is not live');
+  const snapshot = await call('doc.get', { name: 'herdr-app' });
+  if (!Number.isSafeInteger(snapshot?.version) || snapshot.version < 0 || !snapshot.value) throw failure('app layout unavailable');
+  const value = structuredClone(snapshot.value);
+  const { space, tab, pane } = locateTerminalTab(value, terminal);
+  if (record.labels?.['herdr.space'] !== space.id || record.labels?.['herdr.tab'] !== tab.id) throw failure('terminal labels disagree with actual app layout');
+  if (tab.name === name) return;
+  tab.name = name;
+  const fresh = await call('terminal.get', { terminal });
+  if (fresh?.address !== terminal || fresh.state !== 'live' || fresh.created_ms !== record.created_ms ||
+    fresh.labels?.['herdr.space'] !== space.id || fresh.labels?.['herdr.tab'] !== tab.id) throw failure('terminal identity changed before rename');
+  const written = await call('doc.set', { name: 'herdr-app', version: snapshot.version, value });
+  if (!Number.isSafeInteger(written?.version) || written.version !== snapshot.version + 1) throw failure('layout write acknowledgment uncertain; do not replay');
+  const observed = await call('doc.get', { name: 'herdr-app' });
+  if (!Number.isSafeInteger(observed?.version) || observed.version < written.version) throw failure('layout readback version not confirmed; do not replay');
+  const target = locateTerminalTab(observed?.value, terminal);
+  if (target.space.id !== space.id || target.tab.id !== tab.id || target.pane.id !== pane.id || target.tab.name !== name) throw failure('tab rename not confirmed; do not replay');
+}

package/src/index.ts

@@ -5,13 +5,13 @@ import { getAgentDir, SessionManager, SettingsManager, truncateHead, withFileMut
 import { ConfigStore } from './config.js';
 import { Intercom, UNSUPPORTED_CANCELLATION } from './runtime.js';
 import { launchers } from './launcher.js';
-import { ensureMonitorPane } from './monitor-launcher.js';
+import { ensureMonitorPane, closeMonitorPane } 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 }) })],
@@ -19,12 +19,16 @@ 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', 'Coordinator only. Begin a background save-handoff-and-close job for a configured worker in Linux Herdr. Requests a public summary, saves it in config, waits for successful tool persistence and final turn settlement, then attempts one verified pane close. Returns job acceptance, not completion. Registration/session history are retained. Check worker_status/list for closeJob; failure/timeout/uncertainty never authorizes retry. Not graceful abort or an all-descendants termination guarantee; Windows/non-Herdr unsupported.', to],
   ['report_handoff', 'Configured worker only, in response to its pending close request. Submit the matching jobId and concise public resume handoff (current work, completed work, unfinished items, blockers, next step). Never include secrets, private reasoning or raw tool payloads. Saved receipt is not closure: finish the response and wait; the extension requires final turn settlement before pane closure.', Type.Object({ jobId: Type.String({ minLength: 1, maxLength: 128 }), summary: Type.String({ minLength: 1, maxLength: 4000 }) })],
-  ['resume_worker', 'Coordinator only. Resume saved session/name/responsibility after the user explicitly confirms the old session was closed: set confirmClosed:true only for that confirmation, never infer it from disconnected status. A matching live health endpoint blocks launch. In-flight/uncertain attempts are fenced until worker status arrives; otherwise inspect process and reload coordinator before considering retry. No cross-process uniqueness guarantee, automatic assignment, replacement or removal.', Type.Object({ to: Type.String({ minLength: 1, maxLength: 128 }), confirmClosed: Type.Boolean() })],
+  ['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],
+  ['open_monitor', "Coordinator only. Open or reuse the owned status monitor, including with no workers. Explicit placement is required: ask the user if unknown; never guess or fall back to saved settings. Currently supported: 'coordinator-tab' (pane above the coordinator in its current tab), 'new-tab' (separate tab). Does not assign worker work or change saved settings.", Type.Object({ placement: Type.String({ minLength: 1 }) })],
+  ['close_monitor', 'Coordinator only. Close only the verified owned status monitor pane, not a worker, coordinator or whole tab. Does not change saved auto-open settings.', Type.Object({})],
+  ['configure_monitor', "Coordinator only. Persist autoOpen and/or placement for future monitor openings. At least one setting is required. Currently supported placement values: 'coordinator-tab' (pane above the coordinator in its current tab), 'new-tab' (separate tab). Does not open, close or move panes.", Type.Object({ autoOpen: Type.Optional(Type.Boolean()), placement: Type.Optional(Type.String({ minLength: 1 })) }, { minProperties: 1, additionalProperties: false })],
   ['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'] }) })],
 ];
 
@@ -46,6 +50,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;
@@ -57,29 +65,31 @@ 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;
+  let monitorAutoEpoch = 0;
+  let monitorTask: { runtime: Intercom; generation: number; epoch: number; dirty: boolean; promise: Promise<void> } | undefined;
   async function ensureCoordinatorMonitor(current: Intercom, ctx: ExtensionContext, started: number): Promise<void> {
-    const isCurrent = () => started === generation && runtime === current;
+    const epoch = monitorAutoEpoch;
+    const isCurrent = () => started === generation && runtime === current && epoch === monitorAutoEpoch;
     if (!isCurrent()) return;
-    if (monitorTask?.runtime === current && monitorTask.generation === started) {
+    if (monitorTask?.runtime === current && monitorTask.generation === started && monitorTask.epoch === epoch) {
       monitorTask.dirty = true;
       return monitorTask.promise;
     }
     const check = async () => {
       try {
-        const { config, me, id } = await current.state();
+        const { config, me } = 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'); },
-        });
+        const settings = await current.getMonitorSettings();
+        if (!isCurrent() || !settings.autoOpen) return;
+        const monitor = await current.autoOpenMonitor(() => {
+          if (!isCurrent()) throw new Error('Automatic monitor request superseded');
+        }) as Awaited<ReturnType<typeof ensureMonitorPane>>;
         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() };
+    const task = { runtime: current, generation: started, epoch, dirty: false, promise: Promise.resolve() };
     monitorTask = task;
     task.promise = (async () => {
       do { task.dirty = false; await check(); } while (task.dirty && isCurrent());
@@ -96,6 +106,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(),
@@ -106,7 +120,23 @@ export default function intercomExtension(pi: ExtensionAPI): void {
       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,
+      monitor: {
+        open: request => ensureMonitorPane({ ...request,
+          script: fileURLToPath(new URL('../dist/monitor.js', import.meta.url)),
+          assertCurrent: () => {
+            request.assertCurrent();
+            if (started !== generation || runtime !== current) throw new Error('Coordinator session changed');
+          },
+        }),
+        close: request => closeMonitorPane({ ...request,
+          script: fileURLToPath(new URL('../dist/monitor.js', import.meta.url)),
+          assertCurrent: () => {
+            request.assertCurrent();
+            if (started !== generation || runtime !== current) throw new Error('Coordinator session changed');
+          },
+        }),
+      },
       closeProvider: createCloseProvider({
         sessionId: () => context!.sessionManager.getSessionId(),
         sessionFile: () => context!.sessionManager.getSessionFile(),
@@ -185,11 +215,21 @@ export default function intercomExtension(pi: ExtensionAPI): void {
   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 current = runtime, started = generation;
-        const result = await current.tool(operation, args as Record<string, unknown>, _id);
+        if (operation === 'close_monitor') {
+          const state = await current.state();
+          if (started !== generation || runtime !== current) throw new Error('Coordinator session changed');
+          if (!state.me?.coordinator) throw new Error('PiIntercom: coordinator permission required');
+          monitorAutoEpoch++; // Fence prior automatic passes; lock refusal never schedules a retry.
+        }
+        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: ${current.store.file}]` : '') }], details: {} };

package/src/launcher.ts

@@ -1,7 +1,10 @@
 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';
+import { renameCoreTab, withCoreSession, type CoreCall } from './herdr-core.js';
+import { preflightCoreWorkerLayout, attachCoreWorkerLayout } from './core-worker-layout.js';
 
 export type Run = (file: string, args: string[]) => Promise<string>;
 export const run: Run = async (file, args) => {
@@ -16,6 +19,7 @@ export interface LauncherOptions {
   platform?: string;
   env?: NodeJS.ProcessEnv;
   run?: Run;
+  coreCall?: CoreCall;
   sessionExists(cwd: string, id: string): Promise<boolean>;
 }
 export function launchers(options: LauncherOptions) {
@@ -23,11 +27,55 @@ 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');
+      // HC identity takes precedence even when stale legacy variables survive.
+      // Never reinterpret an HC failure as permission to create a legacy tab.
+      if (env.HC_TERMINAL_ID !== undefined) {
+        const caller = env.HC_TERMINAL_ID;
+        if (!/^t[0-9a-z]+$/.test(caller) || caller.trim() !== caller) fail('HC launcher requires a local HC_TERMINAL_ID address; names and remote addresses are not accepted; no fallback');
+        // No template/task/message/provider override. Use an explicit shell and
+        // preserve the user's Pi defaults and literal root/session arguments.
+        const argv = platform === 'win32'
+          ? ['powershell.exe', '-NoProfile', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded(`$ErrorActionPreference='Stop'; Set-Location -LiteralPath ${psQuote(request.cwd)}; & (Get-Command pi.ps1 -ErrorAction Stop).Source ${args.map(psQuote).join(' ')}; exit $LASTEXITCODE`)]
+          : ['/bin/sh', '-c', `exec pi ${args.map(shQuote).join(' ')}`];
+        let attempted = false;
+        const operation = async (call: CoreCall) => {
+          // Refuse missing/unsupported app layout BEFORE creating a terminal.
+          // All reads, spawn, CAS placement and readback share this connection.
+          const ticket = await preflightCoreWorkerLayout({ caller, cwd: request.cwd, workspaceRoot: request.workspaceRoot, platform }, call);
+          attempted = true;
+          const created = await call('terminal.run', {
+            argv, cwd: request.cwd, caller, parent: caller,
+            outlive_parent: true, no_notify: true, wait: false, keep: false,
+          });
+          const placement = await attachCoreWorkerLayout(ticket, created, call);
+          return { commandSubmitted: true, ...placement, terminalState: created.state,
+            ui: 'render-unverified',
+            uiReason: 'Dedicated tab confirmed in shared app layout; remote UI rendering is not observed.',
+            piReadiness: 'not observed; terminal creation and layout confirmation are not Pi readiness', registrationAwaited: false };
+        };
+        try {
+          // Injection is a trusted test seam; production verifies hello/status
+          // for core 0.1.18 once, without reconnecting between launch steps.
+          return await (options.coreCall ? operation(options.coreCall) : withCoreSession(operation, { endpoint: env.HC_SOCKET }));
+        } catch (e) {
+          if (attempted) throw Object.assign(new Error('HC worker launch or placement failed; outcome unknown, terminal/process and app tab may remain; no automatic cleanup/retry/replacement or legacy fallback'), { outcomeUncertain: true });
+          fail(`HC launch preflight failed: ${String(e)}; no fallback or launch attempted`);
+        }
+      }
+      // Compatibility is selected only by explicit legacy identity, never by an
+      // HC error or by discovering an arbitrary running Herdr window.
+      if (env.HERDR_ENV !== '1' || !env.HERDR_WORKSPACE_ID) fail('Herdr launcher requires HC_TERMINAL_ID or explicit legacy HERDR_ENV=1 and HERDR_WORKSPACE_ID; no fallback');
       let created: { result?: { root_pane?: { pane_id?: string }; tab?: { tab_id?: string } } };
       try { created = JSON.parse(await exec('herdr', ['tab', 'create', '--workspace', env.HERDR_WORKSPACE_ID, '--cwd', request.cwd, '--label', 'Intercom (anonymous)', '--no-focus'])); }
       catch (e) { fail(`Herdr tab launch failed: ${String(e)}; no fallback or cleanup`); }
@@ -48,7 +96,7 @@ export function launchers(options: LauncherOptions) {
     if (request.multiplexer !== 'none') fail('unsupported multiplexer');
     // Use encoded PowerShell rather than constructing cmd.exe command strings.
     // The outer process reports only successful visible terminal creation, not Pi readiness.
-    const child = `$ErrorActionPreference='Stop'; Get-ChildItem Env: | Where-Object { $_.Name -like 'HERDR_*' -or $_.Name -like 'PI_SESSION_*' } | ForEach-Object { Remove-Item ('Env:' + $_.Name) }; Set-Location -LiteralPath ${psQuote(request.cwd)}; & (Get-Command pi.cmd -ErrorAction Stop).Source ${args.map(psQuote).join(' ')}; if ($LASTEXITCODE -ne 0) { Write-Error ('Pi exited with code ' + $LASTEXITCODE) }`;
+    const child = `$ErrorActionPreference='Stop'; Get-ChildItem Env: | Where-Object { $_.Name -like 'HERDR_*' -or $_.Name -like 'HC_*' -or $_.Name -like 'PI_SESSION_*' } | ForEach-Object { Remove-Item ('Env:' + $_.Name) }; Set-Location -LiteralPath ${psQuote(request.cwd)}; & (Get-Command pi.cmd -ErrorAction Stop).Source ${args.map(psQuote).join(' ')}; if ($LASTEXITCODE -ne 0) { Write-Error ('Pi exited with code ' + $LASTEXITCODE) }`;
     const outer = `$ErrorActionPreference='Stop'; $null=Get-Command pi.cmd -ErrorAction Stop; $p=Start-Process -FilePath (Join-Path $PSHOME 'powershell.exe') -WorkingDirectory ${psQuote(request.cwd)} -ArgumentList @('-NoProfile','-NoExit','-EncodedCommand',${psQuote(encoded(child))}) -WindowStyle Normal -PassThru; $p.Id`;
     const result = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded(outer)]);
     const pid = Number(result.trim());
@@ -56,6 +104,10 @@ export function launchers(options: LauncherOptions) {
     return { terminalLaunched: true, pid, piReadiness: 'not observed; inspect visible terminal for startup failures', registrationAwaited: false };
   }
   async function syncName(name: string): Promise<void> {
+    if (env.HC_TERMINAL_ID !== undefined) {
+      await renameCoreTab(env.HC_TERMINAL_ID, name, options.coreCall);
+      return;
+    }
     if (env.HERDR_ENV !== '1') return;
     // Resolve inherited pane context, including panes moved since launch.
     if (!env.HERDR_PANE_ID) fail('Herdr tab name sync requires caller pane identity');