@selesai/code 0.5.27 → 0.5.29

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

@@ -0,0 +1,249 @@
+# Changelog
+
+All notable changes to the `pi-intercom` extension will be documented in this file.
+
+## [Unreleased]
+
+## [0.9.2] - 2026-08-03
+
+### Fixed
+- Avoid relaunching standalone Pi executables as the Node runtime when starting the default broker process. Thanks to ZacharyQin for PR #82 and to jeffutter and awaae001 for confirming the impact.
+
+## [0.9.1] - 2026-07-30
+
+### Fixed
+- Scoped name-based queued-mail redelivery to sessions that also match the target's directory. A disconnected session's queued messages, including replies addressed to its exact session ID, could previously be delivered to an unrelated same-named session in a different project folder. Directories compare through the same normalization used by `list-cwd`, so a relaunch reporting the same directory via a trailing slash or symlink still receives its mail.
+
+### Changed
+- Rewrote the broker frame reader as a bounded state machine and made frame writes a single allocation, removing quadratic `Buffer.concat` accumulation on fragmented socket reads (up to ~28x faster on heavily fragmented frames).
+- Cached the collapsed preview and width-keyed wrapped body lines in the inline message renderer, cutting repeated rerender cost of long messages by ~2-3x while keeping live theme changes applied per render.
+
+## [0.9.0] - 2026-07-29
+
+### Added
+- Added a bounded in-memory broker mailbox so replies to recently disconnected named CLI senders are queued and delivered when a process reconnects with the same name. Thanks to Luke (`valkyriweb`) for issue #63.
+- Added protocol-visible delivery metadata, receiver lifecycle receipts, receiver-side inbound message dedupe, explicit cancel/supersede controls, and clearer ask-timeout receipts for ordered delivery diagnostics. Thanks to Donnie Thomas (`donnielrt`) for issue #65.
+
+## [0.8.0] - 2026-07-29
+
+### Added
+- Added opt-in restart-stable intercom session IDs via `PI_INTERCOM_STABLE_ID` or `stableId` in `config.json`. Thanks to iRonin for issue #39.
+- Added `/intercom-id` to insert a stable handoff snippet for the current session into the editor. Thanks to dataforxyz for PR #60.
+- Added `intercom({ action: "list-cwd" })` to list peers scoped to the same working directory. Thanks to iRonin for PR #58.
+- Added live context-window usage to session presence and list output. Thanks to iRonin for PR #59.
+- Added a silent namespaced extension bus for non-conversational extension coordination. Thanks to Kieran Bond for PR #69.
+
+## [0.7.0] - 2026-07-29
+
+### Changed
+- Documented `PI_INTERCOM_ASK_TIMEOUT_MS` for configurable ask/supervisor timeouts. Thanks to wiansapu for issue #14.
+- Clarified session addressing copy so the short IDs shown by `list` are documented as usable prefixes. Thanks to Grant Hutchins for PR #66.
+- Updated Pi runtime peer metadata and tool schemas for the `@earendil-works` package scope and Pi-bundled `typebox`/`pi-ai` packages.
+- Centralized pi-intercom runtime and config paths under `PI_CODING_AGENT_DIR` when set, defaulting to `~/.pi/agent`.
+- Hardened default broker auto-spawn to launch the resolved bundled `tsx` CLI through the current Node executable instead of resolving `npx` through `PATH`; custom `brokerCommand`/`brokerArgs` remain available as advanced trusted config.
+- Added an `inboundTrigger` policy (`always`, `replies`, or `never`) so users can reduce inbound auto-trigger risk while preserving existing behavior by default.
+- Made inline intercom messages collapse and expand with Pi's `Ctrl+O` custom-message toggle while keeping sender, preview, reply, and attachment cues visible. Thanks to RyanKim17920 for PR #32.
+- Improved inline message theme hierarchy with separate semantic styling for borders, headers, body text, and metadata. Thanks to Sreenath for PR #68.
+
+### Fixed
+- Added broker-owned local trust metadata, clearer stable-ID trust boundaries for duplicate names, per-connection rate limiting, and no-op presence coalescing for local IPC abuse hardening.
+- Added an inbound broker frame size cap to reject oversized local IPC messages before buffering their payloads.
+- Restricted Unix intercom runtime directory, socket, PID, and spawn-lock permissions.
+- Rechecked single-flight ask state after session target resolution so concurrent regular asks fail safely instead of crashing on an unhandled rejected reply waiter.
+- Refused broker-level mutual asks that would deadlock two sessions, and cleared outstanding ask edges when asks are replied to, cancelled, or disconnected.
+- Stabilized intercom session addressing across reconnects, idle `/name` changes, replaced Pi sessions, supervisor routing, pending replies, and short-ID targeting.
+- Aligned intercom overlay widths with their rendered modal boxes. Thanks to Cat for PR #43.
+- Marked failed `intercom` and `contact_supervisor` tool results through Pi's `tool_result` error flag path while preserving structured renderer details.
+- Limited the intercom overlay to TUI mode and unsubscribed subagent relay event handlers during session shutdown.
+- Added an opt-in Windows localhost TCP transport using a dynamic port, broker protocol health checks, and a local endpoint secret instead of a fixed-port default.
+- Stabilized reply/supervisor routing by respecting explicit reply targets, suppressing legacy supervisor tools when native supervisor channels are present, and clearing replied idle-queued asks. Thanks to ThanhNT29Jacky for PR #64.
+
+## [0.6.0] - 2026-05-03
+
+### Added
+- Added `brokerCommand` and `brokerArgs` config options for choosing the broker runtime command. Thanks to William Fligor for PR #12.
+
+## [0.5.0] - 2026-05-03
+
+### Changed
+- Busy interactive sessions now queue inbound intercom messages until the receiver is idle instead of aborting the active turn.
+- Sessions now publish automatic lifecycle status (`idle`, `thinking`, or `tool:<name>`) through intercom presence updates.
+- Deferred startup connection, delayed inbound flushes, overlay work, reconnect attempts, and relay callbacks now guard against stale session contexts after shutdown or reload.
+- `intercom` and `contact_supervisor` tool calls/results now use compact custom transcript renderers.
+
+## [0.4.1] - 2026-05-02
+
+### Added
+- Added `contact_supervisor` `reason: "interview_request"` for child subagents to send structured supervisor interviews, wait for a reply, and receive parsed JSON replies in tool result details when available.
+
+### Fixed
+- Busy non-interactive sessions now auto-reply to top-level intercom messages instead of aborting and losing the message.
+
+## [0.4.0] - 2026-05-02
+
+### Added
+- Added a `contact_supervisor` tool for `pi-subagents` child sessions so delegated agents can request supervisor decisions or send meaningful progress updates with run metadata.
+- Documented subagent-to-supervisor escalation in the README and bundled `pi-intercom` skill.
+
+### Fixed
+- Made inline intercom message cards use the available terminal width instead of a narrow fixed width.
+- Cleared supervisor ask waiters correctly after cancellation or delivery failure so subagents can ask again.
+
+### Changed
+- Stopped tracking `package-lock.json` and ignored local `progress.md` memory files.
+
+## [0.3.0] - 2026-04-27
+
+### Added
+- Added `pi-subagents` grouped result relay support over `pi-intercom`, including delivery acknowledgments so parent runs can return compact receipts only after the orchestrator receives the result message.
+
+## [0.2.1] - 2026-04-26
+
+### Fixed
+- Delivered `pi-subagents` needs-attention control events to the orchestrator over intercom.
+
+## [0.2.0] - 2026-04-22
+
+### Added
+- Added receiver-side `reply` ergonomics for inbound asks. Agents can now use `intercom({ action: "reply", message })` in the triggered turn or later against a single pending ask, plus `intercom({ action: "pending" })` to inspect unresolved inbound asks.
+
+### Fixed
+- Migrated extension tool schemas from `@sinclair/typebox` to `typebox` 1.x so packaged installs follow Pi's current extension runtime contract.
+- Included `reply-tracker.ts` in the published package so installed extensions can load the new reply-tracking helper at runtime.
+- Updated the integration test harness to set `USERPROFILE` alongside `HOME`, keeping temp-home isolation reliable on Windows.
+
+### Changed
+- Moved TypeBox from `peerDependencies` to a real `dependencies` entry so `pi install` production installs keep the schema package available at runtime.
+- Incoming ask reply hints now prefer `intercom({ action: "reply", ... })` instead of exposing raw `to` and `replyTo` identifiers.
+- Updated the bundled `pi-intercom` skill and README examples to prefer `reply`/`pending` over manual reply threading.
+
+## [0.1.11] - 2026-04-20
+
+### Added
+- Bundled `pi-intercom` skill with coordination patterns, error handling, constraints, and optional cmux/tmux peer-session spawning for visible multi-session workflows.
+- `pi.skills` manifest in `package.json` so `pi install` loads the skill automatically.
+- AGENTS.md snippet in README recommending a project-level coordination hint for agents.
+- Attachments example to Quick Start section in README.
+
+### Changed
+- Incoming message reply hints now say "To reply, use the intercom tool:" instead of "— reply:" so agents are more likely to use the intercom tool instead of replying inline.
+- `ask` action now documents the one-at-a-time constraint in the Tool Reference.
+- `status` action now clarifies that the session count includes the current session.
+- Broker startup no longer uses a non-null assertion for sender session lookup in the `send` handler — missing sessions now produce a `delivery_failed` response instead of a crash.
+- Broker spawn lock error handling tightened to check `instanceof Error` before accessing `.code`.
+- Broker PID parsing now guards against `NaN` from corrupt PID files.
+- `isConnected()` readability cleanup in `IntercomClient`.
+- README file structure updated to include `broker/paths.ts`, test files, and `skills/` directory.
+- README runtime files section now clarifies that `broker.sock` is macOS/Linux only; Windows uses a named pipe.
+- README mermaid diagram changed "Unix Socket" to "Local Socket/Pipe" for cross-platform accuracy.
+- README broker limitation rephrased from "must be running" to "auto-spawns on first use and exits when idle."
+- README Install section now mentions that the bundled skill is registered on startup.
+
+## [0.1.10] - 2026-04-17
+
+### Fixed
+- Broker startup now works on Windows by launching the local `tsx` CLI through a hidden `wscript.exe` helper without treating the helper's expected early exit as a broker failure.
+
+### Changed
+- The broker now uses a Windows named pipe instead of a Unix socket on Windows, while keeping the existing Unix socket transport on macOS and Linux.
+
+## [0.1.9] - 2026-04-17
+
+### Fixed
+- Declared the extension entry in `package.json` via `pi.extensions` so `pi install npm:pi-intercom` can discover and load the extension from the npm package.
+
+### Changed
+- Added `pi-package` package metadata plus peer dependency declarations for every Pi runtime package the extension imports, including `@mariozechner/pi-tui`.
+
+## [0.1.8] - 2026-04-14
+
+### Changed
+- Intercom sessions now reconnect automatically after broker disconnects or sleep/wake interruptions instead of staying offline until reload or restart.
+- Replaced raw runtime `console.error` intercom disconnect logging with silent recovery so transient broker churn no longer splashes stray text into the Pi TUI.
+
+## [0.1.7] - 2026-04-13
+
+### Changed
+- Unnamed sessions now register a runtime-only `subagent-chat-<id>` intercom alias instead of persisting a generic session title into Pi session history, so `pi --resume` can keep showing transcript snippets while unnamed sessions remain reachable over intercom.
+- Intercom presence updates now refresh the advertised session name during later turn/intercom activity, so renaming a session does not leave subagents and peers targeting a stale startup alias.
+
+## [0.1.6] - 2026-04-13
+
+### Changed
+- Busy incoming intercom messages now try a graceful detach handshake with `pi-subagents` before falling back to interrupting the active turn.
+- Reply follow-ups are deferred and re-delivered as follow-up wakeups so final confirmation messages stop causing unnecessary `Operation aborted` interruptions.
+- Unnamed sessions now auto-register a stable `session-<id>` display name so orchestrators and delegated children can target each other reliably without a manual `/name`.
+
+## [0.1.5] - 2026-04-13
+
+### Changed
+- Switched intercom send confirmation to opt-in. `send` now delivers immediately by default, and interactive confirmation only appears when `confirmSend: true` is set in `~/.pi/agent/intercom/config.json`.
+- Replaced the old inverted `autoSend` config with `confirmSend` to make the behavior easier to understand.
+
+## [0.1.4] - 2026-04-13
+
+### Added
+- Added an MIT `LICENSE` file and set `package.json` `license` to `MIT`.
+
+### Changed
+- Updated `README.md` to mention the `pi-subagents` integration and link to https://github.com/nicobailon/pi-subagents.
+
+## [0.1.3] - 2026-04-10
+
+### Changed
+- **Clearer self vs peer identity** — `intercom({ action: "list" })` now shows `Current session` and `Other sessions`, includes short session IDs, and marks same-folder peers with `[same cwd]` so agents are less likely to mistake another session in the same repo for themselves.
+- **Picker self anchor** — The session picker now shows the current session as a disabled `[self]` row at the top while keeping only peer sessions selectable.
+
+## [0.1.2] - 2026-04-04
+
+### Changed
+- **Reply flows skip approval** — `send` calls that include `replyTo` now bypass the confirmation dialog so reply-hint conversations can continue without an extra approval step.
+- **Overlay readability** — The session picker now shows session name/model on the first line and the cwd on a second line with middle truncation, making long paths much easier to distinguish.
+- **Documentation clarity** — The README now explains which sessions appear in the picker, how sessions become intercom-connected, and the difference between user-facing `/intercom` usage and agent tool calls.
+
+### Fixed
+- **Compose overlay crash** — Replaced the invalid `tui.scheduleRender()` calls with `tui.requestRender()`, fixing the compose overlay crash while typing or sending.
+- **Overlay panel chrome** — Restored bordered modal rendering for the session picker and compose overlay so they display as proper overlays instead of floating unboxed content.
+
+## [0.1.1] - 2026-04-04
+
+### Changed
+- Added a `promptSnippet` for the `intercom` tool so Pi 0.59+ includes it in the default tool prompt section and improves session-to-session coordination discoverability.
+
+### Changed
+- **Pi compatibility refresh** — Updated the extension to match current Pi lifecycle and custom UI APIs, including `session_start` / `session_shutdown` and injected `ctx.ui.custom()` keybindings.
+- **Overlay keybindings** — The session picker and compose overlay now use injected, namespaced Pi keybindings instead of reading editor-global bindings directly.
+- **Session list correlation** — `list` / `sessions` now carry a `requestId`, so a delayed broker reply cannot be mistaken for a newer session-list request.
+- **Reply sends skip approval** — `send` calls that include `replyTo` now bypass the confirmation dialog so reply-hint flows work without an extra approval step.
+- **Documentation accuracy** — The README now matches the current implementation, including request correlation, persistence behavior, broker disconnect behavior, and the file layout.
+
+### Fixed
+- **Protocol state handling** — Broker and client now reject malformed, unknown, duplicate, and out-of-order protocol messages instead of silently accepting them.
+- **Duplicate-name routing** — Sends to a duplicated session name now fail with an explicit error instead of routing to the first match.
+- **Delivery failure visibility** — `delivery_failed.reason` now flows through the client, tool results, and compose overlay error UI.
+- **Disconnect and startup errors** — Broker spawn failures, early broker exits, protocol failures, and disconnects now preserve the real error instead of collapsing to generic messages.
+- **Disconnect-time writes** — Client operations now fail cleanly during disconnect instead of writing to a closing socket and triggering `write after end` errors.
+- **Late-response handling** — Timed-out send/list requests no longer disconnect the client, and delayed list responses can no longer contaminate a later request with stale data.
+- **Config validation** — Invalid intercom config values are now reported and ignored instead of silently producing a broken runtime config.
+
+## [0.1.0] - 2026-03-12
+
+### Added
+- **`ask` action** — `intercom({ action: "ask", to, message })` now sends a message and blocks until the recipient replies, returning the reply as the tool result. Includes a 10-minute timeout, abort handling, disconnect handling, and shutdown cleanup.
+- **Exact reply hints** — Incoming messages can now include a ready-to-run reply command that uses the sender's exact session ID as `to` and the original message ID as `replyTo`, making synchronous `ask`/reply flows reliable.
+- **Attachment body rendering for incoming messages** — Incoming attachment contents are now appended to the agent-visible message body so recipients can read attached file/snippet/context content directly.
+- **Planner/worker workflow documentation** — README now documents the intended planner-worker loop, including `send` vs `ask`, clarification patterns, and reply-hint behavior.
+
+### Changed
+- **Session target resolution** — `send` and `ask` now resolve a unique case-insensitive session name to its exact session ID before sending. Ambiguous names are rejected instead of guessed.
+- **Duplicate-name presentation** — Session labels are now disambiguated consistently across `list`, the session picker, the compose overlay, and send notifications by appending a short session ID when names collide.
+- **Send confirmation dialog** — Confirmation text now includes attachment content previews and `replyTo` metadata so outgoing messages are reviewed accurately before sending.
+- **Inline message rendering** — The custom inline renderer now shows the fully rendered message body, optional reply command, attachment summaries, and reply metadata consistently with what the agent receives.
+
+### Fixed
+- **False `ask` completions from unrelated messages** — Reply matching now requires an exact `replyTo` match and the expected sender, preventing unrelated incoming messages from unblocking a waiting `ask`.
+- **Self-targeted messages** — `send` and `ask` now reject attempts to message the current session instead of allowing loops or self-waits.
+- **Undelivered `ask` cleanup** — If an `ask` message is not delivered, the waiting state is torn down cleanly instead of lingering.
+- **Inline renderer/body mismatch** — The custom message renderer now matches the actual delivered message body for messages with attachments instead of showing a reduced view.
+- **Duplicate-name ambiguity when self shares a name** — Duplicate-name detection now considers all connected sessions, so another session is still disambiguated when it shares a name with the current session.
+- **`broker/client.ts` `sessions` switch scoping** — Braced the `sessions` case to avoid block-scoping hazards in the message handler.

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

