@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/docs/intercom.md

@@ -14,7 +14,7 @@ Sometimes you're running multiple pi sessions — one researching, one executing
 - **Agent collaboration** — An agent can reach out to another session when it needs help or wants to share results
 - **Session awareness** — See what other pi sessions are running and their current status
 
-Unlike pi-messenger (a shared chat room for multi-agent swarms), pi-intercom is for targeted 1:1 communication where you pick the recipient.
+Intercom sends direct messages to the session you choose.
 
 Intercom is bundled with `pi-subagents`: delegated child agents get a child-only `contact_supervisor` tool when the subagent extension supplies bridge metadata. Use blocking `need_decision` or `interview_request` only when the ephemeral child cannot safely continue and must remain alive for the reply. Use `progress_update` only for a discovery or change the supervisor needs while working. It steers at the next tool boundary; skip starts, redundant narration, and routine completion, and retain material findings in the final result. Fresh normal sessions see `load_intercom`, a small entry that enables the full `intercom` tool without sending or checking anything.
 
@@ -32,21 +32,19 @@ Intercom requires Pi **1.0.0** and Node **24.21.0** or later. No Pi fork is requ
 pi install npm:@fitchmultz/pi-subagents
 ```
 
-**The unscoped npm package `pi-subagents` is not this project.** Use `@fitchmultz/pi-subagents`.
-
-Git fallback (existing tags and branches remain installable):
+Install from Git:
 
 ```bash
 pi install git:github.com/fitchmultz/pi-subagents
 ```
 
-That one package includes both extension entries and both skills. For a local checkout, follow the [runtime-only install and rebuild recipe](../README.md#installation): run `npm install --omit=dev` before registering or loading it, including after development validation. Before rebuilding or updating an in-use Pi checkout or extension, checkpoint work and fully quit every Pi session using that installation. Update from a separate terminal, then restart Pi and resume the same saved parent session to retain ownership and pending coordination. `/reload` refreshes supported settings, skills, and prompts but is not a reliable code-update boundary.
+That one package includes both extension entries and both skills. For a local checkout, follow the [runtime-only install and rebuild recipe](reference.md#installation): run `npm install --omit=dev` before registering or loading it, including after development validation. Before rebuilding or updating an in-use Pi checkout or extension, checkpoint work and fully quit every Pi session using that installation. Update from a separate terminal, then restart Pi and resume the same saved parent session to retain ownership and pending coordination. `/reload` refreshes supported settings, skills, and prompts but is not a reliable code-update boundary.
 
 To restart the shared broker too, close every Pi session using the same agent directory and wait at least five seconds before reopening Pi.
 
 ## Development
 
-Follow the [local validation instructions](../README.md#local-validation). Keep retained/cleared custom-queue, rejected-input and pre-admission preparation regressions intact and report results for the exact selected host; earlier published Pi 0.87.1 failures are historical evidence, not current 1.0 certification.
+Follow the [local validation instructions](development.md#local-validation). Keep retained/cleared custom-queue, rejected-input and pre-admission preparation regressions intact and report results for the exact selected host; earlier published Pi 0.87.1 failures are historical evidence, not current 1.0 certification.
 
 `ci` runs typechecking, package and install smokes, and the full subagent/intercom test suite. The native intercom regression uses real SDK sessions, a controlled provider, and private runtime directories without credentials or model-service calls. To run just that regression:
 
@@ -67,6 +65,7 @@ The `--llm` mode copies local `auth.json` and `models.json` into the isolated Pi
 Pi-intercom automatically gives ordinary agents a bounded presence hint when another connected session is working in the same Git repository, including separate worktrees. The hint is a constant count-free string; agents load `load_intercom({})` if needed, then use `intercom({ action: "list" })` before changing shared state or coordinating known overlapping work. Routine standalone read-only tasks do not need a peer check. No message is sent automatically. This guidance applies on official Pi and the fork; broker presence, delivery, approvals, and child recovery are unchanged. Both the tool and `/intercom` overlay default to that repository/worktree scope. Use `intercom({ action: "list", scope: "all" })` or `/intercom all` only when intentionally discovering sessions in other projects. Managed `pi-subagents` children keep their dedicated supervisor channel instead of receiving the peer hint. Project matching is an advisory presence signal, not an authorization boundary. Add project instructions only when you want a stricter mandatory coordination policy.
 
 A session becomes intercom-connected when all of these are true:
+
 - the bundled intercom extension is enabled through `pi config`
 - the session has been restarted after the extension was installed or updated
 - the local broker is running or can be auto-started
@@ -79,7 +78,7 @@ If a session is unnamed, pi-intercom now exposes a runtime-only fallback alias l
 
 ### From the Keyboard
 
-With `pi-subagents`, **Option+Shift+M** (**Alt+Shift+M**) opens your task-labelled agent conversations first; press it again to close. The shortcut is configurable below. In native fullscreen mode, clicking the **Agents** entrance again also closes the open view. See [the agent-view controls](../README.md#try-this-first) for direct human messaging, context replies, saved drafts, unread history, pinning, selected-child stop and explicit continuation. The plain `/intercom` command remains the current-project peer list. Type `/intercom all` to include sessions in other projects:
+With `pi-subagents`, **Option+Shift+M** (**Alt+Shift+M**) opens your task-labelled agent conversations first; press it again to close. The shortcut is configurable below. In native fullscreen mode, clicking the **Agents** entrance again also closes the open view. See [the agent-view controls](reference.md#try-this-first) for direct human messaging, context replies, saved drafts, unread history, pinning, selected-child stop and explicit continuation. The plain `/intercom` command remains the current-project peer list. Type `/intercom all` to include sessions in other projects:
 
 1. **Select a session** — Use arrow keys to pick a target session
 2. **Compose message** — Write your message in the compose overlay. Pasted multiline handoffs are preserved.
@@ -91,11 +90,24 @@ With `pi-subagents`, **Option+Shift+M** (**Alt+Shift+M**) opens your task-labell
 Subscribe explicitly to an exact topic; there are no automatic subscriptions or wildcard broadcasts. Topics span connected local sessions, so use a project/resource-specific name unless cross-project coordination is intended. Publications are self-contained latest state, not deltas. Each sender has one current record per topic; older queued versions cannot replace a newer record. Same-session subscriptions, publications and received records use native session entries. Late subscribers read current published state without replaying earlier interruptions.
 
 ```typescript
