@comput/pi-intercom 0.6.1 → 0.9.0

package/package.json

@@ -6,13 +6,13 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/comput-sh/pi-intercom.git"
+    "url": "git+https://github.com/mbundgaard/pi-intercom.git"
   },
-  "homepage": "https://github.com/comput-sh/pi-intercom#readme",
+  "homepage": "https://github.com/mbundgaard/pi-intercom#readme",
   "bugs": {
-    "url": "https://github.com/comput-sh/pi-intercom/issues"
+    "url": "https://github.com/mbundgaard/pi-intercom/issues"
   },
-  "version": "0.6.1",
+  "version": "0.9.0",
   "description": "A coordinator-led workspace for Pi. Delegate to workers with separate contexts, evaluate their reports, and keep the main conversation focused—with the team visible alongside it.",
   "type": "module",
   "keywords": [
@@ -28,6 +28,8 @@
     "dist",
     "README.md",
     "references/observability.md",
+    "references/releasing.md",
+    "references/herdr-core-migration.md",
     "references/roadmap.md",
     "references/v1-specification.md",
     "references/implementation-blocker.md"
@@ -40,7 +42,7 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-coding-agent": "1.4.0",
     "@types/node": "^22.0.0",
     "typebox": "1.3.7",
     "typescript": "^5.9.3"
@@ -49,12 +51,18 @@
     "build": "node -e \"require('node:fs').rmSync('dist', {recursive:true, force:true})\" && tsc",
     "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
-    "test": "npm run build && node --test tests/core.test.mjs tests/integration.test.mjs tests/launcher.test.mjs tests/linux-launcher.test.mjs tests/activity.test.mjs tests/reports.test.mjs tests/worker-status.test.mjs tests/connections.test.mjs tests/handoff.test.mjs tests/pane-close.test.mjs tests/version.test.mjs tests/monitor.test.mjs tests/monitor-view.test.mjs tests/monitor-launcher.test.mjs tests/extension.test.mjs tests/runtime-http.test.mjs tests/resume-storage.test.mjs tests/observability.test.mjs tests/snapshot.test.mjs tests/snapshot-security.test.mjs tests/observability-integration.test.mjs",
+    "test": "npm run build && node --test tests/release.test.mjs tests/release-workflow.test.mjs tests/published-release.test.mjs tests/core.test.mjs tests/root-isolation.test.mjs tests/integration.test.mjs tests/launcher.test.mjs tests/linux-launcher.test.mjs tests/core-launcher.test.mjs tests/core-worker-layout.test.mjs tests/herdr-core.test.mjs tests/activity.test.mjs tests/reports.test.mjs tests/worker-status.test.mjs tests/connections.test.mjs tests/reminders.test.mjs tests/handoff.test.mjs tests/pane-close.test.mjs tests/core-pane-close.test.mjs tests/version.test.mjs tests/monitor.test.mjs tests/monitor-view.test.mjs tests/monitor-launcher.test.mjs tests/core-monitor.test.mjs tests/monitor-settings.test.mjs tests/extension.test.mjs tests/runtime-http.test.mjs tests/resume-storage.test.mjs tests/observability.test.mjs tests/snapshot.test.mjs tests/snapshot-security.test.mjs tests/observability-integration.test.mjs",
     "test:host": "node --test tests/pi-cancellation-probe.test.mjs",
     "test:package": "node --test tests/packaged-monitor.test.mjs",
     "check:package": "npm run build && npm pack --dry-run --ignore-scripts && npm run test:package"
   },
   "dependencies": {
     "pi-intercom-tui": "npm:@earendil-works/pi-tui@0.84.4"
+  },
+  "overrides": {
+    "@earendil-works/pi-coding-agent@1.4.0": {
+      "undici": "8.12.2",
+      "minimatch": "11.0.1"
+    }
   }
 }

package/references/herdr-core-migration.md

