@comput/pi-intercom 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# PiIntercom (V1 supported core)
+
+One Windows interactive Pi extension for coordinator and workers. **Intercom communicates; Pi orchestrates.** No automatic assignment, retry, removal, replacement, launcher fallback, commit, or rollback.
+
+**`intercom_stop_worker` and `intercom_close_worker` are disabled.** They throw an unsupported-host error before sending control or calling cancellation/shutdown. Incoming stop/close controls also fail. Pi 0.84.4 leaves retry continuation alive after extension abort. See [blocker](references/implementation-blocker.md). Newer versions are not automatically assumed safe; a verified supported lifecycle API and tests are required before enabling these capabilities.
+
+## Use
+
+Requires Windows, Node 22+, interactive Pi with project trust, and this package's peer dependencies supplied by Pi (`@earendil-works/pi-coding-agent`, `typebox`). Launch the coordinator explicitly from the intended root:
+
+```powershell
+cd D:\Source\YourProject
+pi -e D:\Source\PiIntercom\src\index.ts
+```
+
+Alternatively install from npm:
+
+```powershell
+pi install npm:@comput/pi-intercom
+```
+
+Then start a new Pi session or run `/reload`. Nothing here changes global/project Pi settings automatically. Do not load both the source and built output as separate extensions.
+
+Without shared config, the current working directory becomes the coordinator root. Startup creates `.pi-intercom/config.json`, opens a loopback listener, synchronizes the name `Coordinator`, and waits for user input (no model turn). Existing config is found by walking upward. Invalid/unreadable config is an error and is not overwritten. Unknown session IDs, including forks, are workers, never replacement coordinators.
+
+Default launcher `herdr` requires the coordinator to be inside Herdr (`HERDR_ENV=1` and workspace context), with `herdr` on PATH. Each worker gets **one tab, one pane, no split, no focus change**. The `none` launcher requires `pi.cmd` and Windows PowerShell on PATH and opens a separate visible PowerShell terminal. Missing launcher is an error, not fallback. These launchers have mocked tests but have **not been exercised with live workers**.
+
+## Explicit workflow
+
+1. Coordinator calls `intercom_create_worker({projectDirectory:"."})`. No worker identity, responsibility, callback address or special config path is passed.
+2. Anonymous worker opens its own endpoint and sends its session ID, actual port and root-relative project directory to coordinator Pi. Registration starts a normal coordinator turn when idle or queues steering when busy. It creates **no config entry or hidden pending-registration map**.
+3. Coordinator decides and calls `intercom_configure_worker` with **all five explicit fields**: `sessionId`, `port`, `projectDirectory`, `name`, `description`. This only writes config.
+4. Coordinator separately calls `intercom_reload_worker({to:"Builder"})`. Worker rereads responsibility and synchronizes Pi/Herdr tab names. **This is not Pi `/reload`, a restart, cancellation, or work assignment.** No model turn starts.
+5. Coordinator sends explicit work using `intercom_send({to:"Builder",message:"..."})`. Workers can communicate directly with configured peers. Findings do not authorize unrelated implementation. Progress questions ask for reporting and continuation, not cancellation.
+6. Workers report as instructed and wait, without autonomous exit. Coordinator unavailability does not close the worker or cancel its assignment.
+
+Existing workers restore responsibility by session ID, bind their saved port or an OS-selected fallback, and report their actual port. Coordinator updates existing ports as bookkeeping. Status from removed/unknown sessions notifies Pi but creates no entry. Resume uses the configured project directory and full session ID, with a saved-session lookup first; a never-used Pi session might not yet exist on disk. Failure leaves config unchanged, without fabricated history or forced model turns.
+
+## Tools and permissions
+
+Every tool rereads current config and checks the live Pi session ID. Names are case-insensitive for lookup/uniqueness; display capitalization is preserved. `Coordinator` is reserved.
+
+| Tool | Permission / effect |
+|---|---|
+| `intercom_create_worker` | Coordinator; launch anonymous worker, optional directory defaults to root |
+| `intercom_configure_worker` | Coordinator; explicit five fields above, writes only |
+| `intercom_reload_worker` | Coordinator; named worker's passive config/name reload |
+| `intercom_send` | Configured, responsibility-loaded sessions; named asynchronous message |
+| `intercom_list` | Configured sessions; saved state only, never live health |
+| `intercom_request_status` | Coordinator; ask named worker extension for an independent report |
+| `intercom_report_status` | Workers including anonymous; shared report function, never registration |
+| `intercom_stop_worker`, `intercom_close_worker` | Coordinator role checked, then **unsupported-host error**, no side effects |
+| `intercom_resume_worker` | Coordinator; named saved session, configured launcher/directory |
+| `intercom_remove_worker` | Coordinator; config entry only, no shutdown/session deletion |
+| `intercom_set_multiplexer` | Coordinator; `herdr` or `none`, future launches only |
+
+**Removal precondition:** explicitly close a running worker before removing its entry. Since remote close is disabled, arrange explicit user closure in its terminal first. Intercom does not infer liveness from saved IDs/ports and cannot certify closure. No hidden probing or force-kill is performed.
+
+Anonymous `send`/`list` and all coordinator operations fail explicitly. Anonymous registration and status remain available. A dedicated repeat-registration operation and broader anonymous permissions remain **unresolved contract TODOs**, not silently added tools. If initial registration fails, the worker remains reachable and reports the error locally. Explicit user Pi `/reload` restarts this extension and repeats startup registration; status is not a substitute and there is no automatic retry.
+
+## Config and wire contracts
+
+Shared, source-controlled file: `<root>/.pi-intercom/config.json`. Do not ignore it or split IDs/ports into runtime config. Example **schema only** (not automatically installed placeholder data):
+
+```json
+{
+  "version": 1,
+  "multiplexer": "herdr",
+  "agents": [{
+    "sessionId": "actual-pi-session-id",
+    "name": "Coordinator",
+    "coordinator": true,
+    "description": "Coordinate workers, delegate work, and manage shared configuration.",
+    "port": 49152,
+    "projectDirectory": "."
+  }]
+}
+```
+
+Workers have `coordinator:false` and an existing project directory equal to root or below it. Writes canonicalize directories and check real paths (including symlink escapes). Only coordinator extension operations write config; ordinary Pi file/shell tools are not restricted.
+
+Initial creation writes/fsyncs a complete temporary file then atomically publishes via a no-replace hard link. Contenders see only complete config; exactly one wins. Unsupported hard-link filesystems fail explicitly, without unsafe fallback. Interrupted staging files can remain as ignored `.tmp` files but are never mistaken for config. Updates are serialized, join Pi's file-mutation queue, validate, fsync a temporary file and atomically rename. Duplicate activation of the same coordinator session in multiple processes and external editors racing writes remain outside V1's guarantees (session locks deferred).
+
+HTTP binds **127.0.0.1 only**, `POST /intercom`, UTF-8 JSON, at most 64 KiB. Envelope:
+
+```json
+{"version":1,"kind":"message","from":"sender-session-id","to":"expected-recipient-session-id","payload":{"message":"explicit message"}}
+```
+
+Kinds: `message`, `registration` (`port`, `projectDirectory`), `status` (`port`, `busy`), `request_status`, `reload`, `stop`, `close` (empty control payload). Sender session identity is the envelope `from`; registration/status agent notifications include an explicit `sessionId` field. Agent messages require configured sender and recipient; controls require the current coordinator's sender ID and a worker recipient. Registration/unknown status are intentional exceptions to configured-sender checks, accepted only by coordinator. All receivers verify expected recipient ID, protecting against stale ports reaching another session. Local processes are trusted: this is role validation, **not authentication**. No remote networking/proxies/redirects or credentials.
+
+`202 {"accepted":true}` means extension receipt/acceptance, never model completion. Invalid/unsupported requests return an error; excessive bodies return 413. Request-status sends its report separately after accepting control. Delivery is normal when idle and steering when busy, sampled at arrival. It does not hard-interrupt an executing tool. Each send resolves the recipient again from config; 5-second receipt deadline, **no retries**. Timeout means unknown outcome, not proof of nondelivery. No durable inbox, deduplication or replay log in V1.
+
+Tool text output is bounded to 50 KiB/2000 lines. Full list data remains in the shared config file. Name sync errors are surfaced; startup retains the useful endpoint, and explicit reload reports failure (Pi name/responsibility may already have changed before a Herdr tab rename fails).
+
+## Development and validation
+
+```sh
+npm install --ignore-scripts
+npm run typecheck
+npm test
+npm run check:package
+# Optional installed-host compatibility probe (confirms the known defect):
+PI_INTERCOM_PI_ROOT='C:/path/to/pi-coding-agent' npm run test:host
+```
+
+Production source runs through Pi's TypeScript loader; `npm run build` generates `dist` for tests. Pi core/typebox are peer dependencies, not bundled. This implementation run installed only cached development dependencies offline with `--legacy-peer-deps`, then used local ignored junctions to installed Pi/typebox for validation. No installed dependency, global setting or unrelated project was changed.
+
+Tests use temporary directories, local test-only HTTP servers, and mocked Pi hosts/launch executors. They never start agents, tabs, terminals, contact models, services or bridges, or access credentials.
+
+### Not live-tested / remaining limitations
+
+- Actual Pi extension loading, idle/steering queue delivery, busy snapshots, session-name persistence, trust UI and session replacement/reload lifecycle with live Pi hosts.
+- Herdr tab creation, agent readiness, JSON response shapes, current-pane association and tab rename with live workers. Launcher CLI syntax was checked against installed help only. Herdr's temporary launcher alias is not Intercom/Pi identity and is not saved in config.
+- Windows visible terminal/Pi process startup. Success only proves terminal creation, **not Pi readiness**; startup failures remain visible in that terminal. No live readiness handshake was added.
+- Actual persisted-session lookup and resumed worker startup; never-used session failure.
+- Cross-process/network-drive atomicity and Windows ACL/sharing failures (same-process temp-filesystem races are tested).
+- Stop/close remain disabled on all hosts until a verified cancellation API covers retries, compaction continuations and queues. No workaround or weakened guarantee.
+- Explicit repeat-registration tool and broad anonymous permissions require a contract decision. Duplicate-session locks, takeover, durable logging and non-Windows support are deferred.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@comput/pi-intercom",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "version": "0.1.0",
+  "description": "Explicit local communication between Pi sessions; Pi orchestrates.",
+  "type": "module",
+  "keywords": ["pi-package"],
+  "pi": { "extensions": ["./src/index.ts"] },
+  "files": ["src", "README.md", "references/v1-specification.md", "references/implementation-blocker.md"],
+  "engines": { "node": ">=22" },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": "*", "typebox": "*" },
+  "devDependencies": { "typescript": "^5.9.3", "@types/node": "^22.0.0" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test tests/core.test.mjs tests/integration.test.mjs tests/launcher.test.mjs tests/extension.test.mjs",
+    "test:host": "node --test tests/pi-cancellation-probe.test.mjs",
+    "check:package": "npm pack --dry-run --ignore-scripts"
+  }
+}