-intercom({ action: "subscribe", topic: "browser/shared-profile/tab-4", awaitRelease: true })
-intercom({ action: "publish", topic: "browser/shared-profile/tab-4", resource: "tab-4", ownership: "held", message: "Reviewing the sign-in flow; keep this tab open." })
-intercom({ action: "topics", topic: "browser/shared-profile/tab-4" })
-intercom({ action: "publish", topic: "browser/shared-profile/tab-4", event: "release", resource: "tab-4", ownership: "released", message: "Sign-in check complete; this tab is available." })
-intercom({ action: "unsubscribe", topic: "browser/shared-profile/tab-4" })
+intercom({ action: "subscribe", topic: "browser/shared-profile/tab-4", awaitRelease: true });
+intercom({
+  action: "publish",
+  topic: "browser/shared-profile/tab-4",
+  resource: "tab-4",
+  ownership: "held",
+  message: "Reviewing the sign-in flow; keep this tab open.",
+});
+intercom({ action: "topics", topic: "browser/shared-profile/tab-4" });
+intercom({
+  action: "publish",
+  topic: "browser/shared-profile/tab-4",
+  event: "release",
+  resource: "tab-4",
+  ownership: "released",
+  message: "Sign-in check complete; this tab is available.",
+});
+intercom({ action: "unsubscribe", topic: "browser/shared-profile/tab-4" });
 ```
 
 Routine `event: "update"` publications replace quiet inspectable state; they do not become passive conversation messages or wake a model. Inspect current records and declared resource ownership in **`/intercom topics`** or `intercom({ action: "topics" })`; topic state does not appear in the footer. Ownership is advisory, not an exclusive lock; disconnect means **unavailable/disconnected**, never an implied release.
@@ -110,9 +122,9 @@ The agent can list sessions and send messages using the `intercom` tool. Tool ca
 
 ```typescript
 // Enable the peer tool if it is not already available
-load_intercom({})
+load_intercom({});
 // List connected sessions in this repository and its worktrees
-intercom({ action: "list" })
+intercom({ action: "list" });
 // → **Current session:**
 // → • executor (20d43841) — ~/projects/api (claude-sonnet-4) [self, idle, state:idle, accepts_asks:true, pending_asks:0, last_intercom_activity:none]
 // →   ↳ self target unavailable; choose a peer from Other sessions; use pending/reply for inbound asks
@@ -121,14 +133,18 @@ intercom({ action: "list" })
 // →   ↳ send defaults to steer; ask only if sender must stay alive for a required reply (default sends without waiting when peer is busy); queue only for intentional delay; passive discouraged
 
 // Intentionally discover sessions in other projects
-intercom({ action: "list", scope: "all" })
+intercom({ action: "list", scope: "all" });
 
 // Send live guidance without blocking this long-lived session; send defaults to steer
-intercom({ action: "send", to: "research", message: "Check if UserService.validate() handles null. Send the finding back." })
+intercom({
+  action: "send",
+  to: "research",
+  message: "Check if UserService.validate() handles null. Send the finding back.",
+});
 // → Message sent to research. This session can end its turn or continue independent work.
 
 // Check connection status and the same live recipient guidance
-intercom({ action: "status" })
+intercom({ action: "status" });
 // → Connected: Yes, Session ID: abc123, Active sessions: 3
 // → Current session and other-session rows follow.
 
