@comput/pi-intercom 0.6.1 → 0.8.1

package/references/releasing.md

@@ -0,0 +1,90 @@
+# Tag-only npm releases
+
+## Authorization and scope
+
+Obtain explicit authorization before committing, pushing, tagging or publishing. Preparing files or validating locally is not permission to release. Publishing does not install the extension or reload any Pi session; those require separate authorization.
+
+This procedure applies to **new tags containing the tag-only workflow**. Historical tags retain their original workflow files. Never move an existing tag or rerun a legacy publisher to adopt this flow. Choose a new, unused version when the owner authorizes a release.
+
+## Automatic workflow
+
+`.github/workflows/publish.yml` responds only to pushed `v*` tags. There are no GitHub Release or manual-dispatch triggers. Branch commits cannot publish; ordinary main/PR CI remains separate.
+
+Both jobs check out the triggering `github.sha`, not latest main. The workflow requires an annotated tag and checks that its peeled commit, the event SHA's peeled commit and checked-out HEAD match. `scripts/verify-release.mjs` requires canonical stable `vX.Y.Z` with safe-integer components: no leading zeros, prereleases, build metadata or suffixes. The tag must match all three fields exactly:
+
+- `package.json.version`
+- `package-lock.json.version`
+- `package-lock.json.packages[""].version`
+
+Package names must also be `@comput/pi-intercom`. Missing or malformed fields fail closed, before dependency installation.
+
+Windows and Linux run `npm ci`, typecheck, tests, **full-tree `npm audit --audit-level=low`**, and isolated package-content/install checks. Ordinary main/PR CI has the same audit gate so known findings can be caught before creating an immutable release tag. Any reported vulnerability blocks publication; do not omit development dependencies or lower the threshold to get a release through. Dependency remediation is separate reviewed work.
+
+After successful validation, the Ubuntu publisher performs another clean install, audit and package check/build from the same commit. Tracked source modifications are rejected. It packs once into a runner-temporary directory, checks the pack metadata and SHA-512/SHA-1, retains that archive as a workflow artifact, then publishes **that exact archive**, with lifecycle scripts disabled and transport retries disabled for the publish command.
+
+The workflow grants `contents: read`; only the publishing job also has `id-token: write`. It uses GitHub-hosted runners, Node 24 and npm 11 with Trusted Publishing and provenance. No stored npm token, token secret, token-bearing npmrc or token-based setup-node registry configuration is used.
+
+## npm Trusted Publisher
+
+Configure/check this on the **`@comput/pi-intercom` package**, not just the npm account:
+
+- Provider: GitHub Actions
+- Organization/user: `mbundgaard`
+- Repository: `pi-intercom`
+- Workflow filename: `publish.yml` (not the full path)
+- Environment: empty; this workflow does not declare one
+- Allowed actions: direct `npm publish` must be permitted, not only staged publishing
+
+The existing mapping may already match. Do not replace credentials, add a token fallback or change permissions without authorization. Provenance signing alone does not prove npm publishing authorization. Package repository metadata must match `https://github.com/mbundgaard/pi-intercom`.
+
+## Release procedure
+
+The commands below are examples for a shell with Git/Node/npm. Substitute the reviewed version and exact commit. Do not execute the mutation steps without explicit owner authorization.
+
+1. Review the working tree, including new files, and the proposed release scope. Exclude `.pi-intercom/`, local credentials and machine state. Resolve security-audit blockers first.
+2. Choose a stable unused version. Successfully query npm's public version list and inspect previous release workflow outcomes; a network/authentication error is **not** evidence that a version is unused. Check both local tags and remote refs. If any earlier publication outcome is uncertain, stop and inspect it first; registry visibility may lag.
+3. Update `package.json` and both lockfile version fields together, for example `npm version X.Y.Z --no-git-tag-version`. Update the changelog in README's release-history section and relevant compatibility/upgrade notes. This does not create a tag.
+4. Run local validation:
+
+   ```sh
+   RELEASE_TAG=vX.Y.Z node scripts/verify-release.mjs
+   npm ci
+   npm run typecheck
+   npm test
+   npm audit --audit-level=low
+   npm run check:package
+   git diff --check
+   ```
+
+   On PowerShell, set `$env:RELEASE_TAG = 'vX.Y.Z'` before invoking the validator. Use the actual version, not literal placeholders.
+5. Confirm the proposed npm version and Git tag remain unused immediately before release. Example read-only checks:
+
+   ```sh
+   npm view @comput/pi-intercom versions --json --prefer-online
+   git tag --list vX.Y.Z
+   git ls-remote --tags origin refs/tags/vX.Y.Z 'refs/tags/vX.Y.Z^{}'
+   ```
+
+   Require successful network queries and inspect their output; do not interpret command failures as absence. Do not reuse an existing local or remote tag.
+6. With explicit authorization, stage only reviewed files, commit and push that release commit to main. Confirm main CI passes for **that exact SHA**, not an earlier green run. Do not publish yet if any required check fails.
+7. Create an annotated tag pointing to the reviewed release commit, then push only that tag:
+
+   ```sh
+   git tag -a vX.Y.Z <release-commit> -m "Release vX.Y.Z"
+   git push origin refs/tags/vX.Y.Z
+   ```
+
+   Never use a blanket `git push --tags`, move a release tag, or tag an unreviewed newer HEAD. The tag push itself starts publication. **Do not manually trigger a second run.** Complete one release before starting another; GitHub concurrency is not an unlimited release queue.
+8. Inspect the tag-triggered workflow, npm version metadata, downloaded artifact and provenance linkage as described below. A GitHub Release page can be added afterward for release notes; it is not the publishing trigger.
+
+## Verification and uncertainty
+
+`scripts/verify-published.mjs` performs read-only verification after npm accepts the publish command. It compares the public archive byte-for-byte and by SHA-512 with the retained local archive built from the exact tag checkout, verifies registry integrity metadata (and SHA-1 when supplied), and checks decoded SLSA provenance linkage: archive subject digest, repository, source commit, workflow path, tag ref, and GitHub run/attempt URL.
+
+The script accepts `--archive`, `--version`, `--commit`, `--repo`, `--workflow`, `--run-id` and `--run-attempt` for later verification against the retained artifact. The workflow supplies these values from its verified checkout and GitHub event. It does not run npm publish or any mutation command. Downloads are restricted to the expected HTTPS npm registry endpoints, without redirects or credentials, and have size/time limits.
+
+Read-only polling for transient errors/visibility lag is bounded to 15 minutes and at most 31 attempts. A mismatch fails immediately. A timeout or missing verification evidence is **not proof that publication failed**. Preserve the workflow artifact and inspect the publish step, registry version and provenance before deciding what to do. Do not rerun a publishing job merely because its later verification step failed. Never blindly retry publication, move the tag or reuse a published version.
+
+This is **artifact equality and decoded provenance-linkage verification**, not independent cryptographic verification of the DSSE signature, certificate chain or transparency-log inclusion. Do not describe it as such. The retained CI-built archive is the reference artifact; reproducing an archive locally with different npm/toolchain versions may yield different gzip bytes and is not an equivalent reference.
+
+Report success only after workflow publication and the required artifact/linkage checks succeed. State any remaining verification limitation plainly. Installation and `/reload` remain separate actions.