@@ -2,9 +2,9 @@
   <img src="banner.png" alt="pi-intercom" width="1100">
 </p>
 
-# Pi Intercom
+# Selesai Intercom
 
-Direct 1:1 messaging between pi sessions on the same machine. Send context, findings, or requests from one session to another — whether you're driving the conversation or letting agents coordinate.
+Direct 1:1 messaging between Selesai sessions on the same machine. Send context, findings, or requests from one session to another — whether you're driving the conversation or letting agents coordinate.
 
 ```text
 User flow: press Alt+M or run /intercom to pick a session and send a message
@@ -12,33 +12,33 @@ User flow: press Alt+M or run /intercom to pick a session and send a message
 
 ## Why
 
-Sometimes you're running multiple pi sessions — one researching, one executing, one reviewing. Pi-intercom lets you:
+Sometimes you're running multiple Selesai sessions — one researching, one executing, one reviewing. pi-intercom lets you:
 
 - **User-driven orchestration** — Send context or findings from your research session to your execution session
 - **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
+- **Session awareness** — See what other Selesai 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.
 
-Pi-intercom also integrates well with [pi-subagents](https://github.com/nicobailon/pi-subagents): delegated child agents get a child-only `contact_supervisor` tool when `pi-subagents` supplies bridge metadata. Use `reason: "need_decision"` for blocking clarification, `reason: "interview_request"` for multiple structured supervisor answers, and `reason: "progress_update"` for meaningful plan-changing updates. Normal sessions only see the regular `intercom` tool.
+pi-intercom also integrates well with [pi-subagents](https://github.com/nicobailon/pi-subagents): delegated child agents get a child-only `contact_supervisor` tool when `pi-subagents` supplies bridge metadata. Use `reason: "need_decision"` for blocking clarification, `reason: "interview_request"` for multiple structured supervisor answers, and `reason: "progress_update"` for meaningful plan-changing updates. Normal sessions only see the regular `intercom` tool.
 
 ## In One Minute
 
-Each pi session that has `pi-intercom` loaded and enabled connects to a tiny local broker over a local IPC transport. The broker keeps track of connected sessions and routes direct messages to the one you target by name or session ID. The extension gives you both a tool (`intercom`) and a small overlay UI (`/intercom` or `Alt+M`). Incoming messages are rendered inline inside the recipient session, can trigger a turn immediately, and are also stored in Pi session history as extension entries.
+Each Selesai session that has `pi-intercom` loaded and enabled connects to a tiny local broker over a local IPC transport. The broker keeps track of connected sessions and routes direct messages to the one you target by name or session ID. The extension gives you both a tool (`intercom`) and a small overlay UI (`/intercom` or `Alt+M`). Incoming messages are rendered inline inside the recipient session, can trigger a turn immediately by default, and are also stored in Selesai session history as extension entries. If you want a stricter local trust posture, `inboundTrigger` can reduce or disable auto-triggering.
 
 ## Install
 
 ```bash