@@ -0,0 +1,44 @@
+# Herdr core/app compatibility and validation
+
+## Target topology and tested contracts
+
+- Core: `hc` / `herdr-core` **0.1.18**, running on Linux or Windows.
+- UI: Windows `herdr-app`, local or connected to a remote core.
+- Examined app source: public tag **v0.1.13**, commit `93b097f6e29fcb2d90a30dea2f03ce4e5dee7981`.
+- `HC_TERMINAL_ID` identifies a core terminal, not an app pane or tab. `herdr.space` and `herdr.tab` labels are placement IDs, not names.
+
+## Shared document adapter
+
+The app's `src/mirror_sync.rs` reads/writes its machine-owned `herdr-app` document through core `doc.get`/`doc.set`, using an expected version. `src/mirror.rs` separates shared spaces/tabs/layout from screen-private focus. `src/window.rs` applies document updates and qualifies remote IDs.
+
+Intercom uses this route to change the **actual tab name**, not merely a session title or label. Naming changes only the uniquely mapped worker tab. Launch preflight, terminal creation and dedicated-tab attachment share one bounded verified connection. Conflicts, disconnects and uncertain mutations are not replayed. The coordinator's tab name is preserved.
+
+This is a **source-backed private-format adapter**, not an upstream promise of a stable versioned UI API. Core documents are opaque JSON; core's version does not establish the connected app's version. Rows/columns and terminal/mod blocks are supported; the naming helper also accepts mod-only floats. Monitor layout intentionally requires a narrower float-free subset. Stacks, terminal floats, dynamic content and ambiguous identities fail closed.
+
+Unix uses an explicit `HC_SOCKET`, or the documented default endpoint only if no core config file could override it. This connects without spawning a core. An existing config requires explicit `HC_SOCKET`; its contents are not scraped for credentials. Windows can use an explicit endpoint, otherwise existing-core status is checked before `hc connect`; that preflight is not atomic protection against the core disappearing before connect.
+
+## Monitor and worker closure
+
+Monitor ownership is persisted separately from project configuration, with core/session/caller identities, a token, original argv and terminal creation timestamp. Open supports a top-quarter panel or separate tab without changing private focus state. Old legacy records cannot grant new-core ownership.
+
+Monitor close:
+1. Validate the owned terminal, pane, caller and complete descendant inventory.
+2. Refuse any observed live descendant, including one behind a finished intermediate parent.
+3. Persist `close_pending`, then recheck identity/layout and inventory.
+4. Submit one terminal stop and verify finished state.
+5. CAS-remove only the owned pane, preserving siblings and the coordinator layout.
+6. Verify absence and persist `closed`. Only confirmed closure permits a new open.
+
+This is best-effort, not an atomic compare-and-stop primitive. Core completion may terminate `die_with_parent` children; clients must not concurrently register children against an owned monitor/closing worker. No all-descendants or atomic quiescence guarantee is made. Any uncertainty retains the fence; no automatic retry, cleanup or replacement is permitted.
+
+Linux worker closure additionally checks canonical session headers and process start ticks, and retains the existing successful handoff-result persistence, final settlement and same-epoch commit protocol. Windows worker closure remains disabled because equivalent process-identity proof is not implemented. No graceful cancellation support was enabled.
+
+## Validation boundaries
+
+Local validation covers transport framing/errors, core identity/version checks, CAS conflicts, no-replay behavior, missing/ambiguous layout refusal, quoting/root isolation, ownership, descendant refusal, handoff commit ordering, process-exit observation, monitor close/reopen and sibling preservation. Tests use mocked API connections and disposable files; no real workers are needed.
+
+Adapter fixtures strip inherited `HC_*` and `HERDR_*` variables. A prior development test inherited the coordinator terminal and changed its tab to a fixture name; this was an isolation bug. The owner restored the title to **Main**. The test isolation fix prevents those mocked sessions from accessing the live connection again.
+
+A read-only check verified that the real core's document maps this coordinator to its actual Windows-app tab. That does not establish complete native Windows execution or rendered UI behavior. End-to-end worker startup/reload and Windows rendering still require an authorized live acceptance test. No workers are to be created merely to satisfy this checklist without owner authorization.
+
+No package release, installation or session reload is implied by a successful build.

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

@@ -2,7 +2,7 @@
 
 This is the consolidated **target design**, authoritative over conflicting wording in the original proposal and historical discussion notes. It is not a claim that every capability is currently supported. See [README](../README.md) for current behavior, release evidence and validation limits.
 
-**Current capability exception:** `intercom_stop_worker` and `intercom_close_worker` are registered but disabled on every host, before cancellation/shutdown or outgoing control. Their intended guarantees below remain unchanged; see the [cancellation blocker](implementation-blocker.md). Manual-compaction delivery also has a known acceptance gap: HTTP receipt does not guarantee Pi accepted the input. Unresolved contract questions are not silently approved decisions.
+**Historical design versus current capability:** The original V1 targets below are not a current support matrix. `intercom_stop_worker` and graceful cancellation remain disabled; see the [cancellation blocker](implementation-blocker.md). `intercom_close_worker` now uses a separate Linux-owned-pane handoff/settlement/close workflow, not graceful shutdown. New-core compatibility and its non-atomic closure limits are documented in [Herdr migration](herdr-core-migration.md); current supported behavior is in README. Manual-compaction delivery also has a known acceptance gap: HTTP receipt does not guarantee Pi accepted the input. Unresolved contract questions are not silently approved decisions.
 
 ## 1. Scope and principles
 
@@ -19,20 +19,20 @@ 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:
 
 | Scope | Fields |
 |---|---|
-| Solution | Multiplexer (`herdr` or `none`) |
+| Solution | Multiplexer (`herdr` or `none`); optional monitor preferences `{autoOpen:boolean, placement:'coordinator-tab'|'new-tab'}` (defaults true/coordinator-tab) |
 | Agent | Pi session ID, name, coordinator flag, responsibility description, port |
 | Worker | Project directory relative to coordinator root |
 