@@ -137,18 +153,20 @@ intercom({
   action: "send",
   to: "worker",
   message: "Here's the fix:",
-  attachments: [{
-    type: "snippet",
-    name: "auth.ts",
-    language: "typescript",
-    content: "function validate(user: User) { ... }"
-  }]
-})
+  attachments: [
+    {
+      type: "snippet",
+      name: "auth.ts",
+      language: "typescript",
+      content: "function validate(user: User) { ... }",
+    },
+  ],
+});
 ```
 
 ### Receiving Messages
 
-With native [compact view](../README.md#compact-view) enabled, ordinary incoming messages use one content row plus Pi's blank line. In native fullscreen mode, click a collapsed row to reveal its full message and attachments; click it again to collapse. Ctrl+O (or the configured tool-expansion key) still expands all messages. Questions, reply guidance, and needs-attention notices stay prominent. The mode defaults off and does not change delivery or model-visible content.
+With native [compact view](reference.md#compact-view) enabled, ordinary incoming messages use one content row plus Pi's blank line. In native fullscreen mode, click a collapsed row to reveal its full message and attachments; click it again to collapse. Ctrl+O (or the configured tool-expansion key) still expands all messages. Questions, reply guidance, and needs-attention notices stay prominent. The mode defaults off and does not change delivery or model-visible content.
 
 When a message arrives, it appears inline in your chat with the sender's info. The cwd label is the sender's **Native session cwd**, not proof of a command's physical directory. Messages sent with `ask` include a reply hint:
 
@@ -189,7 +207,7 @@ Open two terminals and start pi in each. Name them so they can find each other:
 Verify they see each other from either session:
 
 ```typescript
-intercom({ action: "list" })
+intercom({ action: "list" });
 // → • worker — ~/projects/api (claude-sonnet-4) [idle]
 ```
 
@@ -198,55 +216,62 @@ intercom({ action: "list" })
 Long-lived Pi sessions normally coordinate without blocking each other. The sender uses `send`, which steers by default, and ends its turn or continues independent work. The recipient sees the message at its next tool boundary, incorporates relevant context, continues the active task, and sends any answer back with steer. A steer supplements the task unless it explicitly says to replace it.
 
 **Planner delegates work:**
+
 ```typescript
 intercom({
   action: "send",
   to: "worker",
   delivery: "steer",
-  message: "Task-3: Add retry logic to API client. Key files: src/api/client.ts, src/api/types.ts."
-})
+  message: "Task-3: Add retry logic to API client. Key files: src/api/client.ts, src/api/types.ts.",
+});
 ```
 
 **Worker steers a live discovery without holding its process open:**
+
 ```typescript
 intercom({
   action: "send",
   to: "planner",
   delivery: "steer",
-  message: "Blocked: should retry apply only to idempotent endpoints? Send the decision back with steer."
-})
+  message:
+    "Blocked: should retry apply only to idempotent endpoints? Send the decision back with steer.",
+});
 // Worker ends its turn instead of polling or waiting.
 ```
 
 **Planner answers while preserving the worker's active task:**
+
 ```typescript
 intercom({
   action: "send",
   to: "worker",
   delivery: "steer",
-  message: "Apply retries only to GET/PUT/DELETE. Max 3, exponential backoff from 100ms. Continue the current task."
-})
+  message:
+    "Apply retries only to GET/PUT/DELETE. Max 3, exponential backoff from 100ms. Continue the current task.",
+});
 ```
 
 **Worker reports completion:**
+
 ```typescript
 intercom({
   action: "send",
   to: "planner",
   delivery: "steer",
-  message: "Task-3 done. Added RetryPolicy, applied it to GET/PUT/DELETE, surfaced NetworkError, and passed 4 tests."
-})
+  message:
+    "Task-3 done. Added RetryPolicy, applied it to GET/PUT/DELETE, surfaced NetworkError, and passed 4 tests.",
+});
 ```
 
 ### Communication Patterns
 
-| Pattern | Action | Why |
-|---------|--------|-----|
-| **Task Delegation** | `send` + steer | Wakes an idle worker or reaches a busy worker at the next tool boundary without blocking the planner. |
-| **Guidance / Answer** | `send` + steer | Makes relevant context available during active work. |
-| **Clarification / Blocker** | `send` + steer | Long-lived peers can end their turn and wake when the answer arrives. |
-| **Intentional Deferral** | `send` + queue | The recipient should not incorporate the note until after active work. |
-| **Ephemeral Blocking Wait** | `ask` + steer | Keeps a short-lived process alive only when it cannot safely continue without the reply. |
+| Pattern                     | Action         | Why                                                                                                   |
+| --------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
+| **Task Delegation**         | `send` + steer | Wakes an idle worker or reaches a busy worker at the next tool boundary without blocking the planner. |
+| **Guidance / Answer**       | `send` + steer | Makes relevant context available during active work.                                                  |
+| **Clarification / Blocker** | `send` + steer | Long-lived peers can end their turn and wake when the answer arrives.                                 |
+| **Intentional Deferral**    | `send` + queue | The recipient should not incorporate the note until after active work.                                |
+| **Ephemeral Blocking Wait** | `ask` + steer  | Keeps a short-lived process alive only when it cannot safely continue without the reply.              |
 
 ### Blocking Ask Exception
 
@@ -281,15 +306,15 @@ When both bundled extension entries are enabled, parent sessions can use `agent_
 
 ### Three Reasons
 