package/references/v1-specification.md

@@ -19,13 +19,13 @@ This is the consolidated **target design**, authoritative over conflicting wordi
 
 Location: `<coordinator-root>/.pi-intercom/config.json`.
 
-- Discover by searching upward from the Pi working directory.
-- When genuinely absent, become coordinator and create it under the current working directory, which becomes the coordinator root. Do not infer a Git or solution root.
+- Root-isolation revision (0.8.0): select only the config in the session working directory. Never search ancestors or infer a Git/home root. `--intercom-root` is a same-directory assertion: its canonical path must equal cwd before its config is read. It cannot authorize reading a parent config.
+- Without an explicit workspace root, when the exact local config is genuinely absent, become coordinator and create it under the current working directory. Explicit workspace mode requires an existing valid config and never creates a replacement coordinator. Do not infer a Git or solution root.
 - Initial creation is atomic: only one session targeting the same path becomes coordinator. Other contenders wait for usable config and register as workers.
 - Invalid or unreadable config is an error, not absence. Leave it untouched.
 - The configuration is checked into source control. It includes session IDs and ports; do not split these into a separate runtime configuration.
 - Only coordinator extension code may write it. Workers read only. No attempt to restrict ordinary Pi shell/file tools.
-- Worker directories must be the coordinator root or descendants, stored relative to that root.
+- Saved worker directories remain root-relative. Shared-roster worker create/resume requires the coordinator root itself; descendant launches are rejected before side effects. Old descendant entries/history are retained, not silently relocated.
 - Entries survive process closure. Saved Pi session paths are not stored; resume uses session ID and project directory.
 
 Required configuration information:
@@ -55,7 +55,7 @@ A known session restores its configured role. Any unknown session ID with existi
 ### Anonymous worker
 
 1. Coordinator launches a new Pi session in its project directory with this extension loaded.
-2. Worker discovers shared config and starts a localhost endpoint using an OS-selected port.
+2. Worker verifies its explicit root equals its working directory, validates only that directory's config, then starts a localhost endpoint using an OS-selected port.
 3. Worker reports session ID, port, and project directory to the configured coordinator.
 4. Coordinator extension notifies its agent using normal prompt delivery if idle, steering if busy.
 5. Worker remains anonymous and waits. Registration does not create a placeholder config entry or authorize work.

package/src/config.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, realpath, rename, unlink, open, link, stat } from 'node:fs/promises';
+import { mkdir, readFile, realpath, rename, unlink, open, link, stat, lstat } from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { fencedClose, validateHandoff, validateCloseJob, type Handoff, type CloseJob } from './handoff.js';
@@ -80,24 +80,67 @@ const RENAME_BUDGET_MS = 250;
 export class ConfigStore {
   readonly file: string;
   private tail: Promise<unknown> = Promise.resolve();
+  private canonicalRoot?: string;
   constructor(readonly root: string, private readonly options: ConfigStoreOptions = {}) { this.file = path.join(root, '.pi-intercom', 'config.json'); }
+  private async assertLocalPaths(): Promise<void> {
+    const root = await realpath(this.root);
+    if (this.canonicalRoot === undefined) this.canonicalRoot = root;
+    else if (root !== this.canonicalRoot) fail('config root canonical location changed');
+    // Reject existing escaping links/junctions before following them for any
+    // config access. These path checks are best effort, not TOCTOU protection.
+    for (const [location, directory] of [[path.dirname(this.file), true], [this.file, false]] as const) {
+      try { await lstat(location); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue; throw error; }
+      let resolved: string;
+      try { resolved = await realpath(location); }
+      catch { fail('local config path cannot be resolved safely'); }
+      const relative = path.relative(root, resolved);
+      if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) fail('local config path escapes session root');
+      const metadata = await stat(resolved);
+      if (directory ? !metadata.isDirectory() : !metadata.isFile()) fail('invalid local config path type');
+    }
+  }
+  async validateRoot(expectedCanonicalRoot: string): Promise<void> {
+    await this.assertLocalPaths();
+    if (this.canonicalRoot !== expectedCanonicalRoot) fail('config root canonical location changed');
+  }
   async read(): Promise<Config> {
-    // Missing, malformed and unreadable files propagate; never overwrite them.
+    // Missing, malformed and unreadable local files propagate; no fallback.
+    await this.assertLocalPaths();
     return validateConfig(JSON.parse(await readFile(this.file, 'utf8')));
   }
   static async discover(cwd: string): Promise<ConfigStore | undefined> {
-    let at = path.resolve(cwd);
-    for (;;) {
-      const store = new ConfigStore(at);
-      try { await store.read(); return store; }
-      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
-      const parent = path.dirname(at); if (parent === at) return undefined; at = parent;
-    }
+    const store = new ConfigStore(await realpath(cwd));
+    try { await store.read(); return store; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; return undefined; }
+  }
+  static async workspace(cwd: string, workspaceRoot: string): Promise<ConfigStore> {
+    text(workspaceRoot, 'workspaceRoot');
+    if (!path.isAbsolute(workspaceRoot)) fail('workspaceRoot must be absolute');
+    const root = await realpath(workspaceRoot);
+    if (!(await stat(root)).isDirectory()) fail('workspaceRoot is not a directory');
+    const current = await realpath(cwd);
+    if (path.relative(root, current) !== '') fail('workspaceRoot must equal the session working directory; parent configs are forbidden');
+    const store = new ConfigStore(root);
+    await store.read(); // Explicit worker mode must never create a replacement coordinator.
+    return store;
   }
   protected openTemporary(file: string) { return open(file, 'wx'); }