-pi install npm:pi-intercom
+selesai install npm:pi-intercom
 ```
 
-Then restart Pi. The extension auto-connects to the broker on startup and registers the bundled `pi-intercom` skill for common coordination patterns.
+Then restart Selesai. The extension auto-connects to the broker on startup and registers the bundled `pi-intercom` skill for common coordination patterns.
 
 **Recommended:** Add this snippet to your project's `AGENTS.md` to help agents understand when to coordinate across sessions:
 
 ```xml
 <pi-intercom>
-Coordinate with other local pi sessions on related codebases. Use `/skill:pi-intercom` for patterns.
+Coordinate with other local Selesai sessions on related codebases. Use `/skill:pi-intercom` for patterns.
 
 **When:** Same codebase (parallel work), reference codebase (consulting patterns), related repos (shared libraries).
 
@@ -50,13 +50,13 @@ Coordinate with other local pi sessions on related codebases. Use `/skill:pi-int
 
 A session becomes intercom-connected when all of these are true:
 - the `pi-intercom` extension is installed and loaded in that session
-- `enabled` is not set to `false` in `~/.pi/agent/intercom/config.json`
+- `enabled` is not set to `false` in the intercom config file, which defaults to `~/.selesai/agent/intercom/config.json`
 - the session has started or reloaded after the extension was installed
 - the local broker is running or can be auto-started
 
-The session list only shows intercom-connected sessions, not every open Pi process on the machine.
+The session list only shows intercom-connected sessions, not every open Selesai process on the machine.
 
-If a session is unnamed, pi-intercom now exposes a runtime-only fallback alias like `subagent-chat-1a2b3c4d` so other sessions can still target it. That alias is not persisted as the Pi session title, so `pi --resume` can keep showing the transcript snippet instead of a generic `session-...` name.
+If a session is unnamed, pi-intercom now exposes a runtime-only fallback alias like `subagent-chat-1a2b3c4d` so other sessions can still target it. That alias is not persisted as the Selesai session title, so `selesai --resume` can keep showing the transcript snippet instead of a generic `session-...` name.
 
 ## Quick Start
 
@@ -70,16 +70,19 @@ Press **Alt+M** or type `/intercom` to open the session list overlay:
 
 ### 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. For common patterns like planner-worker delegation, the bundled `pi-intercom` skill provides copy-paste ready examples:
+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:
 
 ```typescript
 // List active sessions
 intercom({ action: "list" })
 // → **Current session:**