-| Reason | Behavior | Use When |
-|--------|----------|----------|
-| `need_decision` | Persists the question, steers the supervisor, and waits without the ordinary ask timeout | The ephemeral child cannot safely continue without one decision, approval, or product/API/scope clarification |
-| `interview_request` | Persists structured questions and waits without the ordinary ask timeout | The ephemeral child cannot safely continue until it receives multiple structured answers |
-| `progress_update` | Non-blocking steer at the next tool boundary | A discovery or change the supervisor needs while working |
+| Reason              | Behavior                                                                                 | Use When                                                                                                      |
+| ------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `need_decision`     | Persists the question, steers the supervisor, and waits without the ordinary ask timeout | The ephemeral child cannot safely continue without one decision, approval, or product/API/scope clarification |
+| `interview_request` | Persists structured questions and waits without the ordinary ask timeout                 | The ephemeral child cannot safely continue until it receives multiple structured answers                      |
+| `progress_update`   | Non-blocking steer at the next tool boundary                                             | A discovery or change the supervisor needs while working                                                      |
 
 Do not use `contact_supervisor` for routine completion handoffs. Return the final subagent result normally through `pi-subagents`.
 
-Intercom provides live coordination and portable background completion notices. Every new subagent run has one detached owner, regardless of whether the parent waits or receives a background receipt. Waiting tools receive their saved result directly; the watcher suppresses an extra Intercom completion notice. See [host capabilities and result delivery](../README.md#host-capabilities-and-result-delivery).
+Intercom provides live coordination and portable background completion notices. Every new subagent run has one detached owner, regardless of whether the parent waits or receives a background receipt. Waiting tools receive their saved result directly; the watcher suppresses an extra Intercom completion notice. See [host capabilities and result delivery](reference.md#host-capabilities-and-result-delivery).
 
 Durable output lives in `pi-subagents` result details and artifact/output paths (`savedOutputPath`, `artifactPaths`, or explicit workspace `output` files). Completion notices include existing saved result and metadata paths, including acceptance details when configured. Use those files as the source of truth for long reports. Broker acceptance, notification delivery, parent review, and runtime acceptance are separate facts.
 
@@ -298,9 +323,14 @@ Durable output lives in `pi-subagents` result details and artifact/output paths
 `need_decision` and `interview_request` save the question before notification. Supervisor or broker disconnection does not end the wait. Resume the same saved supervisor session and use:
 
 ```typescript
-agent_runs({ action: "questions" })
-agent_runs({ action: "answer", id: "<run-id>", questionId: "<question-id>", message: "Use the stable API." })
-agent_runs({ action: "stop", id: "<run-id>" })
+agent_runs({ action: "questions" });
+agent_runs({
+  action: "answer",
+  id: "<run-id>",
+  questionId: "<question-id>",
+  message: "Use the stable API.",
+});
+agent_runs({ action: "stop", id: "<run-id>" });
 ```
 
 The full `subagent` tool also accepts `questions` and `answer`; its stop action is `interrupt`. Questions expose `awaiting_input`, `answer_pending`, `answered`, or `cancelled` independently of run completion. Ownership follows the saved supervisor session, not its cwd or display name. The live intercom reply path saves the same answer. Saving an answer or cancelling through run controls also clears the matching live intercom pending ask; a nudge does not resolve a question.
@@ -316,8 +346,9 @@ Questions, saved launch contracts, and canonical version-2 run status/results li
 ```typescript
 contact_supervisor({
   reason: "need_decision",
-  message: "The auth service returns 403 instead of 401 for expired tokens. Should I treat 403 as a re-auth trigger or a hard failure?"
-})
+  message:
+    "The auth service returns 403 instead of 401 for expired tokens. Should I treat 403 as a re-auth trigger or a hard failure?",
+});
 // → Reply from supervisor: Treat 403 as re-auth trigger. Update the token refresh logic.
 ```
 
@@ -330,11 +361,16 @@ contact_supervisor({
   interview: {
     title: "API migration choices",
     questions: [
-      { id: "api", type: "single", question: "Which API should I target?", options: ["Stable API", "Experimental API"] },
-      { id: "constraints", type: "text", question: "What constraints should I preserve?" }
-    ]
-  }
-})
+      {
+        id: "api",
+        type: "single",
+        question: "Which API should I target?",
+        options: ["Stable API", "Experimental API"],
+      },
+      { id: "constraints", type: "text", question: "What constraints should I preserve?" },
+    ],
+  },
+});
 // → Reply from supervisor: { "responses": [{ "id": "api", "value": "Stable API" }, ...] }
 ```
 
@@ -343,8 +379,9 @@ contact_supervisor({
 ```typescript
 contact_supervisor({
   reason: "progress_update",
-  message: "Discovered the bug is in the retry wrapper, not the API client. Fixing the wrapper will also close issue #42."
-})
+  message:
+    "Discovered the bug is in the retry wrapper, not the API client. Fixing the wrapper will also close issue #42.",
+});
 // → Progress update accepted for supervisor planner. Queued for the next tool boundary; broker acceptance does not confirm the supervisor has read or acted on it.
 ```
 
@@ -386,28 +423,28 @@ The supervisor can reply with plain JSON or a fenced `json` block. If the reply
 
 ### intercom
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `action` | string | `"list"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"` |
-| `scope` | string | Optional for list/status: `"project"` (default) shows this Git repository and its worktrees; `"all"` includes sessions in other projects. |
-| `to` | string | Target session name or ID (for send/ask, or to disambiguate reply) |
-| `message` | string | Message text (for send/ask/reply) |
-| `attachments` | array | Optional `file`, `snippet`, or `context` attachments |
-| `replyTo` | string | Optional message ID for threading or replying to an `ask` |
-| `delivery` | string | Optional: omitted `send` defaults to `"steer"`, which injects after the current tool call; `"queue"` intentionally waits behind active work, and `"passive"` does not wake the recipient model (`send` only). |
-| `queueMode` | string | Optional with queued delivery: `"stack"` keeps all messages, `"replace"` keeps only the latest undelivered message for the same `threadId` after a short coalescing window. |
-| `threadId` | string | Required for `queueMode:"replace"`; stable topic key for replacement. |
-| `passive` | boolean | Legacy `send`-only alias for `delivery:"passive"`. Discouraged for agent-to-agent messages. |
+| Parameter     | Type    | Description                                                                                                                                                                                                   |
+| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`      | string  | `"list"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"`                                                                                                                                            |
+| `scope`       | string  | Optional for list/status: `"project"` (default) shows this Git repository and its worktrees; `"all"` includes sessions in other projects.                                                                     |
+| `to`          | string  | Target session name or ID (for send/ask, or to disambiguate reply)                                                                                                                                            |
+| `message`     | string  | Message text (for send/ask/reply)                                                                                                                                                                             |
+| `attachments` | array   | Optional `file`, `snippet`, or `context` attachments                                                                                                                                                          |
+| `replyTo`     | string  | Optional message ID for threading or replying to an `ask`                                                                                                                                                     |
+| `delivery`    | string  | Optional: omitted `send` defaults to `"steer"`, which injects after the current tool call; `"queue"` intentionally waits behind active work, and `"passive"` does not wake the recipient model (`send` only). |
+| `queueMode`   | string  | Optional with queued delivery: `"stack"` keeps all messages, `"replace"` keeps only the latest undelivered message for the same `threadId` after a short coalescing window.                                   |
+| `threadId`    | string  | Required for `queueMode:"replace"`; stable topic key for replacement.                                                                                                                                         |
+| `passive`     | boolean | Legacy `send`-only alias for `delivery:"passive"`. Discouraged for agent-to-agent messages.                                                                                                                   |
 
 ### contact_supervisor
 
 Only registered in sessions where `pi-subagents` supplied the required child bridge metadata. Contacts the supervisor session that delegated the current task.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `reason` | string | `"need_decision"` (blocking), `"interview_request"` (blocking structured questions), or `"progress_update"` (non-blocking) |
