@selesai/code 0.13.39 → 0.14.0

package/dist/extensions/pi-intercom/CHANGELOG.md

@@ -4,6 +4,72 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.16.1] - 2026-10-04
+
+### Highlights
+- An intercom message that wakes an idle session now starts a normal turn, with everything your other extensions add to the prompt. Providers such as pi-claude-bridge no longer fail on that turn or get stuck afterwards.
+- You can see when a message woke a session: the transcript shows a short "New intercom message above." line.
+- Press Ctrl+O to read the full text of messages you send, not just the first line or so.
+
+### Fixed
+- A message that arrived while a session was idle started a turn without other extensions' `before_agent_start` additions to the prompt. Providers that check the prompt, such as pi-claude-bridge, failed that turn, and the session could stay broken afterwards. The message is now added to the session first, and the session wakes through a normal prompt, so those additions are included. The transcript shows the wake as a short "New intercom message above." line. Sessions already broken by the old behavior need the manual fix described in issue #152. Thanks to [@BGamboa13](https://github.com/BGamboa13) for issue #152 and [@pmontiel-x](https://github.com/pmontiel-x) for the follow-up diagnosis.
+- Pressing Ctrl+O now shows the full message of an outgoing `intercom` or `contact_supervisor` call. Before, long messages stayed cut off at a short preview even when expanded. Thanks to [@summer-tt](https://github.com/summer-tt) for PR #153.
+
+## [0.16.0] - 2026-09-30
+
+### Highlights
+- Hand your work to another session with `/handover`. Pi writes up what this session learned, decided, and changed, and the other session picks up the next task without starting from scratch.
+- Hand over to Pi sessions on your other computers. The `/handover` picker lists sessions on this machine and, when you ask, on your saved Herdr machines.
+- Press `h` in the Alt+M session list to hand over to the highlighted session.
+- On Windows, the broker no longer starts through a VBScript file that security tools flagged, and opening a Herdr project pane now starts Pi.
+
+### Added
+- `/handover <target> [next task]` and the intercom tool's `handover` action hand your session's context to another session. Pi summarizes what the session learned, decided, and changed, and the receiving session starts on the next task. You can edit the summary before sending it. If you give a project path and no session is running there, a Herdr pane opens one. `name@machine` targets on saved Herdr machines work too.
+- `/handover` with no arguments opens a picker. Choose a session on this machine, start a new session in a project, or load Pi sessions from your other Herdr machines. In the Alt+M session list, press `h` to hand over to the highlighted session.
+
+### Changed
+- On Windows, the broker no longer starts through a `broker-launch.vbs` file, which endpoint security tools flagged as suspicious. It now runs as one hidden Node process, the same way as on other platforms, and a failed start shows the broker's error output. If you set a custom `brokerCommand` on Windows, it must point to an executable, not a `.cmd` shim. Thanks to [@jhonruda25](https://github.com/jhonruda25) for issue #142.
+
+### Fixed
+- You can now send to Pi sessions on another machine even if they were never renamed in Herdr. Address them as `full-session-uuid@machine`. Before, only renamed sessions could be found.
+- Opening a Herdr project pane now starts Pi on Windows. The command was sent in quotes, and PowerShell printed it as text instead of running it. Thanks to [@elliot-chung](https://github.com/elliot-chung) for #143.
+- When another machine can't be reached, the error now shows Herdr's reason instead of raw debug output. If that machine's Herdr server is too old to list sessions, the error says how to update it.
+
+## [0.15.0] - 2026-09-27
+
+### Highlights
+- Send one-way text messages to Pi sessions on saved Herdr machines with `name@machine` addressing.
+- Keep remote brokers local-only while SSH carries messages between machines.
+- See a clear `unverified cross-machine` label on messages received from another machine.
+- Update pi-intercom on Windows without open Pi sessions locking the installed package.
+
+### Added
+- Added one-way text `send` to `name@machine` or `full-session-uuid@machine` over SSH through enabled Herdr saved machines. Remote brokers remain local-only, received messages are clearly marked as unverified, and unsupported operations fail with a clear error. Thanks to [@odfalik](https://github.com/odfalik) for issue #138 and the original prototype.
+
+### Fixed
+- Open Pi sessions no longer prevent package updates on Windows. Thanks to [@XWIlluDelu](https://github.com/XWIlluDelu) for #139.
+
+## [0.14.0] - 2026-09-23
+
+### Highlights
+- Coordinate with other sessions from scripts or over SSH using the new command-line client.
+- Keep messages from interrupting your input with optional human-first delivery.
+- Find sessions more easily with Herdr locations and a shorter session list.
+- Messages arriving during compaction now reach their destination afterward.
+
+### Added
+- Added a command-line client with `list`, `send`, and `ask` commands for scripts and coordination over SSH. Thanks to [@pinion05](https://github.com/pinion05) for #131 and issue #130.
+- Added opt-in `busyDelivery: "human-first"` to hold peer messages while you're typing and deliver them at turn boundaries. The default behavior is unchanged. Thanks to [@SiebertLanhove](https://github.com/SiebertLanhove) for #128.
+- Extensions can use the `intercom:session-identity` event to give a session a fixed ID without changing its readable name. Thanks to [@Q-xuan](https://github.com/Q-xuan) for raising the readable child name problem in nicobailon/pi-subagents#2432.
+- `list` now shows the workspace, tab, and pane for sessions hosted in Herdr. Thanks to [@odfalik](https://github.com/odfalik) for #129.
+
+### Changed
+- `list` and `list-cwd` show a one-line summary in the TUI; expand it to see every session. The model still sees the full list. Thanks to [@SiebertLanhove](https://github.com/SiebertLanhove) for #127.
+
+### Fixed
+- Messages held for delivery now report when they're queued or dropped, including after cancellation, supersession, a reply, or session shutdown.
+- Messages arriving during compaction are delivered afterward instead of being lost. Thanks to [@alexjc](https://github.com/alexjc) for #133.
+
 ## [0.13.0] - 2026-09-02
 
 ### Highlights

package/dist/extensions/pi-intercom/README.md

@@ -82,6 +82,8 @@ Press **Alt+M** or type `/intercom` to open the session list overlay:
 2. **Compose message** — Write your message in the compose overlay
 3. **Send** — Press Enter to send, Escape to cancel
 
+Press **h** on a highlighted session to hand this session over to it instead (see [Workflow: Handing Over a Session](#workflow-handing-over-a-session)).
+
 ### From the Agent
 
 The agent can list sessions and send messages using the `intercom` tool. Tool calls and results render as compact transcript rows so send/ask/reply flows are easy to scan. Use `/intercom-id` to insert a handoff snippet for the current session's stable intercom target into the editor. For common patterns like planner-worker delegation, the bundled `pi-intercom` skill provides copy-paste ready examples:
@@ -90,9 +92,9 @@ The agent can list sessions and send messages using the `intercom` tool. Tool ca
 // List active sessions
 intercom({ action: "list" })
 // → **Current session:**
-// → • executor (20d43841) — ~/projects/api (claude-sonnet-4 · 42% ctx) [self, idle]
+// → • executor (20d43841) — ~/projects/api (claude-sonnet-4 · 42% ctx) · Herdr Platform [w5] / API [w5:t2] / pane w5:p4 [self, idle]
 // → **Other sessions:**
-// → • research (6332faab) — ~/projects/api (claude-sonnet-4) [same cwd, thinking]
+// → • research (6332faab) — ~/projects/api (claude-sonnet-4) · not under Herdr [same cwd, thinking]
 
 // List only peers in the same working directory
 intercom({ action: "list-cwd" })
@@ -141,7 +143,20 @@ Found the issue — UserService.validate() doesn't check for null input.
 See auth.ts:142-156.
 ```
 
-The reply hint (enabled by default) points to `intercom({ action: "reply", ... })`, so recipients do not need raw sender or `replyTo` IDs. Idle recipients get a new turn immediately; busy interactive recipients receive the message through Selesai's steering queue at the next safe model boundary without aborting the active turn. Attachment content is included in the agent-visible body, and messages are rendered inline and stored in Selesai session history.
+The reply hint (enabled by default) points to `intercom({ action: "reply", ... })`, so recipients do not need raw sender or `replyTo` IDs. Idle recipients get a new turn immediately; by default busy interactive recipients enter Pi's steering queue at the next safe model boundary without aborting the run. With `busyDelivery: "human-first"`, busy interactive peers wait outside Pi's queues: one FIFO peer is steered per turn when no human message is pending. If the run ends first, the idle flush releases one via the normal `inboundTrigger` policy; remaining peers wait for later turns. Sustained human input can delay peers. Busy non-UI sessions retain their auto-reply behavior. Attachment content is included in the agent-visible body, and messages are rendered inline and stored in Pi session history.
+
+## Desktop / RPC clients
+
+RPC clients can use typed `intercom_status`, `intercom_list`, `intercom_send`, `intercom_ask`, `intercom_reply`, and `intercom_pending` commands directly, without a model turn or the TUI-only `/intercom` overlay. They reuse this extension's broker connection, reply tracker, scope, and consent policy. Ordinary/inferred sends honor `confirmSend`; explicit replies and asks skip confirmation as in the tool. Missing/disabled extensions fail explicitly.
+
+```json
+{"id":"peers","type":"intercom_list"}
+{"id":"send","type":"intercom_send","to":"peer-full-id","message":"Build finished."}
+{"id":"ask","type":"intercom_ask","to":"peer-full-id","message":"Approve?","timeoutMs":60000}
+{"id":"reply","type":"intercom_reply","replyTo":"question-id","message":"Approved."}
+```
+
+Structured connection, peer join/leave, presence, incoming message, delivery, and receipt events stream while idle or busy. Command `id` correlates responses; Intercom `messageId`/`replyTo` correlate messages and receipts. An ask timeout does not cancel delivered work. See [the RPC protocol](../../../docs/rpc.md#intercom-desktop--headless-clients) for response shapes, event examples, timeout limits, confirmation dialogs, and typed client helpers.
 
 ## Workflow: Planner-Worker Coordination
 
@@ -240,12 +255,39 @@ This matters because the agent receiving the message doesn't need to reconstruct
 
 The broker keeps a bounded in-memory mailbox for recently disconnected explicitly named sessions. If a lightweight CLI sender asks a long-running session something and exits before the answer, the later `reply` is accepted into that mailbox instead of failing with `Session not found`; a process that reconnects with the same explicit name and directory receives the queued reply. Runtime-only unnamed-session aliases never transfer mailbox ownership, and routing never remaps mail back to its sender. This is per-broker runtime state, not durable storage across broker restarts.
 
-Incoming messages carry diagnostic metadata end to end: stable message ID, sender sequence, sender timestamp, broker receive/delivery timestamps, receiver receive timestamp, and injection timestamp. Connected interactive receivers emit `receiver_received`, `acknowledged`, and `injected` as they hand messages to Selesai; duplicate IDs are acknowledged but injected at most once per receiving session. Broker mailbox delivery for temporarily disconnected targets can still report queued delivery. If an `ask` times out, the timeout names the message ID and last known delivery state. Timeout is not cancellation: an injected or broker-queued message may remain actionable unless an explicit cancellation path says otherwise.
+Incoming messages carry diagnostic metadata end to end: stable message ID, sender sequence, sender timestamp, broker receive/delivery timestamps, receiver receive timestamp, and injection timestamp. Connected receivers emit `receiver_received`, `acknowledged`, and `injected` as they hand messages to Pi; held messages (during compaction or with human-first delivery) also emit `queued`, followed by `injected` or a terminal `cancelled`, `superseded`, `acknowledged` (answered before injection), or `expired` (session replaced or shut down). Duplicate IDs are acknowledged but injected at most once per receiving session. Broker mailbox delivery for temporarily disconnected targets can still report queued delivery. If an `ask` times out, the timeout names the message ID and last known delivery state. Timeout is not cancellation: an injected or broker-queued message may remain actionable unless an explicit cancellation path says otherwise.
 
-Cancellation is explicit: call `intercom({ action: "cancel", messageId })` to request cancellation of a message you originally sent. Connected interactive messages are injected immediately, so the receiver normally reports `cancellation_requested` rather than pretending it removed work from a private queue. Supersede is also explicit: pass `supersedes: "old-message-id"` on a new `send` or `ask`. The broker only allows same sender → same receiver supersedes, marks the old message `superseded`, and sends the replacement with a new ID; an already-steered old message may still be processed. Retries are never automatic; a retry should be a new authored message, optionally linked with `retryOf`.
+Cancellation is explicit: call `intercom({ action: "cancel", messageId })` to request cancellation of a message you originally sent. A held message is dropped with `cancelled`; an already-injected message reports `cancellation_requested` rather than pretending it removed work from Pi's queues. Supersede is also explicit: pass `supersedes: "old-message-id"` on a new `send` or `ask`. The broker only allows same sender → same receiver supersedes, marks the old message `superseded`, and sends the replacement with a new ID; a held old message is dropped, while an already-steered one may still be processed. Retries are never automatic; a retry should be a new authored message, optionally linked with `retryOf`.
 
 The planner typically uses `send`. If you prefer manual approval for outgoing non-reply messages, turn on `confirmSend: true`. The worker uses `ask` for everything (no confirmation needed, gets answers inline), so it can operate autonomously either way.
 
+## Workflow: Handing Over a Session
+
+When you move work from one session to another, for example from a session in `pi-intercom` to one already running in `pi-mcp-adapter`, a handover carries what the first session learned so the second one does not have to rediscover it.
+
+```
+/handover
+/handover mcp-worker port the schema fix to the adapter
+/handover ~/dev/pi-mcp-adapter port the schema fix to the adapter
+```
+
+`/handover` on its own opens a picker. It lists the other sessions on this machine, most recently active first, with their directory, model, status, and context use; context at 80% or more is highlighted. Your own session and subagent child sessions are hidden. "+ New session in a project path…" asks for a directory and opens a Herdr project pane there. "Fetch sessions from other machines" lists the Pi sessions on your enabled saved Herdr machines; it only runs when you choose it, because each machine is reached over SSH and can take a few seconds. Each machine shows its sessions or the reason it could not be reached. Type the optional next task in the field at the bottom (Tab moves between the list and the field), and press Enter to generate the handover. Pressing **h** on a session in the Alt+M list opens the same picker with that session selected.
+
+The first argument is the target: a session name, ID, ID prefix, or `name@machine`. A target starting with `/`, `./`, `../`, or `~/` is a project path; if no session is running there, pi-intercom opens a Herdr project pane and starts Pi in it. The rest of the line is the next task and is optional. The command generates the handover, opens it in an editor for you to review and change, and sends it when you save.
+
+Agents can do the same without the review step:
+
+```typescript
+intercom({ action: "handover", to: "mcp-worker", message: "Port the schema fix to the adapter" })
+intercom({ action: "handover", cwd: "/Users/me/dev/pi-mcp-adapter", openProjectPaneIfMissing: true })
+```
+
+What is sent: the current model reads this session's conversation, as Pi would send it to the model after compaction and context edits, and writes a summary with the next task, key decisions and rejected approaches, relevant files and repositories, current state, and open questions. A short header names the sender, its working directory, and its git branch and commit. For a target on the same machine, the header also gives the path of the sender's session file so the receiver can read the full transcript when it needs more detail. For a `name@machine` target the handover is sent as plain text without that path.
+
+The receiver gets the handover as an ordinary intercom message asking it to act on the next task, so its `inboundTrigger` and `busyDelivery` settings decide when it starts: right away when idle, or at the next safe point when busy. The handover tells the receiver to treat it as a peer's report and to check its claims against the repository.
+
+Privacy: the summary is generated from your session transcript by your current model and provider, like compaction. The model is told to leave out secrets, tokens, credentials, and private keys, but review the text with `/handover` when the session handled sensitive material. `confirmSend: true` also applies to agent handovers.
+
 ## Workflow: Subagent-to-Supervisor Escalation
 
 This workflow requires [`pi-subagents`](https://github.com/nicobailon/pi-subagents) to be installed and to supply child bridge metadata. When `pi-subagents` spawns a delegated child with that metadata, the child session gets a subagent-only `contact_supervisor` tool in addition to the regular `intercom` tool. Normal sessions never see `contact_supervisor`.
@@ -348,9 +390,9 @@ The supervisor can reply with plain JSON or a fenced `json` block. If the reply
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `action` | string | `"list"`, `"list-cwd"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, `"status"`, or `"cancel"` |
+| `action` | string | `"list"`, `"list-cwd"`, `"send"`, `"ask"`, `"handover"`, `"reply"`, `"pending"`, `"status"`, or `"cancel"` |
 | `to` | string | Target session name or ID. Without `cwd`, send/ask resolve it globally. With `cwd`, send/ask require the target to be in that directory. Also disambiguates reply. |
-| `message` | string | Message text (for send/ask/reply) |
+| `message` | string | Message text (for send/ask/reply), or the optional next task for `handover` |
 | `attachments` | array | Optional `file`, `snippet`, or `context` attachments |
 | `replyTo` | string | Optional message ID for threading or replying to an `ask` |
 | `messageId` | string | Optional explicit message ID for send/ask, or required message ID for `cancel` |
@@ -378,12 +420,14 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 
 ### intercom actions
 
-**`list`** — Returns the current session plus other active intercom-connected sessions with name, short ID, working directory, model, and live status. Status is derived automatically from Selesai lifecycle events: `idle`, `thinking`, or `tool:<name>`.
+**`list`** — Returns the current session plus other active intercom-connected sessions with name, short ID, working directory, model, live status, and explicit Herdr location. For Herdr-hosted sessions, the broker joins the process's stable Pi session identity against one fresh `herdr api snapshot` per list request and returns readable workspace/tab labels together with their opaque IDs and the diagnostic pane ID. Workspace and tab are not registration-time values and are not cached, so moving a pane is reflected by the next list. `herdrLocation.status` is `current`, `not_hosted`, or `unavailable`; unavailable results include a reason such as `pane_missing` or `herdr_unavailable` rather than inviting inference from cwd or session name. A Herdr command failure does not prevent the rest of the roster from being returned. When no connected session advertises Herdr hosting, `list` does not invoke Herdr and preserves the ordinary roster shape and rendering without location lines. `herdrPaneId` is the launch alias and may be stale after a move; consumers needing the current diagnostic pane ID must use `herdrLocation.paneId`. Pane IDs are diagnostic metadata, not intercom addressing handles. Status is derived automatically from Pi lifecycle events: `idle`, `thinking`, or `tool:<name>`.
 
 **`send`** — Sends a message to the specified session and returns immediately after delivery. If the destination has exactly one pending inbound ask, `send` infers the message is its answer and returns `Reply sent to <target> (inferred from pending ask)`. During a turn triggered by an inbound ask, a non-reply `send` to a different target is rejected so a guessed parent/root CWD cannot receive an accidental reply. Zero or multiple pending-ask matches remain unthreaded sends outside the active ask turn. Set `confirmSend: true` to confirm ordinary and inferred sends. A caller-supplied `replyTo` skips confirmation. `to` alone resolves globally across all live sessions. `cwd` alone targets the sole live peer in that directory. `to` plus `cwd` requires that peer to be in the directory. With `openProjectPaneIfMissing: true`, pi-intercom opens a visible Herdr project pane, starts Selesai there, waits for that session to register, then delivers the message through normal intercom routing.
 
 **`ask`** — Requires a currently connected recipient, sends a message, and waits for the recipient to reply (10-minute timeout by default; configurable with `PI_INTERCOM_ASK_TIMEOUT_MS`). A disconnected target fails immediately rather than queueing a blocking request. The reply is returned as the tool result. No confirmation dialog. Only one pending `ask` is allowed per session at a time. Use this when the agent needs the answer to continue working. The same `to`, `cwd`, and `openProjectPaneIfMissing` targeting rules apply.
 
+**`handover`** — Summarizes the current session with the current model and sends the summary to the target, which acts on it. `message` is the optional next task. Targeting, confirmation, and delivery work exactly like `send`, including `name@machine` targets. `replyTo`, `supersedes`, `retryOf`, and `attachments` are rejected. See [Workflow: Handing Over a Session](#workflow-handing-over-a-session).
+
 **`reply`** — Replies to the current intercom-triggered message if there is one. Otherwise it falls back to the single unresolved inbound ask. If multiple asks are pending, pass `to` or inspect them with `pending` first. Under the hood this is still a normal `send` with the exact `replyTo` value.
 
 **`pending`** — Lists unresolved inbound asks with sender, message ID, elapsed time, and a short preview. Useful when replying after the original triggered turn.
@@ -399,6 +443,7 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 | Alt+M | Open session list overlay |
 | ↑/↓ | Navigate session list |
 | Enter | Select session / Send message |
+| h | Hand over to the highlighted session (session list) |
 | Escape | Cancel / Close overlay |
 
 ## Config
@@ -411,21 +456,29 @@ Create `~/.selesai/agent/intercom/config.json`:
   "brokerArgs": ["--no-install", "tsx"],
   "confirmSend": false,
   "inboundTrigger": "always",
+  "busyDelivery": "steer",
   "enabled": true,
   "replyHint": true,
-  "status": "researching"
+  "status": "researching",
+  "crossMachine": {
+    "machineName": "laptop",
+    "remoteCommand": "/usr/local/bin/pi-intercom"
+  }
 }
 ```
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `brokerCommand` | `"npx"` | Advanced trusted override for the broker executable. The default value is hardened internally to launch the resolved bundled `tsx` CLI through the current Node executable instead of resolving `npx` through `PATH`. |
+| `brokerCommand` | `"npx"` | Advanced trusted override for the broker executable. The default value is hardened internally to run the broker in the current Node executable with the resolved bundled `tsx` loader instead of resolving `npx` through `PATH`. A custom command is spawned directly without a shell, so on Windows it must name an executable such as `bun`, not a `.cmd` shim such as `npx`. |
 | `brokerArgs` | `["--no-install", "tsx"]` | Advanced trusted arguments passed to custom `brokerCommand` before the broker script path |
 | `confirmSend` | false | Show a confirmation dialog before ordinary or inferred sends from an interactive session with UI; caller-supplied `replyTo` skips it |
 | `inboundTrigger` | `"always"` | Auto-trigger policy for inbound broker messages: `"always"`, `"replies"`, or `"never"`. Local in-process subagent relay events still trigger the addressed session. |
+| `busyDelivery` | `"steer"` | `"steer"` promptly steers peers into active interactive runs. Opt into `"human-first"` to hold peers until a turn boundary with no pending human input; one held peer is released per turn. Non-interactive busy behavior is unchanged. |
 | `enabled` | true | Enable/disable intercom entirely |
 | `replyHint` | true | Include reply instruction in incoming messages |
 | `status` | — | Optional custom status suffix shown after the automatic lifecycle status, for example `thinking · researching` |
+| `crossMachine.machineName` | lowercased short hostname | Name peers use for this host in their Herdr saved-machine lists |
+| `crossMachine.remoteCommand` | `"pi-intercom"` | Command invoked through non-interactive SSH on remote machines |
 
 If `config.json` cannot be parsed or contains an invalid value, pi-intercom logs the error and fails closed for inbound broker auto-triggering by using `inboundTrigger: "never"` until the config is fixed.
 Obsolete `toolVisibility` values are ignored; the generic `intercom` tool remains stable in the active tool set for prompt-cache friendliness.
@@ -445,6 +498,8 @@ Set `PI_INTERCOM_SCOPE_ID` before starting Selesai to opt a session into an opaq
 
 By default, runtime state and config live under `~/.selesai/agent/intercom`. If Selesai is launched with `SELESAI_CODING_AGENT_DIR`, pi-intercom uses `$SELESAI_CODING_AGENT_DIR/intercom` instead, including `config.json`, broker PID/lock files, sockets, and launcher state.
 
+The broker also runs from this runtime directory so its working directory does not lock the installed package against updates on Windows. Custom broker commands can use executables on `PATH` or absolute paths; relative file paths in commands and arguments resolve from the runtime directory.
+
 ## Extension channels
 
 Other Selesai extensions can use intercom's broker for bounded, non-conversational coordination. Extension-channel traffic never calls `pi.sendMessage()`, never enters a session transcript, and never starts an agent turn.
@@ -511,6 +566,51 @@ pi.events.emit(INTERCOM_OUTBOX_REQUEST_EVENT, {
 
 `confirmSend` applies to outbox requests. If confirmation is required and no UI is available, the request fails closed with `confirmation_unavailable`. The outbox resolves the target through the current session's scoped intercom client, so extensions cannot choose the sender, scope, or resolved target ID. Duplicate `requestId` values are rejected and do not deliver again. Receiver messages include structured `extension_outbox` provenance in message details; provenance is not prepended to the message body.
 
+### Session identity claim
+
+At session start, pi-intercom emits `intercom:session-identity` on that session's event bus before it picks the session's intercom ID. An extension that owns the session's routing address can call `claim(id)` synchronously. The first non-empty claim becomes that session's intercom ID, and it wins over `PI_INTERCOM_STABLE_ID` and `stableId`. Because the claim is per session, it works for several sessions running in one process, such as in-process subagent children. The session name stays free for a human-readable label.
+
+```typescript
+import { INTERCOM_SESSION_IDENTITY_EVENT, type IntercomSessionIdentityRequestV1 } from "pi-intercom/extension-api.ts";
+
+pi.events.on(INTERCOM_SESSION_IDENTITY_EVENT, (request: IntercomSessionIdentityRequestV1) => {
+  request.claim("subagent-worker-run1-1");
+});
+```
+## Scripting and Remote Machines
+
+The `pi-intercom` executable is a minimal command-line client for scripted access to the local broker. It registers as a regular session (so it appears in the roster and can receive replies while connected), reuses the same `IntercomClient` as the extension, and does not start a broker.
+
+```bash
+# roster
+pi-intercom list
+
+# fire-and-forget message (cron hooks, CI, notifications)
+pi-intercom send --to worker --text "build failed — please look at src/api"
+
+# blocking ask: prints the other session's reply and exits
+pi-intercom ask --to planner --text "which API version?" --timeout-ms 180000
+
+# JSON output for scripts
+pi-intercom list --json
+```
+
+Flags: `--to <name|session-id>`, `--text`, `--name <session-name>` (roster name, default `pi-intercom-cli`), `--timeout-ms` (ask only, default 120000), `--json`. Exit codes: `0` success, `1` usage/connection/delivery failure, `2` ask timeout. With `--json`, every command prints one object with an `ok` field: `list` returns `{ ok: true, sessions: [...] }`, and failures return `ok: false` with `error` (plus `reason: "timeout"` on timeout).
+
+### Cross-machine coordination over ssh
+
+Because the CLI runs *on the machine that owns the broker*, you can bridge sessions across machines through ssh without opening any network listener — the remote broker stays exactly as local-only as before:
+
+```bash
+ssh remote-host 'pi-intercom ask --to worker --text "done with the migration?"'
+```
+
+For native cross-machine `send`, pi-intercom discovers an agent on an explicitly selected, enabled Herdr saved machine and relays through SSH while every broker remains local-only. Use `reviewer@workstation` (or a full session UUID followed by `@workstation`) to route to the saved `workstation` machine. Ordinary local targets never fall back to remote discovery, and unknown, disabled, or malformed machine entries fail closed.
+
+The relay carries structured SSH-asserted origin metadata. Incoming headers render `From worker@laptop · unverified cross-machine` and provide a new-message `send` hint to that address. This identity is not cryptographically verified: anyone with SSH access that can invoke the relay can claim it. Cross-machine `ask`, `replyTo`, attachments, supersede, retry, cwd/project-pane routing, and lifecycle actions are not supported in v1.
+
+Discovery and delivery are bounded by five-second and fifteen-second timeouts respectively. Remote hosts must provide a compatible `pi-intercom relay` command. Non-interactive SSH often has a minimal `PATH`; set the trusted global `crossMachine.remoteCommand` to an absolute command when needed. Unknown relay versions and non-JSON responses produce an upgrade error.
+
 ## How It Works
 
 ```mermaid
@@ -549,13 +649,12 @@ Async extension work (startup, inbound flushes, reconnects, overlays, and relays
 
 Runtime files live at `~/.selesai/agent/intercom/` by default, or `$SELESAI_CODING_AGENT_DIR/intercom/` when `SELESAI_CODING_AGENT_DIR` is set:
 - `broker.sock` — Unix domain socket for communication (macOS/Linux only; Windows uses a named pipe instead)
-- `broker-launch.vbs` — Windows helper script used to launch the broker without a console window
 - `broker.pid` — Broker process ID
 - `broker.spawn.lock` — Auto-spawn lock file
 - `broker.port.json` — Dynamic localhost TCP endpoint, only when Windows TCP transport is explicitly enabled
 - `config.json` — User configuration
 
-Supported `config.json` keys include `stableId` for restart-stable addressing, `status` for a custom status suffix, `inboundTrigger` (`always`, `replies`, or `never`), `replyHint`, `confirmSend`, and advanced broker launch overrides.
+Supported `config.json` keys include `stableId` for restart-stable addressing, `status` for a custom status suffix, `inboundTrigger` (`always`, `replies`, or `never`), `busyDelivery` (`steer` or `human-first`), `replyHint`, `confirmSend`, and advanced broker launch overrides.
 
 ## Design Decisions
 
@@ -585,6 +684,7 @@ Use pi-messenger for multi-agent swarms working on a shared task. Use pi-interco
 ├── index.ts              # Extension entry point
 ├── types.ts              # SessionInfo, Message, protocol types
 ├── config.ts             # Config loading
+├── handover.ts           # Session handover summary and header
 ├── project-agent.ts      # Herdr project-pane launch and cwd target resolution
 ├── broker/
 │   ├── broker.ts         # Broker process
@@ -596,6 +696,7 @@ Use pi-messenger for multi-agent swarms working on a shared task. Use pi-interco
 │   └── paths.test.ts     # Path resolution tests
 ├── ui/
 │   ├── session-list.ts   # Session selection overlay
+│   ├── handover-picker.ts # /handover session picker
 │   ├── compose.ts        # Message composition overlay
 │   └── inline-message.ts # Received message display
 └── skills/
@@ -610,3 +711,5 @@ Use pi-messenger for multi-agent swarms working on a shared task. Use pi-interco
 - **No attachments UI** — `file`, `snippet`, and `context` attachments are supported in the protocol, but not in the compose overlay
 - **Only connected sessions appear** — The list shows Selesai sessions that have loaded `pi-intercom` and successfully registered with the broker, not every open Selesai process on the machine
 - **Broker lifecycle** — The broker auto-spawns on first use and exits when idle; sessions reconnect automatically if the broker restarts
+
+All Intercom events and `intercom_status.data` carry `scope: {version:1,sessionId,epoch}`. `scope.sessionId` is the host parent SDK session ID, not a path or broker endpoint. Existing top-level `sessionId` still identifies broker self (status/connection) or departing peer (leave). The epoch is shared with subagent snapshots and rotates on rebind/reload; discard obsolete scope pairs. Broker reconnect within a binding keeps the epoch.