-// → • executor (20d43841) — ~/projects/api (claude-sonnet-4) [self, idle]
+// → • executor (20d43841) — ~/projects/api (claude-sonnet-4 · 42% ctx) [self, idle]
 // → **Other sessions:**
 // → • research (6332faab) — ~/projects/api (claude-sonnet-4) [same cwd, thinking]
 
+// List only peers in the same working directory
+intercom({ action: "list-cwd" })
+
 // Send a message
 intercom({ action: "send", to: "research", message: "Check if UserService.validate() handles null" })
 // → Message sent to research
@@ -115,7 +118,7 @@ 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 once they go idle. Attachment content is included in the agent-visible body, and messages are rendered inline and stored in Pi 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; busy interactive recipients receive the message once they go idle. Attachment content is included in the agent-visible body, and messages are rendered inline and stored in Selesai session history.
 
 ## Workflow: Planner-Worker Coordination
 
@@ -208,10 +211,16 @@ This matters because the agent receiving the message doesn't need to reconstruct
 
 `send` is fire-and-forget — the tool returns immediately after delivery. By default, it sends immediately even in interactive sessions. If you want an approval dialog before non-reply sends, set `confirmSend: true` in config. Replies that include `replyTo` still skip confirmation so reply-hint flows can continue without an extra approval step.
 