-| `message` | string | The decision request, optional interview note, or progress update |
-| `interview` | object | Required for `interview_request`: `{ title?, description?, questions: [...] }` |
+| Parameter   | Type   | Description                                                                                                                |
+| ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `reason`    | string | `"need_decision"` (blocking), `"interview_request"` (blocking structured questions), or `"progress_update"` (non-blocking) |
+| `message`   | string | The decision request, optional interview note, or progress update                                                          |
+| `interview` | object | Required for `interview_request`: `{ title?, description?, questions: [...] }`                                             |
 
 **`need_decision`** — Use only when the ephemeral child cannot safely continue without one decision, approval, or product/API/scope clarification. It sends a formatted steered ask to the supervisor and keeps the child alive until the reply arrives, without the ordinary intercom ask timeout. The reply comes back as the tool result. Includes run metadata in the message so the supervisor knows which subagent is asking.
 
@@ -431,13 +468,13 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 
 ## Keyboard Shortcuts
 
-| Key | Action |
-|-----|--------|
+| Key                                        | Action                                                                                   |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
 | Option+Shift+M (Alt+Shift+M), configurable | Toggle owned agent conversations; open peer messaging when the agent view is unavailable |
-| ↑/↓ | Navigate session list |
-| Tab | Toggle Send / Request Reply mode in the compose overlay |
-| Enter | Select session / Send or ask |
-| Escape | Cancel / Close overlay |
+| ↑/↓                                        | Navigate session list                                                                    |
+| Tab                                        | Toggle Send / Request Reply mode in the compose overlay                                  |
+| Enter                                      | Select session / Send or ask                                                             |
+| Escape                                     | Cancel / Close overlay                                                                   |
 
 ## Config
 