package/references/implementation-blocker.md

@@ -0,0 +1,71 @@
+# V1 cancellation capability blocked: Pi cancellation contract
+
+> **Current status:** The user subsequently approved implementing independent features. The supported core now exists; see `implementation-progress.md` and `../README.md`. Only stop/close remain disabled, failing before cancellation/shutdown. The historical feasibility report below is preserved as evidence; its statements that no implementation exists describe the earlier run, not current project status.
+
+## Historical outcome
+
+Implementation was stopped at the API feasibility gate required by the implementation request. **PiIntercom V1 is not implemented.** No package, extension, launcher, transport, or shared configuration has been created. Existing project settings and installed Pi files were not changed.
+
+Installed Pi version inspected: **0.84.4**.
+
+## Concrete blocker
+
+The V1 stop/close contract requires cancelling current work without automatically restarting queued or pending work. In the installed interactive host, extension `ctx.abort()` clears steering/follow-up/compaction message queues, but calls only the low-level agent's `abort()`. It does **not** cancel the separate session retry timer. During retry backoff there is no active low-level agent run to abort. After backoff, Pi continues the previous assignment with `agent.continue()` even though the extension requested cancellation.
+
+`ctx.shutdown()` does not repair this: interactive shutdown waits for session idle, so the automatic continuation can execute before shutdown. Rejecting new HTTP messages during stop/close also cannot cancel this already pending internal continuation.
+
+This is narrower than saying Pi cannot clear queues: queue clearing **does work**, and the probe verifies it. The missing cancellation coverage is the blocker.
+
+Installed source evidence (paths relative to the installed `pi-coding-agent` package):
+
+- `dist/modes/interactive/interactive-mode.js:1451–1456`: extension `abortHandler` calls `restoreQueuedMessagesToEditor({ abort: true })`.
+- Same file, `:3568–3618`: clears queued messages into the editor, then calls `this.agent.abort()`.
+- `node_modules/@earendil-works/pi-agent-core/dist/agent.js:202–204`: abort affects only `activeRun?.abortController`.
+- `dist/core/agent-session.js:2279–2322`: `_prepareRetry()` sleeps using a separate `_retryAbortController`, then returns `true` unless that controller was cancelled.
+- Same file, `:772–795`: post-run loop calls `agent.continue()` following a successful retry wait.
+- `dist/modes/interactive/interactive-mode.js:1507–1512`: shutdown is deferred while the session is busy.
+- Same file, `:2762–2764` and `:2820–2822`: interactive Escape uses separate session cancellation APIs for compaction and retry. Those APIs are not exposed on `ExtensionContext`.
+
+Compaction cancellation also needs validation with an upstream fix; this run reproduced the retry problem specifically, not every compaction case.
+
+## Decision needed
+
+**Recommended:** require a Pi version with a supported extension cancellation operation that cancels active tools/model work, retry backoff, compaction continuations, and queued work as one lifecycle operation. Have that fixed/verified in Pi separately, then resume this implementation. This task does not authorize changing the installed host or an unrelated Pi source project.
+
+Alternatively, explicitly revise the V1 stop/close guarantees to permit best-effort cancellation and possible continuation. That is a semantic change and has not been implemented or assumed approved.
+
+No private-runtime access, repeated abort polling, synthetic Escape input, settings changes disabling retries/compaction, forced shutdown, or hidden recovery has been introduced as a workaround. Intercom communication must remain independent of launcher choice.
+
+## Validation
+
+Added `tests/pi-cancellation-probe.test.mjs`, a dependency-free compatibility probe. It extracts selected installed methods and executes them with mocks; it does not construct a Pi session, read credentials, contact a model, bind a server, launch a process, or modify Herdr.
+
+Git Bash invocation:
+
+```bash
+PI_INTERCOM_PI_ROOT='C:/Users/martin/AppData/Roaming/npm/node_modules/@earendil-works/pi-coding-agent' \
+  node --test tests/pi-cancellation-probe.test.mjs
+```
+
+Actual result: **3 tests passed, 0 failed**:
+
+1. Installed interactive extension abort delegates to the queue-restoration path.
+2. That path clears queued work into the editor and aborts an active low-level run.
+3. During retry backoff, the same path leaves the retry signal un-aborted and `_prepareRetry()` returns `true`, enabling continuation.
+
+The third passing test confirms the **undesired installed behavior**, not V1 compliance. This is a source-backed mocked compatibility probe, not a live end-to-end test. Source-layout changes intentionally fail the probe rather than silently testing different code.
+
+No typecheck/build/package checks are applicable yet: implementation stopped before creating the package. No live Pi worker, Herdr tab, terminal, service, or messaging bridge was started. Herdr commands were help/discovery only.
+
+## Preserved decisions and remaining scope
+
+The authoritative `v1-specification.md` remains unchanged. In particular, the historical review's pending-registration-map suggestion is superseded: registration must deliver ID/port/directory to the coordinator agent; configure takes those explicit values and only writes configuration; reload stays separate. Never-used-session resume failure is already allowed by the authoritative spec and is not reopened here.
+
+Other implementation gaps (explicit registration-repeat operation and anonymous permissions) remain as listed in the authoritative spec. No additional tool contract or permissions decision was silently made while blocked.
+
+`D:/Source/PiIntercom` had no `.git` directory at inspection; `git status` returned “not a git repository”. No repository was initialized and no commit was made.
+
+## Changed paths
+
+- `tests/pi-cancellation-probe.test.mjs` — new compatibility probe.
+- `references/implementation-blocker.md` — this report.