+  private async cleanupTemporary(temp: string): Promise<void> {
+    // A moved root may leave an unpublished temp behind. Never follow a
+    // replacement parent outside the pinned root just to clean up. This guard
+    // is independent of lifecycle/deadline expiry so ordinary failures clean up.
+    await this.assertLocalPaths();
+    const resolved = await realpath(temp);
+    const relative = path.relative(this.canonicalRoot!, resolved);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) fail('temporary config path escapes session root');
+    await unlink(temp);
+  }
   private async temporary(config: Config): Promise<string> {
     validateConfig(config);
+    await this.assertLocalPaths();
     await mkdir(path.dirname(this.file), { recursive: true });
+    await this.assertLocalPaths();
     const temp = `${this.file}.${randomUUID()}.tmp`;
     const handle = await this.openTemporary(temp);
     try {
@@ -108,7 +151,7 @@ export class ConfigStore {
     } catch (error) {
       // Cleanup failures must not replace the original write/sync/close error.
       await handle.close().catch(() => {});
-      await unlink(temp).catch(() => {});
+      await this.cleanupTemporary(temp).catch(() => {});
       throw error;
     }
   }
@@ -118,14 +161,14 @@ export class ConfigStore {
     assertValid();
     const temp = await this.temporary({ version: 1, multiplexer: 'herdr', agents: [{ sessionId: id, name: 'Coordinator', coordinator: true, description: DEFAULT_DESCRIPTION, port: boundPort, projectDirectory: '.' }] });
     try {
-      assertValid();
+      await this.assertLocalPaths(); assertValid();
       try { await link(temp, this.file); }
       catch (e) {
         if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e;
-        await this.read(); await unlink(temp); return false;
+        await this.read(); await this.cleanupTemporary(temp); return false;
       }
-      await unlink(temp); return true;
-    } catch (error) { await unlink(temp).catch(() => {}); throw error; }
+      await this.cleanupTemporary(temp); return true;
+    } catch (error) { await this.cleanupTemporary(temp).catch(() => {}); throw error; }
   }
   private async publish(temp: string, assertValid: () => void): Promise<void> {
     const replace = this.options.rename ?? rename;
@@ -138,7 +181,7 @@ export class ConfigStore {
       // of this already synced/closed temp, never the mutation or any OS action
       // outside config persistence. The elapsed budget bounds retry initiation,
       // not the duration of an already-submitted OS rename.
-      assertValid();
+      await this.assertLocalPaths(); assertValid();
       if (attempt > 0 && now() - started >= RENAME_BUDGET_MS) throw originalError;
       try { await replace(temp, this.file); return; }
       catch (error) {
@@ -160,7 +203,7 @@ export class ConfigStore {
         // Every publication attempt checks the lifecycle/deadline guard; an
         // already submitted OS rename still cannot be undone.
         await this.publish(temp, assertValid);
-      } catch (error) { await unlink(temp).catch(() => {}); throw error; }
+      } catch (error) { await this.cleanupTemporary(temp).catch(() => {}); throw error; }
       return c;
     });
     this.tail = operation.catch(() => {}); return operation;

package/src/index.ts

@@ -11,7 +11,7 @@ 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,11 +19,12 @@ 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],
   ['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 +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;
@@ -96,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(),
@@ -106,7 +115,7 @@ 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,
       closeProvider: createCloseProvider({
         sessionId: () => context!.sessionManager.getSessionId(),
         sessionFile: () => context!.sessionManager.getSessionFile(),
@@ -185,11 +194,15 @@ 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);
+        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,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/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);
+  }
+}