@@ -455,17 +492,17 @@ Create `${PI_CODING_AGENT_DIR:-~/.pi/agent}/intercom/config.json`:
 }
 ```
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `shortcut` | `"alt+shift+m"` | Native Pi key identifier for the Agents/Intercom shortcut, for example `"ctrl+shift+k"`. The Agents entrance hint uses the same setting. |
-| `brokerCommand` | current Node executable | Command used to start the local broker process when you override the default |
-| `brokerArgs` | `[]` | Arguments passed to `brokerCommand` before the broker script path. The built-in default runs the bundled TypeScript broker directly with Node. |
-| `confirmSend` | false | Show a confirmation dialog before non-reply sends from an interactive session with UI |
-| `replyHint` | true | Include reply instructions in incoming asks |
-| `askTimeoutMs` | `120000` | Reply wait timeout for ordinary peer `ask`; durable supervisor questions do not expire |
-| `sendTimeoutMs` | `8000` | Broker delivery-ack timeout for sends/asks |
-| `listTimeoutMs` | `5000` | Session-list response timeout |
-| `status` | — | Optional custom status suffix shown after the automatic lifecycle status, for example `thinking · researching` |
+| Setting         | Default                 | Description                                                                                                                                    |
+| --------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shortcut`      | `"alt+shift+m"`         | Native Pi key identifier for the Agents/Intercom shortcut, for example `"ctrl+shift+k"`. The Agents entrance hint uses the same setting.       |
+| `brokerCommand` | current Node executable | Command used to start the local broker process when you override the default                                                                   |
+| `brokerArgs`    | `[]`                    | Arguments passed to `brokerCommand` before the broker script path. The built-in default runs the bundled TypeScript broker directly with Node. |
+| `confirmSend`   | false                   | Show a confirmation dialog before non-reply sends from an interactive session with UI                                                          |
+| `replyHint`     | true                    | Include reply instructions in incoming asks                                                                                                    |
+| `askTimeoutMs`  | `120000`                | Reply wait timeout for ordinary peer `ask`; durable supervisor questions do not expire                                                         |
+| `sendTimeoutMs` | `8000`                  | Broker delivery-ack timeout for sends/asks                                                                                                     |
+| `listTimeoutMs` | `5000`                  | Session-list response timeout                                                                                                                  |
+| `status`        | —                       | Optional custom status suffix shown after the automatic lifecycle status, for example `thinking · researching`                                 |
 
 The default shortcut requires a terminal that reports combined modifiers through Kitty keyboard protocol or xterm modifyOtherKeys. Pi negotiates these automatically on supported terminals. `/agents` is also available. Restart Pi after changing the shortcut.
 