-`ask` sends the message and blocks until the recipient responds (10-minute timeout). The reply comes back as the tool result, so the agent continues in the same turn with full context. No confirmation dialog — if you're asking and waiting, the intent is clear.
+`ask` sends the message and blocks until the recipient responds (10-minute timeout by default; set `PI_INTERCOM_ASK_TIMEOUT_MS` to a positive millisecond value to change it). The reply comes back as the tool result, so the agent continues in the same turn with full context. No confirmation dialog — if you're asking and waiting, the intent is clear.
 
 `reply` is receiver-side sugar for replying to an inbound ask. In the turn triggered by an incoming intercom ask, `intercom({ action: "reply", message: "..." })` targets that exact sender and message automatically. If you reply later, it falls back to the single unresolved inbound ask. If multiple asks are pending, use `intercom({ action: "pending" })` to inspect them and then call `reply` with `to` to disambiguate.
 
+The broker keeps a bounded in-memory mailbox for recently disconnected 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 name receives the queued reply. This is per-broker runtime state, not durable storage across broker restarts.
+
+Incoming messages now carry diagnostic metadata end to end: stable message ID, sender sequence, sender timestamp, broker receive/delivery timestamps, receiver receive timestamp, and injection timestamp. Receivers emit lifecycle receipts for `receiver_received`, `acknowledged`, `queued`, `injected`, `expired`, `cancelled`, `superseded`, and `cancellation_requested`; duplicate message IDs are acknowledged but injected at most once per receiving session. If an `ask` times out, the timeout names the message ID and last known delivery state. Timeout is not cancellation: the recipient may still have the message queued or 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. If the receiver has not injected it yet, it is removed from the queue and reported as `cancelled`; if it is already injected or processed, the receiver reports `cancellation_requested` instead of hiding it. 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 message ID. 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: Subagent-to-Supervisor Escalation
@@ -222,10 +231,10 @@ This workflow requires [`pi-subagents`](https://github.com/nicobailon/pi-subagen
 
 `contact_supervisor` only registers when `pi-subagents` sets all of these environment variables:
 
-- `PI_SUBAGENT_ORCHESTRATOR_TARGET` — the supervisor session name or ID
-- `PI_SUBAGENT_RUN_ID` — the run identifier
-- `PI_SUBAGENT_CHILD_AGENT` — the agent type
-- `PI_SUBAGENT_CHILD_INDEX` — the child index within the run
+- `SELESAI_SUBAGENT_ORCHESTRATOR_TARGET` — the supervisor session name or ID
+- `SELESAI_SUBAGENT_RUN_ID` — the run identifier
+- `SELESAI_SUBAGENT_CHILD_AGENT` — the agent type
+- `SELESAI_SUBAGENT_CHILD_INDEX` — the child index within the run
 
 If any are missing, the session falls back to the regular `intercom` tool.
 
@@ -233,7 +242,7 @@ If any are missing, the session falls back to the regular `intercom` tool.
 
 | Reason | Behavior | Use When |
 |--------|----------|----------|
-| `need_decision` | Sends an ask and blocks until the supervisor replies (10-minute timeout) | The subagent is blocked, uncertain, needs approval, or faces a product/API/scope decision |
+| `need_decision` | Sends an ask and blocks until the supervisor replies (10-minute timeout by default; configurable with `PI_INTERCOM_ASK_TIMEOUT_MS`) | The subagent is blocked, uncertain, needs approval, or faces a product/API/scope decision |
 | `interview_request` | Sends structured questions and blocks until the supervisor replies | The subagent needs multiple machine-readable answers from the supervisor in one exchange |
 | `progress_update` | Fire-and-forget update to the supervisor | Meaningful progress or unexpected discoveries that change the plan |
 
@@ -312,11 +321,14 @@ The supervisor can reply with plain JSON or a fenced `json` block. If the reply
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `action` | string | `"list"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"` |
+| `action` | string | `"list"`, `"list-cwd"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, `"status"`, or `"cancel"` |
 | `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` |
+| `messageId` | string | Optional explicit message ID for send/ask, or required message ID for `cancel` |
+| `supersedes` | string | Optional previous message ID that this send/ask explicitly replaces |
+| `retryOf` | string | Optional previous message ID that this send/ask explicitly retries |
 
 ### contact_supervisor
 
@@ -328,7 +340,7 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 | `message` | string | The decision request, optional interview note, or progress update |
 | `interview` | object | Required for `interview_request`: `{ title?, description?, questions: [...] }` |
 
-**`need_decision`** — Sends a formatted ask to the supervisor and blocks until it replies (10-minute timeout). The reply comes back as the tool result. Includes run metadata in the message so the supervisor knows which subagent is asking.
+**`need_decision`** — Sends a formatted ask to the supervisor and blocks until it replies (10-minute timeout by default; configurable with `PI_INTERCOM_ASK_TIMEOUT_MS`). The reply comes back as the tool result. Includes run metadata in the message so the supervisor knows which subagent is asking.
 
 **`interview_request`** — Sends a formatted, agent-readable interview to the supervisor and blocks until it replies. Questions use a local pi-interview-like shape: `{ id, type, question, options?, context? }` where `type` is `single`, `multi`, `text`, `image`, or `info`. `info` questions are context-only and do not need responses. The supervisor reply should be JSON with `{ "responses": [{ "id": "...", "value": ... }] }`. Parsed JSON replies are returned in `details.structuredReply`.
 
@@ -336,16 +348,18 @@ 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 Pi 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, and live status. Status is derived automatically from Selesai lifecycle events: `idle`, `thinking`, or `tool:<name>`.
 
 **`send`** — Sends a message to the specified session. By default it sends immediately, including in interactive sessions. Set `confirmSend: true` in config if you want a confirmation dialog for non-reply sends. Replies that include `replyTo` skip confirmation. Returns delivery confirmation.
 
-**`ask`** — Sends a message and waits for the recipient to reply (10-minute timeout). 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.
+**`ask`** — Sends a message and waits for the recipient to reply (10-minute timeout by default; configurable with `PI_INTERCOM_ASK_TIMEOUT_MS`). 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.
 
 **`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.
 
+**`cancel`** — Requests cancellation of a message previously sent by the current session. Queued messages are removed before injection; already-injected messages receive a visible cancellation request.
+
 **`status`** — Shows connection status, session ID, and total count of active sessions (including the current session).
 
 ## Keyboard Shortcuts
@@ -359,13 +373,14 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 
 ## Config
 
-Create `~/.pi/agent/intercom/config.json`:
+Create `~/.selesai/agent/intercom/config.json`:
 
 ```json
 {
   "brokerCommand": "npx",
   "brokerArgs": ["--no-install", "tsx"],
   "confirmSend": false,
+  "inboundTrigger": "always",
   "enabled": true,
   "replyHint": true,
   "status": "researching"
@@ -374,14 +389,17 @@ Create `~/.pi/agent/intercom/config.json`:
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `brokerCommand` | `"npx"` | Command used to start the local broker process |
-| `brokerArgs` | `["--no-install", "tsx"]` | Arguments passed to `brokerCommand` before the broker script path |
+| `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`. |
+| `brokerArgs` | `["--no-install", "tsx"]` | Advanced trusted arguments passed to custom `brokerCommand` before the broker script path |
 | `confirmSend` | false | Show a confirmation dialog before non-reply sends from an interactive session with UI |
+| `inboundTrigger` | `"always"` | Auto-trigger policy for inbound broker messages: `"always"`, `"replies"`, or `"never"`. Local in-process subagent relay events still trigger the addressed session. |
 | `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` |
 
-For example, if you have Bun installed and want it to start the broker directly, use:
+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.
+
+Custom broker commands are trusted local configuration: anyone who can edit this config can choose the executable used for future broker auto-spawns. For example, if you have Bun installed and want it to start the broker directly, use:
 
 ```json
 {
@@ -390,13 +408,52 @@ For example, if you have Bun installed and want it to start the broker directly,
 }
 ```
 
-Pi-intercom publishes live session status automatically. Sessions register as `idle`, switch to `thinking` while the agent is running, show `tool:<name>` during tool execution, and return to `idle` on agent completion. If `status` is set in config, it is appended as context instead of replacing the lifecycle status.
+pi-intercom publishes live session status automatically. Sessions register as `idle`, switch to `thinking` while the agent is running, show `tool:<name>` during tool execution, and return to `idle` on agent completion. If `status` is set in config, it is appended as context instead of replacing the lifecycle status.
+
+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.
+
+## 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.
+
+Register during `session_start` so intercom includes the capability in its deferred broker registration:
+
+```typescript
+import type { ExtensionAPI } from "@selesai/code";
+import {
+  INTERCOM_EXTENSION_REGISTER_EVENT,
+  type IntercomExtensionChannel,
+} from "pi-intercom/extension-api.ts";
+
+export default function (pi: ExtensionAPI) {
+  let channel: IntercomExtensionChannel | undefined;
+
+  pi.on("session_start", () => {
+    pi.events.emit(INTERCOM_EXTENSION_REGISTER_EVENT, {
+      namespace: "example/v1",
+      ownerEligible: true,
+      onReady: (value: IntercomExtensionChannel) => { channel = value; },
+      onEvent: (event: unknown) => { /* owner, state, peer, or payload event */ },
+    });
+  });
+}
+```
+
+The broker:
+
+- advertises `extension-bus-v1` through feature negotiation
+- routes payloads only to sessions advertising the same namespace
+- elects one owner per namespace and changes its epoch after socket replacement
+- rejects stale owner-only writes
+- stores at most 64 KiB of opaque, revisioned state per namespace
+
+`channel.publish()` accepts payloads up to 16 KiB. A `capable` broadcast includes the sender, so consumers must not blindly republish messages they receive. `channel.commitState()` uses compare-and-swap against the last observed revision. Capabilities registered after the broker connection is established are synchronized without reconnecting. Clients connected to an older broker see the channel as unsupported and do not send extension operations.
 
 ## How It Works
 
 ```mermaid
 graph TB
-    subgraph A["Pi Session A"]
+    subgraph A["Selesai Session A"]
         A1[Intercom Client]
         A2[intercom tool]
         A3[UI overlays]
@@ -407,7 +464,7 @@ graph TB
         B2[Message Router]
     end
 
-    subgraph B["Pi Session B"]
+    subgraph B["Selesai Session B"]
         B3[Intercom Client]
         B4[intercom tool]
         B5[UI overlays]
@@ -420,19 +477,25 @@ graph TB
 
 The broker is a standalone TypeScript process that manages session registration and message routing. It auto-spawns when the first intercom-enabled session needs it and exits after 5 seconds when the last connected session disconnects. Clients now reconnect automatically if the broker disappears and later comes back.
 
-Messages use length-prefixed JSON over a local socket/pipe transport (4-byte length + JSON payload) to handle fragmentation properly. The protocol includes request correlation for session listing, explicit delivery failures, and validation for malformed or out-of-order messages.
+Messages use length-prefixed JSON over a local socket/pipe transport (4-byte length + JSON payload) to handle fragmentation properly. The protocol includes request correlation for session listing, explicit delivery failures, validation for malformed or out-of-order messages, a frame-size cap, per-connection local rate limiting, and no-op presence coalescing.
+
+Session IDs are the trusted addressing key. Duplicate names remain allowed for same-user workflows, but sends to ambiguous names fail and users should target the stable session ID shown by `list`/`status` in trust-sensitive flows. Mail queued for a disconnected session is redelivered to a session that reconnects under the same session ID, or to a session that matches both its name and its directory, so a same-named session in a different project never inherits another project's queued messages. Set `PI_INTERCOM_STABLE_ID` or `stableId` in `config.json` to pin a session's intercom ID across full process relaunches; `config.json` is machine-global, so a fixed `stableId` there applies to every session on the machine and the newest registration takes over that identity. The broker owns local trust metadata such as `trustedLocal`; `peerUid` is reserved for runtimes that can expose real peer credentials and is left unset otherwise. Client-supplied cwd/model/pid/status are display metadata, not authentication.
 
 Async extension work (startup, inbound flushes, reconnects, overlays, and relays) no-ops if the session shuts down or reloads before it settles.
 
-Runtime files live at `~/.pi/agent/intercom/`:
+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.
+
 ## Design Decisions
 
-**Local IPC instead of TCP.** Same-machine only by design. `pi-intercom` uses Unix sockets on macOS/Linux and a named pipe on Windows, which keeps setup simple and avoids port management.
+**Local IPC instead of TCP.** Same-machine only by design. `pi-intercom` uses Unix sockets on macOS/Linux and a named pipe on Windows, which keeps setup simple and avoids port management. Windows TCP is available only as an explicit escape hatch with `PI_INTERCOM_TRANSPORT=tcp` (or `PI_INTERCOM_TCP=1`) for environments where named pipes are blocked. In that mode the broker binds a dynamic `127.0.0.1` port, records the endpoint plus a local secret under the intercom state dir, and requires that secret before health or registration succeeds. Health replies do not echo the secret, so a random localhost process cannot discover it through the broker protocol.
 
 **Auto-spawn with file lock.** The broker starts on first connection and exits after 5 seconds idle. There is no daemon to manage. A spawn lock file, keyed by PID and timestamp, prevents duplicate brokers when multiple sessions start at once.
 
@@ -446,14 +509,14 @@ Runtime files live at `~/.pi/agent/intercom/`:
 | **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 |
+| **Persistence** | In Selesai 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
 
 ```
-~/.pi/agent/extensions/pi-intercom/
+~/.selesai/agent/extensions/pi-intercom/
 ├── package.json
 ├── index.ts              # Extension entry point
 ├── types.ts              # SessionInfo, Message, protocol types
@@ -478,7 +541,7 @@ Use pi-messenger for multi-agent swarms working on a shared task. Use pi-interco
 ## Limitations
 
 - **Same machine only** — Uses local sockets/pipes, no network support
-- **No dedicated intercom log** — Messages are kept in Pi session history, but there is no separate intercom transcript or inbox
+- **No dedicated intercom log** — Messages are kept in Selesai session history, but there is no separate intercom transcript or inbox
 - **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 Pi sessions that have loaded `pi-intercom` and successfully registered with the broker, not every open Pi process on the machine
+- **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