package/references/v1-specification.md

@@ -0,0 +1,183 @@
+# PiIntercom V1 Specification
+
+This is the consolidated record of the agreed V1 design. It supersedes conflicting wording in the original architecture proposal and historical discussion notes. Implementation gaps are listed separately at the end; they are not silently approved decisions.
+
+## 1. Scope and principles
+
+- One Pi extension codebase runs in coordinator and worker sessions.
+- Pi session ID is the underlying identity; do not introduce instance IDs.
+- Names provide human-friendly addressing. Lookup and uniqueness are case-insensitive; preserve capitalization for display.
+- Intercom is a communication extension, not an orchestration engine. The coordinator Pi agent decides assignments, sequencing, and recovery. The extension provides communication and explicit tool operations; it does not choose the workflow.
+- Coordinator manages configuration and delegates work. Workers may communicate directly with peers.
+- Tools perform explicit documented operations. Failure reports do not trigger hidden recovery, replacement, removal, or launcher fallback.
+- Windows only for V1. Launchers: Herdr (default) and `none` (separate visible terminals).
+- No bulk tools in V1. Use existing tools for individual workers.
+
+## 2. Shared configuration
+
+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.
+- 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.
+- 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`) |
+| Agent | Pi session ID, name, coordinator flag, responsibility description, port |
+| Worker | Project directory relative to coordinator root |
+
+Exact schema and versioning remain implementation gaps. Do not treat a saved endpoint or session ID as proof that its process exists.
+
+## 3. Startup and registration
+
+### Coordinator
+
+1. Resolve current session ID and configuration.
+2. With no config, atomically initialize coordinator configuration.
+3. Use name `Coordinator` and default responsibility: `Coordinate workers, delegate work, and manage shared configuration.`
+4. Bind configured port; if unavailable or absent, bind port 0 and use the OS-selected port.
+5. Record its actual port directly in config.
+6. Fix Pi session name and, when hosted in Herdr, tab name to `Coordinator`.
+7. Publish readiness without triggering an agent turn. Wait for user input.
+
+A known session restores its configured role. Any unknown session ID with existing configuration follows worker registration, including forks. No implicit coordinator takeover.
+
+### 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.
+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.
+6. Coordinator agent calls `intercom_configure_worker` to create a named entry with responsibility and reported connection details.
+7. Coordinator agent separately calls `intercom_reload_worker`.
+8. Worker reads its responsibility, synchronizes Pi session and Herdr tab names, and waits for a work prompt.
+
+No worker-specific config path, callback address, instance ID, or preassigned responsibility is passed at launch. No sequential-launch restriction is required for normal creation.
+
+### Existing worker startup/resume
+
+- Read its entry by Pi session ID and restore responsibility.
+- Try configured port; use OS allocation if unavailable.
+- Report actual endpoint to coordinator. Existing-entry port updates are automatic bookkeeping.
+- Fix Pi session and applicable Herdr tab names to configured name.
+- Wait for new instructions, even if previous work was unfinished.
+- Coordinator connection failure is reported but does not prevent the worker's own endpoint from opening.
+
+## 4. Responsibilities and work
+
+- Responsibility describes an agent's remit, not its current task.
+- Loading or reloading responsibility does not start a turn or authorize implementation.
+- Work is assigned by explicit agent messages.
+- Findings may be used within an existing assignment, but do not independently authorize unrelated implementation.
+- After work, report as instructed and wait.
+- Workers continue assigned work and peer communication while coordinator is unreachable.
+- Workers do not autonomously exit upon completion or coordinator shutdown.
+
+## 5. Transport and delivery
+
+- Localhost HTTP, one receiving message endpoint per extension.
+- Bind loopback only. No authentication in V1; local processes are trusted.
+- All application-level messages are asynchronous and one-way. A message may lead to zero, one, or many later messages.
+- HTTP acknowledgment confirms receipt/acceptance or reports transport/validation failure, not agent completion.
+- Reports/results travel as independent messages, never as synchronous agent replies in HTTP responses.
+- Every send rereads config to resolve the current destination endpoint.
+- Agent-facing recipient arguments use names. Transport includes the expected destination session ID, verified by the receiver.
+- Include sender identity and label agent messages with sender and purpose.
+- Incoming coordinator-only controls check sender session ID against current config. This is role validation, not authentication.
+- Receipt timeout is 5 seconds. No automatic retries. A failure or timeout is reported; the agent decides recovery.
+- Dedicated durable message logging is deferred until the basic system works.
+
+### Agent delivery
+
+- Idle recipient: start normal agent turn.
+- Busy recipient: use Pi steering at supported boundaries, not a hard interrupt of executing tools.
+- Determine delivery behavior at arrival; busy is only a snapshot.
+- Progress questions do not cancel existing assignments. Report and continue unless explicitly redirected.
+- Findings use the same delivery path, not a separate context-only inbox.
+
+### Control delivery
+
+- Registration, status reporting, config reload, stop, and close run extension code.
+- Worker's status report contains session ID, bound port, and busy flag; generation needs no worker model turn.
+- One shared worker reporting function is invoked by either its report tool or a coordinator request. Reject use on a coordinator host.
+- Coordinator receiving status updates an existing entry's changed port, then notifies its agent (normal/steering).
+- Unknown/removed session status notifies but does not create config entries. Registration is separate.
+- Routine monitoring should use extension status. Detailed progress uses an agent prompt; checking status first is optional.
+
+## 6. Tools
+
+Every invocation reads the current Pi session ID and shared config, determines role, and checks permission. Unknown sessions never receive coordinator-only privileges.
+
+| Tool | Role | Inputs | Operation |
+|---|---|---|---|
+| `intercom_create_worker` | Coordinator | `projectDirectory?` (default `.`) | Launch new anonymous worker with extension loaded; report launch success/failure without awaiting registration |
+| `intercom_configure_worker` | Coordinator | `sessionId`, `port`, `projectDirectory`, `name`, `description` | Write the explicitly supplied worker configuration; no notification |
+| `intercom_reload_worker` | Coordinator | `to` (name) | Send config-read control only |
+| `intercom_send` | Both | `to` (name), `message` | Deliver agent prompt/steering; return send result, not agent reply |
+| `intercom_list` | Both | None | Reread config; list names, responsibilities, IDs, roles, ports, without live probing |
+| `intercom_request_status` | Coordinator | `to` (name) | Ask worker extension to send independent runtime status report |
+| `intercom_report_status` | Worker | None | Invoke shared reporting function; reject on coordinator |
+| `intercom_stop_worker` | Coordinator | `to` (name) | Cancel current work; leave Pi and extension running |
+| `intercom_close_worker` | Coordinator | `to` (name) | Cancel work, gracefully exit Pi, preserve session/config |
+| `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 |
+
+### 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.
+- Stop/close use Pi cancellation and graceful shutdown; no force-kill, automatic commit, or rollback. Close does not require a separate stop call.
+- 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.
+- Pi may not persist a never-used session until its first assistant response. This is an implementation caveat covered by the existing resume-failure rule, not a change to registration or a separate design decision. Do not force a model turn or fabricate history to persist it.
+- Existing workers are not moved or restarted when launcher configuration changes.
+
+## 7. Launchers
+
+- Default Herdr: one new tab per worker, no splits.
+- `none`: separate visible terminal per worker, not background-only execution.
+- Missing configured multiplexer means a clear launch failure, not fallback.
+- Keep communication independent of launcher choice.
+- Keep launcher interface extensible for future multiplexers/platforms.
+- Session names and tabs track configured agent names; coordinator uses `Coordinator`.
+
+## 8. Explicitly deferred
+
+- Other operating systems and multiplexers.
+- Durable message logging, including storage/retention policy.
+- Duplicate Pi-session activation detection or session-ID locks.
+- Automatic retry queues and recovery orchestration are not V1 behavior.
+- Bulk tools: use individual operations instead.
+
+## 9. Remaining implementation gaps — not new approved behavior
+
+Consolidate these before coding; avoid reopening settled user flows.
+
+1. **Registration handoff — resolved:** deliver reported session ID, port, and project directory into the coordinator Pi context. The coordinator agent decides what to do and supplies all values explicitly to configure_worker. No hidden pending-registration map, placeholder entry, or automatic configuration/reload workflow.
+2. **Retrying anonymous registration:** status reports do not create registrations. Define an explicit way to repeat a failed initial registration without conflating it with known-worker status.
+3. **Wire/config schemas:** finalize schema version, field names, control types, message envelope, validation, body limits, optional message IDs and receipt acknowledgment boundary. No synchronous agent reply semantics.
+4. **Pi lifecycle APIs:** verify extension loading, session-ID resume lookup, cancellation, queued-message treatment on stop/close, busy detection, and session-switch cleanup. Stop must not unexpectedly restart queued work; exact API feasibility needs checking.
+5. **Launch integration:** verify installed Herdr operations and a Windows visible-terminal implementation, including readiness/launch-failure observability and tab association. A successful process launch is not worker registration success.
+6. **Configuration writes:** implement safe serialized/atomic coordinator writes and first-creation race handling. Define bounded handling of incomplete initialization. No malformed-file overwrites.
+7. **Missing coordinator session:** workers report connection failure and remain reachable. Explicit coordinator takeover is not specified or approved; do not invent it.
+8. **Unconfigured worker permissions:** explicitly define allowed worker-side tools before its entry exists, while retaining registration/reporting ability and forbidding coordinator operations.
+9. **Protocol control checks:** distinguish initial registration from configured-sender validation. Reload must reach the anonymous worker after the coordinator has created its entry.
+
+## 10. Implementation documentation and verification
+
+- Read installed Pi documentation and relevant Herdr skills before implementation.
+- Document tool permissions, startup/registration flow, passive responsibility loading, separate configure/reload calls, and failure semantics.
+- Test role gates, port fallback, recipient mismatch, duplicate names, config errors, explicit recovery, and asynchronous steering/status paths.
+- No implementation code has been produced during this design discussion.