@@ -515,6 +552,7 @@ Messages use length-prefixed JSON over a local Unix socket transport (4-byte len
 Startup restoration and inbound batches join during shutdown while their old native owner remains valid. Work that outlives a replaced owner (reconnects, overlays, and relays) no-ops rather than using stale APIs. Completion handoffs retain accepted acknowledgements before listeners stop; failed shutdown deliveries remain eligible on reopen without requesting a new turn after ingress closes. Undelivered receiver messages remain in native session metadata, bound to the exact saved session UUID. Native message entries are the delivery receipt, including messages that have left the active context after compaction. Each body is checkpointed once; later handoff metadata stores only the message ID and state.
 
 Runtime files:
+
 - Unix domain socket — private short temp path `pi-intercom-<hash>/broker.sock` on macOS/Linux, keyed by user ID and `PI_CODING_AGENT_DIR` or `~/.pi/agent`
 - `${PI_CODING_AGENT_DIR:-~/.pi/agent}/intercom/broker.pid` — Broker process ID on the first line (backward-readable). On Linux, new brokers add native boot ID, PID namespace, reader time namespace and process start ticks on a second `linux-v1` line.
 - `${PI_CODING_AGENT_DIR:-~/.pi/agent}/intercom/config.json` — User configuration
@@ -529,18 +567,6 @@ Runtime files:
 
 **`ask` stays client-side.** The broker still routes plain messages; it does not have a special request/response mode for `ask`. The sender marks the message as expecting a reply, the recipient wakes or queues according to the delivery mode, and the sender waits for the matching reply before returning it as the tool result. Reply hints make that flow practical by showing the recipient the exact `reply` call to use. Separately, `list` / `sessions` now carry a `requestId` so a delayed session-list reply cannot be mistaken for a newer one.
 
-## pi-intercom vs pi-messenger
-
-| Aspect | pi-intercom | pi-messenger |
-|--------|-------------|--------------|
-| **Model** | Direct 1:1 messaging | Shared chat room |
-| **Primary use** | User orchestrating sessions | Autonomous agent coordination |
-| **Discovery** | Broker-based (real-time) | File-based registry |
-| **Messages** | Private, session-to-session | Broadcast to all agents |
-| **Persistence** | In Pi session history | Shared coordination files |
-
-Use pi-messenger for multi-agent swarms working on a shared task. Use pi-intercom when you want to manually coordinate your own sessions or have one agent reach out to another specific session.
-
 ## File Structure
 
 ```
@@ -572,7 +598,7 @@ Assistant-error replies wait for broker acknowledgement during `message_end`, bo
 
 ## Limitations
 
-Historical official Pi 0.87.1 checks exposed queue visibility and prompt-preparation races. Current tests preserve exact-once receipts and input rejection/recovery on the selected host, including the genuine Pi 1.0 pre-admission window described above; they do not promise one combined provider turn. Historical results are not a current 1.0 pass. Use an explicit `async: false` wait when dependent work needs a finalized result. Native pending-call, idle-checkpoint and immediate-usage APIs are no longer supported. See [result delivery](../README.md#host-capabilities-and-result-delivery) and [local qualification](../README.md#local-validation).
+Historical official Pi 0.87.1 checks exposed queue visibility and prompt-preparation races. Current tests preserve exact-once receipts and input rejection/recovery on the selected host, including the genuine Pi 1.0 pre-admission window described above; they do not promise one combined provider turn. Historical results are not a current 1.0 pass. Use an explicit `async: false` wait when dependent work needs a finalized result. Native pending-call, idle-checkpoint and immediate-usage APIs are no longer supported. See [result delivery](reference.md#host-capabilities-and-result-delivery) and [local qualification](development.md#local-validation).
 
 - **Same machine only** — The core broker uses local Unix sockets, no network support. The optional [secure remote bridge](intercom-bridge.md) authenticates remote messaging through a separate loopback mTLS proxy; it does not expose the broker socket.
 - **No dedicated intercom log** — Messages are kept in Pi session history, but there is no separate intercom transcript or inbox

package/docs/performance.md

@@ -4,6 +4,8 @@
 
 Native journals and canonical run/control/receipt files remain the sources of truth. SQLite supplies private browse observations, not a new execution owner, completion receipt, billing authority or transcript format. Installing the extension does not adopt unrelated archives or remove provider and queue waits.
 
+Persisted run contracts use AJV standalone validators generated from their canonical TypeScript declarations. Pi sessions and detached runners validate disk reads without loading AJV's compiler or compiling guards at startup. `npm run generate:schemas` regenerates the JSON schema, executable guards and type declarations together; `npm run check:schemas` checks all three for drift. Both source and compiled package paths include the guards. Nested-field checks, finite-number rules, forward-compatible fields and validation diagnostics are unchanged.
+
 Startup recovers saved ownership, unanswered questions and Intercom receipts in small batches, allowing input between batches. Queued Intercom delivery also yields between batches, preserving followers before the final wake-up and staging new arrivals durably until the batch finishes. Retention cleanup uses asynchronous filesystem operations. Tools capture their invocation directory before awaiting restoration, and coordination publishes the current session name even if it changes during recovery. Checkpoint reconciliation remains synchronous and strict. Recovery still checks the complete eligible history and legacy records, without increasing or suppressing the host's performance-warning budget. A single recovery record, native append/projection or integrity scan remains atomic.
 
 ### Indexed browsing and lazy Agents work
@@ -42,7 +44,7 @@ The changed boundaries are exercised through real extension functions and regist
 - Four independent timing writers preserve each completed sample, another agent's samples, per-agent retained row counts and database integrity. A legacy snapshot read cannot erase an acknowledged write.
 - Native tool loading covers list/history/search validation, owned paging and same-parent reload on both compact and advanced routes. UI regressions cover narrow/wide native layouts, full reports/Reply, loading navigation, saved anchors and disposal.
 
-Primary owners are `test/integration/{history-index,owned-run-list,agent-interaction,tool-activation,lazy-coordination,session-resume-cost}.test.ts` and `test/unit/{run-history,journal-reader,temp-root-cleanup}.test.ts`. Run the [local validation](../README.md#local-validation) against an explicitly selected coherent host graph. Operation counts are more repeatable than timing thresholds.
+Primary owners are `test/integration/{history-index,owned-run-list,agent-interaction,tool-activation,lazy-coordination,session-resume-cost}.test.ts` and `test/unit/{run-history,journal-reader,temp-root-cleanup}.test.ts`. Run the [local validation](development.md#local-validation) against an explicitly selected coherent host graph. Operation counts are more repeatable than timing thresholds.
 
 ## Receipt and loadout work
 
@@ -56,16 +58,16 @@ The Agents dock polls while live work, questions, selected/pinned conversations
 
 The earlier 0.43.1 fixes removed repeated completed-history projections, continuation recursion, native observation matching, nested polling, and result/receipt polling. Their same-host recheck on fork `76dfe3d1` (Node 24.21.0) remains useful historical evidence; it is not a measurement of the new SQLite browse implementation:
 
-| Synthetic operation | Before 0.43.1 | 0.43.1 |
-| --- | --- | --- |
-| 100 completed 2,000-entry histories, five refreshes | 1,000,000 timestamp parses; 1,005 ms | 0 timestamp parses; 1.6 ms |
-| 1,000 continuations, one visible task | 500,500 identity resolutions | 1,000 |
-| 10,000 delivered/billed runs, three polls | 30,003 existence checks | 3 directory checks |
-| 40 unchanged foreign files, three polls | 120 decodes | 40 initial decodes |
-| 20,000 parent entries, ten owner checks | 400,020 visits, 20 scans | 40,002 visits, two startup scans |
-| 1,500 retained nested events, unchanged poll | 500 event rereads and one registry rewrite | Neither |
-| Nested projection in one job poll | Three registry reads | One |
-| Ten 100-card history windows | 1,001 cached components | 101, including the assignment |
+| Synthetic operation                                 | Before 0.43.1                              | 0.43.1                           |
+| --------------------------------------------------- | ------------------------------------------ | -------------------------------- |
+| 100 completed 2,000-entry histories, five refreshes | 1,000,000 timestamp parses; 1,005 ms       | 0 timestamp parses; 1.6 ms       |
+| 1,000 continuations, one visible task               | 500,500 identity resolutions               | 1,000                            |
+| 10,000 delivered/billed runs, three polls           | 30,003 existence checks                    | 3 directory checks               |
+| 40 unchanged foreign files, three polls             | 120 decodes                                | 40 initial decodes               |
+| 20,000 parent entries, ten owner checks             | 400,020 visits, 20 scans                   | 40,002 visits, two startup scans |
+| 1,500 retained nested events, unchanged poll        | 500 event rereads and one registry rewrite | Neither                          |
+| Nested projection in one job poll                   | Three registry reads                       | One                              |
+| Ten 100-card history windows                        | 1,001 cached components                    | 101, including the assignment    |
 
 Cold factory startup did not measurably change in that comparison: five isolated offline CLI launches ranged from 410–605 ms before and 411–437 ms after. The minimum difference was below run-to-run variation.
 
@@ -104,17 +106,17 @@ For a hypothetical constant **500,000 cached tokens per request**:
 
 If "97% hit" means cached tokens divided by cached plus uncached input tokens, the corresponding uncached input is `4.26 billion × 0.03 / 0.97 = 131.75 million`, or about `15,463.92` per request. A request-based hit percentage would not support that calculation.
 
-| Hypothetical steady workload | Cache-read tokens |
-| --- | ---: |
-| One 500k-prefix session, one request/10 seconds for 24 hours | 4.32 billion |
-| Parent plus eight 500k-prefix children, one request/30 seconds each for 8 hours | 4.32 billion |
-| Eight 50k-prefix fresh children, one request/30 seconds each for 8 hours | 384 million |
+| Hypothetical steady workload                                                    | Cache-read tokens |
+| ------------------------------------------------------------------------------- | ----------------: |
+| One 500k-prefix session, one request/10 seconds for 24 hours                    |      4.32 billion |
+| Parent plus eight 500k-prefix children, one request/30 seconds each for 8 hours |      4.32 billion |
+| Eight 50k-prefix fresh children, one request/30 seconds each for 8 hours        |       384 million |
 
 These assumptions include sustained activity and a full cache hit on that prefix; they are not measured workloads, throughput guarantees or pricing estimates. Token counts alone cannot establish dollars, double billing, a spawn loop, or which sessions made the requests.
 
 ### Accounting and useful checks
 
-`src/runs/shared/native-usage.ts` excludes inherited launch-baseline entries and nonbillable checkpoints, then validates and deduplicates new native contributions. Excluding old journal usage does **not** make newly sending inherited context free. Pi 1.0 attribution uses finalized execution/wait tool results, not the removed `recordUsage` hook. Background notifications alone do not enter parent totals. Claude totals may remain explicitly accounting-incomplete when per-category evidence is unavailable. See [usage accounting](../README.md#usage-accounting); local attribution is not an additional provider request.
+`src/runs/shared/native-usage.ts` excludes inherited launch-baseline entries and nonbillable checkpoints, then validates and deduplicates new native contributions. Excluding old journal usage does **not** make newly sending inherited context free. Pi 1.0 attribution uses finalized execution/wait tool results, not the removed `recordUsage` hook. Background notifications alone do not enter parent totals. Claude totals may remain explicitly accounting-incomplete when per-category evidence is unavailable. See [usage accounting](reference.md#usage-accounting); local attribution is not an additional provider request.
 
 To investigate an actual spike, compare provider usage for the relevant time/model/account with parent and child native usage, launch counts, effective `fresh`/`fork` settings and context sizes. Do not sum attributed parent totals and the same child totals as independent traffic. Keep private prompts, journals and credentials out of public issues.