@@ -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.
@@ -129,17 +129,20 @@ Every invocation reads the current Pi session ID and shared config, determines r
 | `intercom_request_status` | Coordinator | `to` (name) | Ask worker extension to send independent runtime status report |
 | `intercom_report_status` | Worker, including anonymous | None | Invoke shared reporting function; reject on coordinator |
 | `intercom_stop_worker` | Coordinator | `to` (name) | Target: cancel current work; leave Pi and extension running. Currently disabled; unsupported-host error |
-| `intercom_close_worker` | Coordinator | `to` (name) | Target: cancel work, gracefully exit Pi, preserve session/config. Currently disabled; unsupported-host error |
+| `intercom_close_worker` | Coordinator | `to` (name) | Start a Linux Herdr handoff/settlement/owned-pane close job; preserve registration/history. Not graceful cancellation; unsupported elsewhere |
 | `intercom_resume_worker` | Coordinator | `to` (name) | Launch saved session using configured directory and launcher; failures leave config unchanged |
 | `intercom_remove_worker` | Coordinator | `to` (name) | Remove config entry only; no process stop or session-file deletion |
 | `intercom_set_multiplexer` | Coordinator | `multiplexer` | Set `herdr` or `none` for future launches, including resume |
+| `intercom_open_monitor` | Coordinator | Required `placement` | Open/preserve the monitor in Herdr; ask the user if placement is unknown, never infer from saved settings; explicit opening allows an empty roster |
+| `intercom_close_monitor` | Coordinator | None | Close only the verified owned monitor pane, never an entire tab or a worker |
+| `intercom_configure_monitor` | Coordinator | `autoOpen?`, `placement?` | Persist at least one preference; no immediate pane effects |
 
 ### Tool details
 
 - Configure rejects duplicate names, including `Coordinator`, case-insensitively. Keeping a session's own name is allowed.
 - Configure and reload are deliberately separate. Reload is not Pi's extension-code reload, a process restart, cancellation, or a work assignment. Explain this in tool and user documentation.
 - Reload synchronizes Pi session and applicable Herdr tab names to config.
-- Target contract: stop/close use Pi cancellation and graceful shutdown; no force-kill, automatic commit, or rollback. Close does not require a separate stop call. **Currently both fail closed; no stop or shutdown is performed.**
+- Original target contract: stop/close use Pi cancellation and graceful shutdown. This target remains blocked. The implemented close tool is a separate explicit owned-pane termination workflow, without automatic source commits/rollback or an all-descendants guarantee; it does not enable stop/cancellation.
 - Close success at transport level is not proof that process exit has completed.
 - Remove a running worker only after explicitly closing it; removal itself never closes it.
 - Resume failure must be surfaced; no implicit removal, replacement, or reassignment.

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';
@@ -15,7 +15,15 @@ export interface Agent {
   handoff?: Handoff;
   closeJob?: CloseJob;
 }
-export interface Config { version: 1; multiplexer: 'herdr' | 'none'; agents: Agent[] }
+export interface MonitorSettings { autoOpen: boolean; placement: 'coordinator-tab' | 'new-tab' }
+export interface Config { version: 1; multiplexer: 'herdr' | 'none'; agents: Agent[]; monitor?: MonitorSettings }
+export function monitorSettings(config: Config): MonitorSettings {
+  return config.monitor ? { ...config.monitor } : { autoOpen: true, placement: 'coordinator-tab' };
+}
+export function validateMonitorSettings(value: unknown): asserts value is MonitorSettings {
+  const settings = value as MonitorSettings;
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings) || typeof settings.autoOpen !== 'boolean' || !['coordinator-tab', 'new-tab'].includes(settings.placement) || Object.keys(settings).some(key => !['autoOpen', 'placement'].includes(key))) fail('invalid monitor settings');
+}
 export const DEFAULT_DESCRIPTION = 'Coordinate workers, delegate work, and manage shared configuration.';
 export const key = (name: string) => name.toLowerCase();
 export function fail(message: string): never { throw new Error(`PiIntercom: ${message}`); }
@@ -32,6 +40,7 @@ export function relativeDirectory(value: unknown): asserts value is string {
 export function validateConfig(value: unknown): Config {
   const c = value as Config;
   if (!c || c.version !== 1 || !['herdr', 'none'].includes(c.multiplexer) || !Array.isArray(c.agents)) fail('invalid config schema/version');
+  if (c.monitor !== undefined) validateMonitorSettings(c.monitor);
   const names = new Set<string>(), ids = new Set<string>();
   for (const a of c.agents) {
     if (!a || typeof a.coordinator !== 'boolean') fail('invalid agent');
@@ -80,24 +89,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 +160,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 +170,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 +190,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 +212,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;