package/src/config.ts

@@ -0,0 +1,114 @@
+import { mkdir, readFile, realpath, rename, unlink, open, link, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export interface Agent {
+  sessionId: string;
+  name: string;
+  coordinator: boolean;
+  description: string;
+  port: number;
+  projectDirectory: string;
+}
+export interface Config { version: 1; multiplexer: 'herdr' | 'none'; agents: Agent[] }
+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}`); }
+export function text(value: unknown, field: string, max = 4096): asserts value is string {
+  if (typeof value !== 'string' || !value.trim() || value.length > max || value.includes('\0')) fail(`invalid ${field}`);
+}
+export function port(value: unknown): asserts value is number {
+  if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 65535) fail('invalid port');
+}
+export function relativeDirectory(value: unknown): asserts value is string {
+  text(value, 'projectDirectory');
+  if (path.isAbsolute(value) || path.win32.isAbsolute(value) || value.split(/[\\/]/).includes('..')) fail('projectDirectory must be root-relative, without ..');
+}
+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');
+  const names = new Set<string>(), ids = new Set<string>();
+  for (const a of c.agents) {
+    if (!a || typeof a.coordinator !== 'boolean') fail('invalid agent');
+    text(a.sessionId, 'sessionId', 256); text(a.name, 'name', 128); text(a.description, 'description');
+    if (a.name !== a.name.trim() || /[\r\n\x00-\x1f]/.test(a.name)) fail('invalid name');
+    port(a.port); relativeDirectory(a.projectDirectory);
+    if (names.has(key(a.name)) || ids.has(a.sessionId)) fail('duplicate name or session ID');
+    names.add(key(a.name)); ids.add(a.sessionId);
+    if (a.coordinator ? (a.name !== 'Coordinator' || a.projectDirectory !== '.') : key(a.name) === 'coordinator') fail('reserved Coordinator identity');
+  }
+  if (c.agents.filter(a => a.coordinator).length !== 1) fail('config requires exactly one coordinator');
+  return c;
+}
+export const coordinator = (c: Config) => c.agents.find(a => a.coordinator)!;
+export function named(c: Config, name: string): Agent {
+  text(name, 'to', 128);
+  return c.agents.find(a => key(a.name) === key(name)) ?? fail(`unknown recipient ${name}`);
+}
+export function requireCoordinator(c: Config, id: string): Agent {
+  const a = c.agents.find(a => a.sessionId === id);
+  return a?.coordinator ? a : fail('coordinator permission required');
+}
+export async function directory(root: string, requested: string): Promise<string> {
+  text(requested, 'projectDirectory');
+  const base = await realpath(root), target = await realpath(path.resolve(root, requested));
+  const rel = path.relative(base, target);
+  if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) fail('project directory must be coordinator root or descendant (including symlinks)');
+  if (!(await stat(target)).isDirectory()) fail('projectDirectory is not a directory');
+  return rel.split(path.sep).join('/') || '.';
+}
+export class ConfigStore {
+  readonly file: string;
+  private tail: Promise<unknown> = Promise.resolve();
+  constructor(readonly root: string) { this.file = path.join(root, '.pi-intercom', 'config.json'); }
+  async read(): Promise<Config> {
+    // Missing, malformed and unreadable files propagate; never overwrite them.
+    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;
+    }
+  }
+  private async temporary(config: Config): Promise<string> {
+    validateConfig(config);
+    await mkdir(path.dirname(this.file), { recursive: true });
+    const temp = `${this.file}.${randomUUID()}.tmp`;
+    const handle = await open(temp, 'wx');
+    try { await handle.writeFile(JSON.stringify(config, null, 2) + '\n'); await handle.sync(); }
+    finally { await handle.close(); }
+    return temp;
+  }
+  async initialize(id: string, boundPort: number): Promise<boolean> {
+    // Publish an already complete file using an atomic, no-replace hard link.
+    // Losers only ever see complete JSON; unsupported filesystems fail explicitly.
+    const temp = await this.temporary({ version: 1, multiplexer: 'herdr', agents: [{ sessionId: id, name: 'Coordinator', coordinator: true, description: DEFAULT_DESCRIPTION, port: boundPort, projectDirectory: '.' }] });
+    try { await link(temp, this.file); return true; }
+    catch (e) { if ((e as NodeJS.ErrnoException).code === 'EEXIST') { await this.read(); return false; } throw e; }
+    finally { await unlink(temp); }
+  }
+  async update(id: string, mutate: (config: Config) => void | Promise<void>): Promise<Config> {
+    const operation = this.tail.then(async () => {
+      const c = await this.read(); requireCoordinator(c, id);
+      await mutate(c); validateConfig(c);
+      const temp = await this.temporary(c);
+      try { await rename(temp, this.file); }
+      finally { await unlink(temp).catch(e => { if (e.code !== 'ENOENT') throw e; }); }
+      return c;
+    });
+    this.tail = operation.catch(() => {}); return operation;
+  }
+  async configure(id: string, values: Omit<Agent, 'coordinator'>): Promise<Config> {
+    return this.update(id, async c => {
+      if (values.sessionId === coordinator(c).sessionId) fail('cannot configure coordinator as worker');
+      const projectDirectory = await directory(this.root, values.projectDirectory);
+      const a: Agent = { sessionId: values.sessionId, name: values.name, description: values.description, port: values.port, projectDirectory, coordinator: false };
+      const index = c.agents.findIndex(old => old.sessionId === a.sessionId);
+      if (index < 0) c.agents.push(a); else c.agents[index] = a;
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+import { fileURLToPath } from 'node:url';
+import { Type, type TSchema } from 'typebox';
+import { SessionManager, truncateHead, withFileMutationQueue, type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { ConfigStore } from './config.js';
+import { Intercom, UNSUPPORTED_CANCELLATION } from './runtime.js';
+import { launchers } from './launcher.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()) })],
+  ['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 }) })],
+  ['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_status', 'Worker only (including anonymous). Send runtime sessionId/port/busy report to coordinator. This is NOT registration and creates no config entry.', Type.Object({})],
+  ['stop_worker', UNSUPPORTED_CANCELLATION, to],
+  ['close_worker', UNSUPPORTED_CANCELLATION, to],
+  ['resume_worker', 'Coordinator only. Launch saved session by ID in configured directory. No replacement/removal on failure; no old assignment is automatically started.', to],
+  ['remove_worker', 'Coordinator only. Remove config entry only; never stop process or delete session files. A running worker must be explicitly closed before removal. Stop/close are disabled on current host: arrange explicit user closure first.', to],
+  ['set_multiplexer', 'Coordinator only. Set herdr (default) or none (separate visible Windows terminals) for future launches. Never move/restart existing workers or fall back.', Type.Object({ multiplexer: Type.String({ enum: ['herdr', 'none'] }) })],
+];
+
+// Participate in Pi's own per-file mutation queue as well as Intercom serialization.
+class PiConfigStore extends ConfigStore {
+  override update(id: string, mutate: Parameters<ConfigStore['update']>[1]) {
+    return withFileMutationQueue(this.file, () => super.update(id, mutate));
+  }
+}
+export default function intercomExtension(pi: ExtensionAPI): void {
+  let runtime: Intercom | undefined;
+  let context: ExtensionContext | undefined;
+  const launcher = launchers({
+    extension: fileURLToPath(import.meta.url),
+    sessionExists: async (cwd, id) => (await SessionManager.list(cwd, process.env.PI_CODING_AGENT_SESSION_DIR)).some(s => s.id === id),
+  });
+  pi.on('session_start', async (_event, ctx) => {
+    await runtime?.close(); context = ctx;
+    if (process.platform !== 'win32' || ctx.mode !== 'tui') throw new Error('PiIntercom V1 requires Windows interactive Pi. No resources started.');
+    if (!ctx.isProjectTrusted()) throw new Error('PiIntercom requires project trust before honoring shared project configuration.');
+    runtime = new Intercom({
+      cwd: ctx.cwd,
+      sessionId: () => context!.sessionManager.getSessionId(),
+      busy: () => !context!.isIdle(),
+      deliver: (content, busy) => pi.sendUserMessage(content, busy ? { deliverAs: 'steer' } : undefined),
+      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) });
+    try { await runtime.start(); }
+    catch (e) { runtime = undefined; ctx.ui.notify(String(e), 'error'); }
+  });
+  pi.on('session_shutdown', async () => { await runtime?.close(); runtime = undefined; context = undefined; });
+  pi.on('before_agent_start', async (event, ctx) => {
+    context = ctx;
+    if (!runtime) return;
+    const { me } = await runtime.state();
+    const loaded = runtime.responsibility;
+    return { systemPrompt: event.systemPrompt + '\n\nPiIntercom: communicates; Pi decides orchestration. Responsibility is not a work assignment. Do not implement unrelated work from findings. After assigned work, report as instructed and wait; do not autonomously exit. Progress questions require reporting and continuing unless explicitly redirected. stop_worker/close_worker are disabled due to host cancellation blocker.\n' + (me && loaded ? `Identity: ${loaded.name} (${me.sessionId}). Responsibility: ${loaded.description}.` : 'Anonymous/unloaded worker: wait for coordinator configuration and separate reload; do not treat registration as authorization to work.') };
+  });
+  for (const [operation, description, parameters] of tools) {
+    pi.registerTool({
+      name: `intercom_${operation}`, label: `Intercom ${operation}`, description, parameters,
+      async execute(_id, args, signal, _update, ctx) {
+        signal?.throwIfAborted(); context = ctx;
+        if (!runtime) throw new Error('PiIntercom not initialized; inspect startup error.');
+        const result = await runtime.tool(operation, args as Record<string, unknown>);
+        const output = truncateHead(JSON.stringify(result, null, 2));
+        return { content: [{ type: 'text', text: output.content + (output.truncated ? `\n[Truncated; full shared configuration: ${runtime.store.file}]` : '') }], details: {} };
+      },
+    });
+  }
+}

package/src/launcher.ts

@@ -0,0 +1,61 @@
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { promisify } from 'node:util';
+import { fail } from './config.js';
+import type { LaunchRequest } from './runtime.js';
+
+export type Run = (file: string, args: string[]) => Promise<string>;
+export const run: Run = async (file, args) => {
+  const { stdout } = await promisify(execFile)(file, args, { windowsHide: true, timeout: 40000, maxBuffer: 1024 * 1024 });
+  return stdout;
+};
+export const psQuote = (value: string) => `'${value.replaceAll("'", "''")}'`;
+export const encoded = (script: string) => Buffer.from(script, 'utf16le').toString('base64');
+export interface LauncherOptions {
+  extension: string;
+  platform?: string;
+  env?: NodeJS.ProcessEnv;
+  run?: Run;
+  sessionExists(cwd: string, id: string): Promise<boolean>;
+}
+export function launchers(options: LauncherOptions) {
+  const exec = options.run ?? run, env = options.env ?? process.env;
+  async function launch(request: LaunchRequest): Promise<unknown> {
+    if ((options.platform ?? process.platform) !== 'win32') fail('V1 launchers support Windows only');
+    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] : [])];
+    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 } } };
+      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`); }
+      const pane = created.result?.root_pane?.pane_id, tab = created.result?.tab?.tab_id;
+      if (!pane || !tab) fail('Herdr creation response missing returned pane/tab IDs; no guessed targeting or cleanup');
+      // Herdr requires a unique lowercase launcher alias. This is not Pi identity,
+      // is never stored in Intercom config/wire, and assigns no responsibility.
+      const alias = `intercom-${randomBytes(6).toString('hex')}`;
+      try { await exec('herdr', ['agent', 'start', alias, '--kind', 'pi', '--pane', pane, '--timeout', '30000', '--', ...args]); }
+      catch (e) { fail(`Herdr agent launch failed in tab ${tab}, pane ${pane}: ${String(e)}. Tab/process may remain; no automatic cleanup/retry/replacement`); }
+      return { launched: true, tab, pane, registrationAwaited: false };
+    }
+    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 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());
+    if (!Number.isInteger(pid) || pid <= 0) fail('visible terminal launch returned no process ID; outcome unknown');
+    return { terminalLaunched: true, pid, piReadiness: 'not observed; inspect visible terminal for startup failures', registrationAwaited: false };
+  }
+  async function syncName(name: string): Promise<void> {
+    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');
+    const data = JSON.parse(await exec('herdr', ['pane', 'current', '--current']));
+    const tab = data.result?.pane?.tab_id;
+    if (typeof tab !== 'string') fail('Herdr current-pane response missing tab_id; tab name not synchronized');
+    await exec('herdr', ['tab', 'rename', tab, name]);
+  }
+  return { launch, syncName };
+}

package/src/runtime.ts

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import { ConfigStore, coordinator, directory, fail, named, requireCoordinator, type Agent, type Config } from './config.js';
+import { listen, send, type Endpoint, type Envelope, type Kind } from './transport.js';
+
+export const UNSUPPORTED_CANCELLATION = 'Unsupported Pi host: stop_worker and close_worker are disabled. Pi 0.84.4 extension abort does not cancel retry backoff/continuations; graceful shutdown cannot guarantee no queued work restarts. No cancellation or shutdown was performed. See references/implementation-blocker.md. A verified supported host API is required (no version-only override).';
+export interface Host {
+  sessionId(): string;
+  cwd: string;
+  busy(): boolean;
+  deliver(text: string, busy: boolean): void;
+  setName(name: string): Promise<void>;
+  notify(text: string): void;
+}
+export interface LaunchRequest { multiplexer: 'herdr' | 'none'; cwd: string; sessionId?: string }
+export interface RuntimeOptions {
+  launch(request: LaunchRequest): Promise<unknown>;
+  listen?: typeof listen;
+  send?: typeof send;
+  store?: (root: string) => ConfigStore;
+}
+export class Intercom {
+  store!: ConfigStore;
+  endpoint?: Endpoint;
+  private active = false;
+  private initialId = '';
+  responsibility?: Agent;
+  constructor(readonly host: Host, readonly options: RuntimeOptions) {}
+  private id(): string {
+    const id = this.host.sessionId();
+    if (!this.active || id !== this.initialId) fail('session is inactive or replaced');
+    return id;
+  }
+  async start(): Promise<void> {
+    this.initialId = this.host.sessionId(); this.active = true;
+    try {
+      const discovered = await ConfigStore.discover(this.host.cwd);
+      this.store = this.options.store?.(discovered?.root ?? this.host.cwd) ?? discovered ?? new ConfigStore(this.host.cwd);
+      const previous = discovered ? await this.store.read() : undefined;
+      const own = previous?.agents.find(a => a.sessionId === this.id());
+      this.endpoint = await (this.options.listen ?? listen)(own?.port, m => this.receive(m));
+      if (!previous) await this.store.initialize(this.id(), this.endpoint.port);
+      const config = await this.store.read();
+      const me = config.agents.find(a => a.sessionId === this.id());
+      if (me?.coordinator) {
+        await this.store.update(this.id(), c => { requireCoordinator(c, this.id()).port = this.endpoint!.port; });
+        try { await this.reload(); } catch (e) { this.host.notify(`Name/responsibility synchronization failed: ${String(e)}`); }
+        this.host.notify(`Intercom Coordinator ready at 127.0.0.1:${this.endpoint.port}; waiting for user input.`);
+      } else {
+        if (me) { try { await this.reload(); } catch (e) { this.host.notify(`Name/responsibility synchronization failed: ${String(e)}`); } }
+        try {
+          if (me) await this.report();
+          else await this.transmit(coordinator(config).name, 'registration', { port: this.endpoint.port, projectDirectory: await directory(this.store.root, this.host.cwd) });
+        } catch (e) { this.host.notify(`Coordinator unreachable/registration failed; worker remains reachable: ${String(e)}. No retry. Anonymous registration repeat is an unresolved contract; use explicit Pi /reload to restart this extension, not report_status.`); }
+        this.host.notify(`Intercom worker ready at 127.0.0.1:${this.endpoint.port}; waiting for explicit work.`);
+      }
+    } catch (e) { await this.close(); throw e; }
+  }
+  async close(): Promise<void> {
+    this.active = false;
+    const endpoint = this.endpoint; this.endpoint = undefined;
+    if (endpoint) await endpoint.close();
+    this.responsibility = undefined;
+  }
+  async state(): Promise<{ id: string; config: Config; me?: Agent }> {
+    const id = this.id(), config = await this.store.read();
+    this.id();
+    return { id, config, me: config.agents.find(a => a.sessionId === id) };
+  }
+  async reload(): Promise<void> {
+    const { me } = await this.state();
+    if (!me) fail('worker not configured; configure_worker must run before reload_worker');
+    this.responsibility = { ...me };
+    await this.host.setName(me.name);
+    this.host.notify(`Intercom responsibility loaded for ${me.name}; no work turn started.`);
+  }
+  async transmit(to: string, kind: Kind, payload: Record<string, unknown> = {}): Promise<void> {
+    const { id, config } = await this.state();
+    const target = named(config, to);
+    await (this.options.send ?? send)(target.port, { version: 1, from: id, to: target.sessionId, kind, payload });
+  }
+  async report(): Promise<void> {
+    const { config, me } = await this.state();
+    if (me?.coordinator) fail('report_status is worker-only');
+    if (!this.endpoint) fail('endpoint unavailable');
+    await this.transmit(coordinator(config).name, 'status', { port: this.endpoint.port, busy: this.host.busy() });
+  }
+  async receive(message: Envelope): Promise<void> {
+    const { id, config, me } = await this.state();
+    if (message.to !== id) fail('recipient session ID mismatch (stale endpoint)');
+    const sender = config.agents.find(a => a.sessionId === message.from);
+    const busy = this.host.busy();
+    const notify = (purpose: string, content: string) => {
+      this.id();
+      this.host.deliver(`[Intercom ${purpose} from ${sender?.name ?? 'unconfigured worker'} (${message.from})]\n${content}`, busy);
+    };
+    if (message.kind === 'registration' || message.kind === 'status') {
+      requireCoordinator(config, id);
+      if (sender?.coordinator) fail('coordinator cannot report as worker');
+      if (message.kind === 'registration') {
+        const projectDirectory = await directory(this.store.root, message.payload.projectDirectory as string);
+        // No pending map, placeholder or configuration mutation.
+        notify('registration', JSON.stringify({ sessionId: message.from, port: message.payload.port, projectDirectory }) + '\nThis is connection information, not a work assignment. Configure explicitly, then reload separately.');
+      } else {
+        if (sender) await this.store.update(id, c => {
+          const entry = c.agents.find(a => a.sessionId === message.from && !a.coordinator);
+          if (entry) entry.port = message.payload.port as number;
+        });
+        notify('status', JSON.stringify({ sessionId: message.from, port: message.payload.port, busy: message.payload.busy, configured: !!sender }));
+      }
+      return;
+    }
+    if (message.kind === 'message') {
+      if (!sender || !me) fail('agent messaging requires configured sender and recipient; anonymous permissions TODO');
+      if (!this.responsibility) fail('worker must load responsibility before receiving work');
+      notify('agent message', message.payload.message as string); return;
+    }
+    if (!sender?.coordinator) fail('control requires current coordinator sender session ID');
+    if (me?.coordinator) fail('worker control cannot target coordinator');
+    if (message.kind === 'stop' || message.kind === 'close') fail(UNSUPPORTED_CANCELLATION);
+    if (message.kind === 'reload') { await this.reload(); return; }
+    if (message.kind === 'request_status') {
+      // Independent one-way report, never a synchronous status in the HTTP response.
+      setImmediate(() => { if (this.active) void this.report().catch(e => this.host.notify(`Status report failed: ${String(e)}`)); });
+      return;
+    }
+    fail('unsupported control');
+  }
+  async tool(operation: string, args: Record<string, unknown>): Promise<unknown> {
+    const { id, config, me } = await this.state();
+    if (operation === 'list') {
+      if (!me) fail('anonymous intercom_list permissions unresolved (TODO); no coordinator privileges');
+      return config;
+    }
+    if (operation === 'report_status') { await this.report(); return { accepted: true }; }
+    if (operation === 'send') {
+      if (!me || !this.responsibility) fail('anonymous/unloaded worker cannot send agent messages (permissions TODO)');
+      await this.transmit(args.to as string, 'message', { message: args.message }); return { accepted: true, completion: 'not awaited' };
+    }
+    requireCoordinator(config, id);
+    if (operation === 'stop_worker' || operation === 'close_worker') fail(UNSUPPORTED_CANCELLATION);
+    if (operation === 'configure_worker') {
+      await this.store.configure(id, args as unknown as Omit<Agent, 'coordinator'>);
+      return { written: true, reloaded: false };
+    }
+    if (operation === 'set_multiplexer') {
+      await this.store.update(id, c => { c.multiplexer = args.multiplexer as Config['multiplexer']; }); return { written: true };
+    }
+    if (operation === 'create_worker') {
+      const relative = await directory(this.store.root, (args.projectDirectory as string | undefined) ?? '.');
+      return this.options.launch({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative) });
+    }
+    const target = named(config, args.to as string);
+    if (target.coordinator) fail('operation requires a worker target');
+    if (operation === 'reload_worker' || operation === 'request_status') {
+      await this.transmit(target.name, operation === 'reload_worker' ? 'reload' : 'request_status');
+      return { accepted: true, completion: 'not awaited' };
+    }
+    if (operation === 'resume_worker') {
+      const relative = await directory(this.store.root, target.projectDirectory);
+      return this.options.launch({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), sessionId: target.sessionId });
+    }
+    if (operation === 'remove_worker') {
+      // No live process claim: the caller must explicitly ensure closure first.
+      await this.store.update(id, c => { c.agents = c.agents.filter(a => a.sessionId !== target.sessionId); });
+      return { removed: true, processStopped: false, sessionDeleted: false };
+    }
+    fail(`unknown operation ${operation}`);
+  }
+}

package/src/transport.ts

@@ -0,0 +1,78 @@
+import http from 'node:http';
+import { fail, port, text } from './config.js';
+
+export const BODY_LIMIT = 64 * 1024;
+export const RECEIPT_TIMEOUT = 5000;
+export type Kind = 'message' | 'registration' | 'status' | 'request_status' | 'reload' | 'stop' | 'close';
+export interface Envelope {
+  version: 1;
+  kind: Kind;
+  from: string;
+  to: string;
+  payload: Record<string, unknown>;
+}
+export function envelope(value: unknown): Envelope {
+  const m = value as Envelope;
+  if (!m || m.version !== 1 || !['message', 'registration', 'status', 'request_status', 'reload', 'stop', 'close'].includes(m.kind)) fail('invalid wire schema/version/kind');
+  text(m.from, 'sender sessionId', 256); text(m.to, 'recipient sessionId', 256);
+  if (!m.payload || Array.isArray(m.payload) || typeof m.payload !== 'object') fail('invalid payload');
+  if (m.kind === 'message') text(m.payload.message, 'message', 48000);
+  if (m.kind === 'registration' || m.kind === 'status') port(m.payload.port);
+  if (m.kind === 'registration') text(m.payload.projectDirectory, 'projectDirectory');
+  if (m.kind === 'status' && typeof m.payload.busy !== 'boolean') fail('invalid busy flag');
+  return m;
+}
+export interface Endpoint { port: number; close(): Promise<void> }
+export async function listen(preferred: number | undefined, accept: (message: Envelope) => Promise<void>): Promise<Endpoint> {
+  const server = http.createServer(async (req, res) => {
+    const reply = (status: number, data: unknown) => { if (!res.destroyed) { res.writeHead(status, { 'content-type': 'application/json', connection: 'close' }); res.end(JSON.stringify(data)); } };
+    if (req.method !== 'POST' || req.url !== '/intercom') { reply(404, { error: 'POST /intercom required' }); req.resume(); return; }
+    let bytes = 0;
+    const chunks: Buffer[] = [];
+    try {
+      for await (const chunk of req) {
+        bytes += chunk.length;
+        if (bytes > BODY_LIMIT) { reply(413, { error: 'body exceeds 64 KiB' }); return; }
+        chunks.push(Buffer.from(chunk));
+      }
+      await accept(envelope(JSON.parse(Buffer.concat(chunks).toString('utf8'))));
+      reply(202, { accepted: true });
+    } catch (error) { reply(400, { error: String(error) }); }
+  });
+  server.requestTimeout = RECEIPT_TIMEOUT;
+  server.headersTimeout = RECEIPT_TIMEOUT;
+  server.setTimeout(RECEIPT_TIMEOUT, socket => socket.destroy());
+  const bind = (p: number) => new Promise<void>((resolve, reject) => {
+    const error = (e: Error) => { server.off('listening', ready); reject(e); };
+    const ready = () => { server.off('error', error); resolve(); };
+    server.once('error', error); server.once('listening', ready); server.listen(p, '127.0.0.1');
+  });
+  try { await bind(preferred ?? 0); }
+  catch (e) { if (preferred && (e as NodeJS.ErrnoException).code === 'EADDRINUSE') await bind(0); else throw e; }
+  const address = server.address();
+  if (!address || typeof address === 'string') fail('listener has no port');
+  return { port: address.port, close: () => new Promise((resolve, reject) => {
+    server.close(e => e ? reject(e) : resolve()); server.closeAllConnections();
+  }) };
+}
+export async function send(destinationPort: number, message: Envelope, timeout = RECEIPT_TIMEOUT): Promise<void> {
+  port(destinationPort); envelope(message);
+  const body = JSON.stringify(message);
+  if (Buffer.byteLength(body) > BODY_LIMIT) fail('message exceeds 64 KiB');
+  // Node HTTP bypasses proxy environment variables; never redirects or retries.
+  await new Promise<void>((resolve, reject) => {
+    const req = http.request({ hostname: '127.0.0.1', port: destinationPort, path: '/intercom', method: 'POST', headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) } }, res => {
+      let result = '';
+      res.on('data', chunk => { result += chunk; if (result.length > BODY_LIMIT) req.destroy(new Error('oversized acknowledgment')); });
+      res.on('error', reject);
+      res.on('end', () => {
+        try {
+          if (res.statusCode !== 202 || JSON.parse(result).accepted !== true) fail(`receipt rejected (${res.statusCode}): ${result}`);
+          resolve();
+        } catch (e) { reject(e); }
+      });
+    });
+    const timer = setTimeout(() => req.destroy(new Error('PiIntercom: receipt timeout; outcome unknown; no automatic retry')), timeout);
+    req.on('close', () => clearTimeout(timer)); req.on('error', reject); req.end(body);
+  });
+}