pi-link 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -2,21 +2,49 @@
 
 All notable changes to pi-link are documented here.
 
-This changelog is based on the git history from `2026-03-21` through `2026-04-03` (current). Versions correspond to npm publishes.
+This changelog is based on the git history from `2026-03-21` (initial commit) through the present. Versions correspond to npm publishes.
+
+---
+
+## 0.1.8 — 2026-04-16
+
+### Added
+
+- **Idle-gated batched delivery for `triggerTurn:true`.** `link_send` with `triggerTurn:true` no longer calls `pi.sendMessage()` immediately. Messages queue in a local inbox, coalesce over a 200ms debounce window, and flush only when the receiver is idle (`ctx.isIdle()`). Delivered as a single `[Link: N message(s) received]` block at the start of a fresh turn. Avoids a Pi platform race where mid-run steering messages can be stranded. `triggerTurn:false` is unchanged (immediate fire-and-forget). (`82977ec`, `ca2996b`)
+
+- **Session name as default terminal identity.** When no explicit `/link-name` is saved for a session, the terminal now adopts the Pi session name instead of a random `t-xxxx` ID. The session name is used at runtime only — it is not saved as `preferredName`, so only explicit `/link-name` calls persist across sessions.
+
+### Changed
+
+- **Removed per-item truncation, raised batch cap.** Deleted the `ITEM_MAX_CHARS` (2 000) constant — it was silently cutting real agent work mid-word. `BATCH_MAX_CHARS` raised from 8 000 → 16 000 (~4K tokens). The batch cap is a soft limit: the first item is always included even if oversized, so one large message fills the batch alone and defers others to the next flush.
+
+### Fixed
+
+- **`flushInbox()` used `pi.isIdle()` instead of `ctx.isIdle()`.** `isIdle()` lives on `ExtensionContext`, not `ExtensionAPI`. Fixed to use the stored `ctx`.
+
+---
+
+## 0.1.7 — 2026-04-09
+
+### Added
+
+- **Bundled `pi-link-coordination` skill.** The coordination guide is now shipped with the package via `pi.skills` manifest entry. Installing pi-link now auto-loads the skill — no manual copy required. The skill provides on-demand guidance for agents delegating work across terminals: tool selection (`link_prompt` vs `link_send`), the golden rule (no sync-after-async on same target), callback contracts, and coordination modes.
 
 ---
 
 ## 0.1.6 — 2026-04-03
 
+**Pi 0.65.0 migration.** Pi removed `session_switch` and `session_fork` events. All session transitions (startup, reload, `/new`, `/resume`, `/fork`) now fire `session_start` with `event.reason`. Each transition tears down the old extension runtime via `session_shutdown` before creating a fresh one — so there is no live connection to update in-place across sessions.
+
 ### Added
 
-- **Persistent connection intent.** `/link-connect` and `/link-disconnect` now save their state to the session via `pi.appendEntry("link-active", ...)`. On `session_start`, the saved preference is checked before falling back to `--link`. Connect once and it stays connected across session resumes without needing the flag.
+- **Persistent connection intent.** `/link-connect` and `/link-disconnect` now save their state to the session via `pi.appendEntry("link-active", ...)`. On `session_start`, the saved preference is checked before falling back to `--link`. Connect once and it stays connected across session resumes without needing the flag. Explicit user intent (`link-active`) takes precedence over the `--link` flag default.
 
 ### Removed
 
-- **`cwd_update` message type.** Working directories are now only reported on connect (via `register`/`welcome`), not mid-session. Protocol returns to 9 message types.
+- **`cwd_update` message type.** With the old `session_switch` gone, mid-session cwd changes have no trigger. Working directories are now only reported on connect (via `register`/`welcome`). Protocol returns to 9 message types.
 
-- **`session_switch` handler.** Removed the session-switch logic that handled name and cwd changes on `/resume`. Simplifies the lifecycle.
+- **`session_switch` handler.** The 77-line in-place mutation matrix (hub rename, cwd diffing, client reconnect) is dead under the new lifecycle. Replaced by a unified `session_start` handler + `shouldConnect()` helper.
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # pi-link
 
-A WebSocket-based inter-terminal communication system that creates a local network between multiple Pi coding agent terminals. Enables terminals to discover each other, exchange messages, and orchestrate work across agents — all automatically on `localhost`.
+A WebSocket-based inter-terminal communication system that creates a local network between multiple Pi coding agent terminals. Enables terminals to discover each other, exchange messages, and orchestrate work across agents - all automatically on `localhost`.
 
 > Self-contained TypeScript in a single `index.ts` file. Start Pi with `--link` to enable.
 
@@ -27,10 +27,10 @@ A WebSocket-based inter-terminal communication system that creates a local netwo
 
 A single Pi terminal is powerful. Multiple terminals working together unlock new patterns:
 
-- **Research + Build** — one terminal investigates APIs, docs, or logs while another writes code based on the findings.
-- **Fan-out** — split a large task across agents (e.g., "terminal A handles the backend, terminal B handles the frontend") and collect results.
-- **Orchestrator / Worker** — designate one terminal as a coordinator that delegates subtasks to others via `link_prompt` and assembles the final output.
-- **Review pipeline** — one terminal writes code, another reviews it, back and forth until both are satisfied.
+- **Research + Build** - one terminal investigates APIs, docs, or logs while another writes code based on the findings.
+- **Fan-out** - split a large task across agents (e.g., "terminal A handles the backend, terminal B handles the frontend") and collect results.
+- **Orchestrator / Worker** - designate one terminal as a coordinator that delegates subtasks to others via `link_prompt` and assembles the final output.
+- **Review pipeline** - one terminal writes code, another reviews it, back and forth until both are satisfied.
 
 ---
 
@@ -63,7 +63,7 @@ Link is **off by default**. Start Pi with the `--link` flag to auto-connect on s
 Terminal 1                            Terminal 2
 ----------                            ----------
 $ pi --link                           $ pi --link
-✓ Link hub on :9900 as "t-a1b2"      ✓ Joined link as "t-c3d4" (2 online)
+✓ Link hub started on :9900 as "t-a1b2"  ✓ Joined link as "t-c3d4" (2 online)
 ```
 
 Already in a session without `--link`? You can connect mid-session with `/link-connect`.
@@ -76,7 +76,7 @@ Use `/link` in any terminal to check status, or let the LLM tools handle cross-t
 
 Here's a concrete example of two terminals collaborating. Open two separate `pi --link` sessions.
 
-**Terminal 1** — rename and check status:
+**Terminal 1** - rename and check status:
 
 ```
 > /link-name builder
@@ -90,7 +90,7 @@ Here's a concrete example of two terminals collaborating. Open two separate `pi
     cwd: ~/my-project
 ```
 
-**Terminal 2** — rename it too:
+**Terminal 2** - rename it too:
 
 ```
 > /link-name researcher
@@ -124,7 +124,7 @@ Every other terminal sees:
 
 ## Configuration
 
-Link is **off by default**. Without `--link`, the extension is completely silent — no status bar, no connections, no warnings.
+Link is **off by default**. Without `--link`, the extension is completely silent - no status bar, no connections, no warnings.
 
 | Method             | When                                | Auto-reconnect?                  |
 | ------------------ | ----------------------------------- | -------------------------------- |
@@ -132,7 +132,7 @@ Link is **off by default**. Without `--link`, the extension is completely silent
 | `/link-connect`    | Opt-in mid-session (no flag needed) | Yes                              |
 | `/link-disconnect` | Opt-out mid-session                 | Suppressed until `/link-connect` |
 
-`/link-connect` enables full participation in Pi Link regardless of whether `--link` was passed. `/link-disconnect` always wins — even over `--link` — until you explicitly `/link-connect` again.
+`/link-connect` enables full participation in Pi Link regardless of whether `--link` was passed. Both `/link-connect` and `/link-disconnect` save their intent to the session - resume that session later and the connection state is restored without needing the flag. Explicit user intent takes precedence over `--link`.
 
 Once connected, terminals discover each other on `127.0.0.1:9900`. See [Limitations](#limitations--design-decisions) for the hardcoded port.
 
@@ -140,7 +140,7 @@ Once connected, terminals discover each other on `127.0.0.1:9900`. See [Limitati
 
 ## LLM Tools
 
-The extension registers three tools that the LLM can invoke during agent runs.
+The extension registers three tools that the LLM can invoke during agent runs. pi-link also ships with a bundled **pi-link-coordination** skill that gives agents on-demand guidance for tool selection, delegation patterns, and avoiding common coordination mistakes.
 
 ### Which tool should I use?
 
@@ -162,9 +162,11 @@ Send a fire-and-forget chat message to a specific terminal or broadcast to all.
 | `message`     | `string`  | Message content                                      |
 | `triggerTurn` | `boolean` | If `true`, the receiver's LLM responds automatically |
 
-When `triggerTurn` is enabled, the message is delivered via `pi.sendMessage` with `deliverAs: "steer"`, causing the remote agent to kick off an LLM turn. Note: `triggerTurn` does **not** cause the response to come back to the caller — use `link_prompt` for that.
+When `triggerTurn` is enabled, the message is queued in the receiver's local inbox. Nearby arrivals are coalesced (200ms debounce), and delivery is gated on the receiving agent being idle - ensuring it starts a clean new turn. Messages arrive as a single `[Link: N message(s) received]` block at the top of a fresh turn, not mid-run. When `triggerTurn` is `false` or omitted, delivery is immediate fire-and-forget.
 
-> **Broadcast note:** Sending to `"*"` delivers to **all other terminals** — the sender is excluded.
+Note: `triggerTurn` does **not** cause the response to come back to the caller - use `link_prompt` for that.
+
+> **Broadcast note:** Sending to `"*"` delivers to **all other terminals** - the sender is excluded.
 
 Pre-validates the target name against the local terminal list before sending, catching typos early. See [Message Routing](#message-routing--error-handling) for delivery semantics.
 
@@ -177,12 +179,12 @@ Send a prompt to a remote terminal and **wait** for the LLM's response (synchron
 | `to`      | `string` | Target terminal name |
 | `prompt`  | `string` | Prompt text to send  |
 
-- The remote terminal processes the prompt via `pi.sendUserMessage()` — as if a user typed it.
+- The remote terminal processes the prompt via `pi.sendUserMessage()` - as if a user typed it.
 - Returns the remote terminal's actual assistant reply text as the tool result.
-- **Self-target rejection** — prompting yourself (`to` equals your own name) returns an immediate error.
-- **Heartbeat-based timeout** — no short fixed deadline. The target sends keepalives every 30s while working. The sender resets a 90-second inactivity timer on each keepalive. A 30-minute hard ceiling acts as a safety net against broken-but-chatty targets. A 10-minute task with regular activity never times out; a genuinely dead target times out in 90 seconds of silence.
-- **Immediate failure on disconnect** — if the target leaves the network (`terminal_left`), pending prompts to that target fail immediately instead of waiting for the inactivity timeout.
-- **Early failure detection** — if the message can't be delivered (e.g., target not found), the tool resolves immediately with an error instead of waiting for the timeout.
+- **Self-target rejection** - prompting yourself (`to` equals your own name) returns an immediate error.
+- **Heartbeat-based timeout** - no short fixed deadline. The target sends keepalives every 30s while working. The sender resets a 90-second inactivity timer on each keepalive. A 30-minute hard ceiling acts as a safety net against broken-but-chatty targets. A 10-minute task with regular activity never times out; a genuinely dead target times out in 90 seconds of silence.
+- **Immediate failure on disconnect** - if the target leaves the network (`terminal_left`), pending prompts to that target fail immediately instead of waiting for the inactivity timeout.
+- **Early failure detection** - if the message can't be delivered (e.g., target not found), the tool resolves immediately with an error instead of waiting for the timeout.
 - Supports abort signals.
 - Targets **one terminal at a time** (no broadcast mode).
 - Only **one remote prompt** can execute at a time per target terminal. Concurrent requests are rejected with `"Terminal is busy"`.
@@ -193,7 +195,7 @@ Lists all connected terminals with role info, live agent status, working directo
 
 Each terminal reports its current working directory on connect. `link_list` shows the full absolute path so agents can choose the right target, use explicit paths when terminals differ, and catch wrong-project mistakes early.
 
-Each terminal's status is derived automatically from Pi lifecycle events — agents can't set it manually. Three states:
+Each terminal's status is derived automatically from Pi lifecycle events - agents can't set it manually. Three states:
 
 | Status            | Meaning                 |
 | ----------------- | ----------------------- |
@@ -201,7 +203,7 @@ Each terminal's status is derived automatically from Pi lifecycle events — age
 | `thinking (3s)`   | LLM is generating       |
 | `tool:bash (12s)` | Running a specific tool |
 
-Durations are computed at render time from a `since` timestamp — no timer traffic over the wire. Terminals that just joined with no status data yet render as blank, not fake idle.
+Durations are computed at render time from a `since` timestamp - no timer traffic over the wire. Terminals that just joined with no status data yet render as blank, not fake idle.
 
 Working directories use full absolute paths in tool output. In the TUI (`/link`), paths are shortened to `~/...` when possible to keep the display compact.
 
@@ -245,19 +247,20 @@ Connected terminals:
 ✓ Renamed to "orchestrator"
 
 > /link-name
-✓ Renamed to "my-session"          (adopts Pi session name)
+✓ Renamed to "my-session"
 
 > /link-broadcast starting the build pipeline
 ✓ Broadcast sent
 
 > /link-disconnect
-✓ Disconnected from Pi Link
+✓ Disconnected from link
 
 > /link-connect
-✓ Joined Pi Link as "orchestrator" (3 online)    ... or ...
-✓ Pi Link hub started on :9900 as "orchestrator" ... if no hub exists
+✓ Joined link as "orchestrator" (3 online)
 ```
 
+With no argument, `/link-name` adopts the Pi session name. `/link-connect` joins an existing hub if one is running; otherwise it starts the hub.
+
 **Name persistence:** `/link-name` saves your preferred name to the session. Resume later and it's restored automatically. If the name is taken, the hub assigns a variant (e.g., `"builder-2"`), but your preferred name stays saved for the next reconnect. See [Name Uniqueness & Persistence](#name-uniqueness--persistence) for details.
 
 See [Configuration](#configuration) for details on `--link`, `/link-connect`, and `/link-disconnect` behavior.
@@ -284,7 +287,7 @@ The network topology is **hub-spoke (star)**:
           +-------+      +-------+      +-------+
 ```
 
-- The **first terminal** to start becomes the **hub** — it runs a `WebSocketServer` on `127.0.0.1:9900`.
+- The **first terminal** to start becomes the **hub** - it runs a `WebSocketServer` on `127.0.0.1:9900`.
 - **Subsequent terminals** connect as **clients** via plain WebSocket.
 - All messages route **through the hub**; clients never talk directly to each other.
 
@@ -296,13 +299,13 @@ The sequence is a simple fallback:
 
 1. Attempt to connect as a **client** to `127.0.0.1:9900`.
 2. If connection fails → become the **hub** (start a WebSocket server on that port).
-3. If both fail (rare race condition) → retry after a randomized 2–5 second backoff.
+3. If both fail (rare race condition) → retry after a randomized 2-5 second backoff.
 
 ### Hub Promotion
 
 When the hub disconnects, clients detect the WebSocket close event, enter `"disconnected"` state, and call `scheduleReconnect()`. The **first terminal to retry** becomes the new hub via the same initialize-or-fallback flow.
 
-There is **no explicit leader election** — promotion is race-based.
+There is **no explicit leader election** - promotion is race-based.
 
 ---
 
@@ -310,7 +313,7 @@ There is **no explicit leader election** — promotion is race-based.
 
 ### Port 9900 is already in use
 
-If another process occupies port 9900, the terminal can't become the hub. It will attempt to connect as a client instead (which also fails if there's no real hub), then retry after 2–5 seconds. Free the port or modify `DEFAULT_PORT` in `index.ts` — see [Limitations](#limitations--design-decisions).
+If another process occupies port 9900, the terminal can't become the hub. It will attempt to connect as a client instead (which also fails if there's no real hub), then retry after 2-5 seconds. Free the port or modify `DEFAULT_PORT` in `index.ts` - see [Limitations](#limitations--design-decisions).
 
 ### "Terminal is busy" rejections
 
@@ -328,7 +331,7 @@ Each terminal can only execute **one remote prompt at a time**. If a `link_promp
 
 ### Hub promotion loses state
 
-When the hub goes down and a client promotes itself, terminal names and in-flight prompts from the old hub session are lost. All surviving clients reconnect and re-register. This is by design — see [Limitations](#limitations--design-decisions).
+When the hub goes down and a client promotes itself, terminal names and in-flight prompts from the old hub session are lost. All surviving clients reconnect and re-register. This is by design - see [Limitations](#limitations--design-decisions).
 
 ---
 
@@ -339,7 +342,7 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
 | 1   | **No authentication**                     | Any localhost process can connect to port 9900. Acceptable for local dev; don't expose the port externally.                                                                                                     |
 | 2   | **Hardcoded port (9900)**                 | Not configurable without editing `DEFAULT_PORT` in `index.ts`. Could conflict with other services on the same port.                                                                                             |
 | 3   | **Race-based hub promotion**              | Non-deterministic. Terminal state (names, in-flight prompts) is lost during promotion. Simple but imperfect.                                                                                                    |
-| 4   | **Single remote prompt per terminal**     | No queuing — immediate rejection if busy. See [`link_prompt`](#link_prompt) and [Troubleshooting](#terminal-is-busy-rejections).                                                                                |
+| 4   | **Single remote prompt per terminal**     | No queuing - immediate rejection if busy. See [`link_prompt`](#link_prompt) and [Troubleshooting](#terminal-is-busy-rejections).                                                                                |
 | 5   | **No message persistence**                | Purely ephemeral WebSocket frames. Messages are lost if the recipient is offline.                                                                                                                               |
 | 6   | **Client rename triggers full reconnect** | Changing a client's name requires a new `register` message, so the client disconnects and reconnects. Hub renames are handled in-place with collision checks.                                                   |
 | 7   | **Single-machine / localhost-only**       | Link only binds to `127.0.0.1`; terminals on different machines cannot join.                                                                                                                                    |
@@ -374,7 +377,6 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
 ```json
 {
   "name": "pi-link",
-  "private": true,
   "dependencies": {
     "ws": "^8.20.0"
   },
@@ -382,12 +384,13 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
     "@types/ws": "^8.18.1"
   },
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": ["./index.ts"],
+    "skills": ["./skills"]
   }
 }
 ```
 
-The `pi.extensions` field tells Pi which files to load as extensions. Here it points to `./index.ts`, which Pi compiles and registers on startup.
+The `pi.extensions` field tells Pi which files to load as extensions. `pi.skills` registers bundled skill directories - the `pi-link-coordination` skill is loaded automatically on install.
 
 ---
 
@@ -463,7 +466,7 @@ The hub enforces unique terminal names via a `uniqueName()` function. If `"build
 
 Default names are random 4-character hex IDs: `t-a1b2`, `t-c3d4`, etc.
 
-**Persistence:** `/link-name` saves the preferred name to the session via `pi.appendEntry("link-name", { name })`. On session resume, the saved name is restored and requested from the hub. Only explicit `/link-name` calls persist — hub-assigned variants like `"builder-2"` are not saved. On reconnect, the terminal always requests the preferred name, not the last runtime name.
+**Persistence:** `/link-name` saves the preferred name to the session via `pi.appendEntry("link-name", { name })`. On session resume, the saved name is restored and requested from the hub. Only explicit `/link-name` calls persist - hub-assigned variants like `"builder-2"` are not saved. On reconnect, the terminal always requests the preferred name, not the last runtime name.
 
 **Rename guards:**
 
@@ -482,6 +485,8 @@ Default names are random 4-character hex IDs: `t-a1b2`, `t-c3d4`, etc.
 | `activeToolName`         | `string \| null`                      | Name of the currently executing tool (drives `tool:<name>` status)                          |
 | `stateSince`             | `number`                              | Timestamp of last status change (used for duration display)                                 |
 | `currentCwd`             | `string`                              | Current working directory reported to peers on connect                                      |
+| `inbox`                  | `array`                               | Queued `triggerTurn:true` messages awaiting idle-gated flush                                |
+| `flushTimer`             | `Timer \| null`                       | Pending inbox flush (debounce or busy-retry)                                                |
 | `manuallyDisconnected`   | `boolean`                             | Set by `/link-disconnect`; suppresses auto-reconnect                                        |
 | `pendingRemotePrompt`    | `object \| null`                      | Tracks the single in-flight remote prompt execution                                         |
 | `pendingPromptResponses` | `Map`                                 | Outstanding prompt RPCs awaiting responses (includes inactivity + ceiling timers per entry) |
@@ -490,31 +495,52 @@ Default names are random 4-character hex IDs: `t-a1b2`, `t-c3d4`, etc.
 
 `routeMessage()` returns a `boolean` indicating delivery status:
 
-- **Hub** — delivery is authoritative. If the target terminal isn't connected, the hub sends a protocol-level error back to the sender. For `prompt_request` messages to unknown targets, the hub sends a `prompt_response` with an error field so the sender's pending promise resolves immediately rather than timing out.
-- **Client** — delivery is optimistic (`true` means "sent to hub"). The hub handles routing and errors via the protocol.
+- **Hub** - delivery is authoritative. If the target terminal isn't connected, the hub sends a protocol-level error back to the sender. For `prompt_request` messages to unknown targets, the hub sends a `prompt_response` with an error field so the sender's pending promise resolves immediately rather than timing out.
+- **Client** - delivery is optimistic (`true` means "sent to hub"). The hub handles routing and errors via the protocol.
 
 ### Connection Lifecycle
 
 Internally, teardown is split into two functions:
 
-- **`disconnect()`** — closes sockets, clears connection state, resolves pending promises. Used by `/link-disconnect` and called internally by `cleanup()`.
-- **`cleanup()`** — calls `disconnect()` then marks the extension as disposed. Used on `session_shutdown`.
+- **`disconnect()`** - closes sockets, clears connection state, resolves pending promises. Used by `/link-disconnect` and called internally by `cleanup()`.
+- **`cleanup()`** - calls `disconnect()` then marks the extension as disposed. Used on `session_shutdown`.
 
-The `manuallyDisconnected` flag distinguishes user-initiated disconnects (`/link-disconnect`) from connection loss. When set, `scheduleReconnect()` is suppressed — the terminal stays offline until `/link-connect` is explicitly called.
+The `manuallyDisconnected` flag distinguishes user-initiated disconnects (`/link-disconnect`) from connection loss. When set, `scheduleReconnect()` is suppressed - the terminal stays offline until `/link-connect` is explicitly called.
 
 ### Agent Lifecycle Integration
 
 The extension hooks into Pi's agent lifecycle events:
 
 - **`agent_start`** → Sets `agentRunning = true`, blocking incoming remote prompts. Broadcasts `status_update` (`thinking`).
-- **`agent_end`** → Checks if a remote prompt was running. If so, extracts the last assistant response from `event.messages` and sends back a `prompt_response`. Broadcasts `status_update` (`idle`).
+- **`agent_end`** → Wakes up the inbox flush (idle-gated delivery for `triggerTurn:true` messages). Checks if a remote prompt was running; if so, extracts the last assistant response from `event.messages` and sends back a `prompt_response`. Broadcasts `status_update` (`idle`).
 - **`tool_execution_start`** → Broadcasts `status_update` (`tool:<name>`).
 - **`tool_execution_end`** → Clears tool status; broadcasts `status_update` (`thinking`) while the agent run continues.
 - **`session_shutdown`** → Full cleanup via `cleanup()`: closes all sockets, resolves pending promises, and disposes the extension.
 
 Status updates are push-based: each terminal broadcasts changes to the hub, which fans them out. New joiners receive a status snapshot for all terminals in the `welcome` message.
 
-While executing a remote prompt, the target sends a forced `status_update` every 30 seconds as a keepalive — reusing the existing status push mechanism. On the sender side, each incoming `status_update` from the target resets the 90-second inactivity timer. All resolution paths (response, inactivity, ceiling, abort, disconnect, delivery failure) go through a single `cleanupPending()` helper to prevent double-resolution races.
+While executing a remote prompt, the target sends a forced `status_update` every 30 seconds as a keepalive - reusing the existing status push mechanism. On the sender side, each incoming `status_update` from the target resets the 90-second inactivity timer. All resolution paths (response, inactivity, ceiling, abort, disconnect, delivery failure) go through a single `cleanupPending()` helper to prevent double-resolution races.
+
+### Idle-Gated Inbox
+
+When a `chat` message arrives with `triggerTurn:true`, it goes into a local inbox instead of calling `pi.sendMessage()` immediately. This avoids a Pi platform race where steering messages sent mid-agent-run can be stranded (see `REPORT-sendMessage-race.md`).
+
+The flush pipeline:
+
+1. **Debounce** - `scheduleFlush(FLUSH_DELAY_MS)` coalesces burst arrivals (200ms window).
+2. **Idle gate** - `flushInbox()` checks `ctx.isIdle()`. If busy, retries every 500ms.
+3. **Batch** — up to 20 messages or ~16 000 chars per delivery (soft cap — the first item is always included even if oversized).
+4. **Deliver** — one `pi.sendMessage({ triggerTurn: true })` call with a `[Link: N message(s) received]` block.
+5. **Drain** — if the inbox still has items, reschedule.
+
+On `agent_end`, the inbox flush is kicked via `scheduleFlush(0)` — deferred to the next macrotask, by which time `ctx.isIdle()` returns `true`.
+
+| Constant          | Value  | Purpose                                  |
+| ----------------- | ------ | ---------------------------------------- |
+| `FLUSH_DELAY_MS`  | 200    | Burst debounce window                    |
+| `IDLE_RETRY_MS`   | 500    | Busy-retry polling interval              |
+| `BATCH_MAX_ITEMS` | 20     | Max messages per batch                   |
+| `BATCH_MAX_CHARS` | 16 000 | Soft cap on batch text size (~4K tokens) |
 
 ### Rendering
 

package/index.ts

@@ -28,6 +28,10 @@ const PROMPT_INACTIVITY_MS = 90_000;
 const PROMPT_HARD_CEILING_MS = 1_800_000;
 const RECONNECT_DELAY_MS = 2000;
 const KEEPALIVE_INTERVAL_MS = 30_000;
+const FLUSH_DELAY_MS = 200;
+const IDLE_RETRY_MS = 500;
+const BATCH_MAX_ITEMS = 20;
+const BATCH_MAX_CHARS = 16_000;
 
 // ─── Protocol ────────────────────────────────────────────────────────────────
 
@@ -159,6 +163,10 @@ export default function (pi: ExtensionAPI) {
   let pendingRemotePrompt: { id: string; from: string } | null = null;
   let keepaliveTimer: ReturnType<typeof setInterval> | null = null;
 
+  // Inbox: idle-gated batched delivery for triggerTurn:true messages
+  const inbox: { from: string; content: string }[] = [];
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
   // ── Helpers ──────────────────────────────────────────────────────────────
 
   function updateStatus() {
@@ -234,6 +242,54 @@ export default function (pi: ExtensionAPI) {
     return normalized;
   }
 
+  // ── Inbox: idle-gated batched delivery ───────────────────────────────────
+
+  function scheduleFlush(delay: number) {
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(flushInbox, delay);
+  }
+
+  function flushInbox() {
+    flushTimer = null;
+    if (inbox.length === 0) return;
+    if (!ctx) return;
+
+    // Only deliver when idle so triggerTurn takes the prompt-start path
+    // instead of mid-run steering, avoiding async delivery loss.
+    if (!ctx.isIdle()) {
+      scheduleFlush(IDLE_RETRY_MS);
+      return;
+    }
+
+    // Select batch: up to BATCH_MAX_ITEMS, ~BATCH_MAX_CHARS total (soft cap —
+    // first item always included even if oversized, others deferred to next flush)
+    const batch: string[] = [];
+    let totalChars = 0;
+    for (let i = 0; i < inbox.length && batch.length < BATCH_MAX_ITEMS; i++) {
+      const item = inbox[i];
+      const text = `From "${item.from}":\n${item.content}`;
+      if (batch.length > 0 && totalChars + text.length > BATCH_MAX_CHARS) break;
+      batch.push(text);
+      totalChars += text.length;
+    }
+
+    pi.sendMessage(
+      {
+        customType: "link",
+        content: `[Link: ${batch.length} message(s) received]\n\n${batch.join("\n\n")}`,
+        display: true,
+        details: { batched: true, count: batch.length },
+      },
+      { triggerTurn: true },
+    );
+    inbox.splice(0, batch.length);
+
+    // Reschedule if inbox still has items; agent_end wakeup will usually beat this
+    if (inbox.length > 0) {
+      scheduleFlush(IDLE_RETRY_MS);
+    }
+  }
+
   // ── Connection intent ──────────────────────────────────────────────────
 
   function shouldConnect(_ctx: ExtensionContext): boolean {
@@ -449,15 +505,20 @@ export default function (pi: ExtensionAPI) {
 
       // ── Chat message ──
       case "chat":
-        pi.sendMessage(
-          {
-            customType: "link",
-            content: msg.content,
-            display: true,
-            details: { from: msg.from },
-          },
-          { triggerTurn: msg.triggerTurn, deliverAs: "steer" },
-        );
+        if (msg.triggerTurn) {
+          inbox.push({ from: msg.from, content: msg.content });
+          scheduleFlush(FLUSH_DELAY_MS);
+        } else {
+          pi.sendMessage(
+            {
+              customType: "link",
+              content: msg.content,
+              display: true,
+              details: { from: msg.from },
+            },
+            { triggerTurn: false, deliverAs: "steer" },
+          );
+        }
         break;
 
       // ── Another terminal asks us to run a prompt ──
@@ -767,11 +828,23 @@ export default function (pi: ExtensionAPI) {
     lastPushedKind = null;
     lastPushedTool = null;
     updateStatus();
+
+    // Inbox survives disconnect — messages are local state waiting for local delivery.
+    // Ensure pending flush still fires.
+    if (inbox.length > 0 && !flushTimer) {
+      scheduleFlush(FLUSH_DELAY_MS);
+    }
   }
 
   function cleanup() {
     disposed = true;
     disconnect();
+    // Full teardown: clear inbox and flush timer
+    inbox.length = 0;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
   }
 
   // ── Lifecycle events ─────────────────────────────────────────────────────
@@ -791,6 +864,11 @@ export default function (pi: ExtensionAPI) {
     if (saved?.data?.name) {
       preferredName = saved.data.name;
       terminalName = preferredName;
+    } else {
+      // No explicit link-name: fall back to session name as a better default than t-xxxx
+      const sessionName = pi.getSessionName()?.trim().replace(/\s+/g, " ");
+      if (sessionName) terminalName = sessionName;
+      // NOT saved as preferredName — only /link-name persists
     }
 
     if (shouldConnect(_ctx)) await initialize();
@@ -825,6 +903,10 @@ export default function (pi: ExtensionAPI) {
     stateSince = Date.now();
     pushStatus();
 
+    // Wake up inbox flush — agent_end fires before finishRun(), so ctx.isIdle()
+    // is still false here. scheduleFlush(0) defers to next macrotask when idle.
+    if (inbox.length > 0) scheduleFlush(0);
+
     // If we were running a remote prompt, send the response back
     if (pendingRemotePrompt) {
       const { id, from } = pendingRemotePrompt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-link",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",
@@ -25,6 +25,9 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/pi-link-coordination/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: pi-link-coordination
+description: Guidance for coordinating work across Pi terminals using pi-link. Use when delegating tasks, choosing between link_prompt and link_send, planning async vs sync work, batching parallel jobs, or avoiding busy/conflict patterns.
+---
+
+# Pi-Link Coordination
+
+How to coordinate work across Pi terminals via pi-link.
+
+---
+
+## Tool Selection Rule
+
+- Need the answer back now? → `link_prompt`
+- Need autonomous work done? → `link_send(triggerTurn: true)`
+- Need to notify only? → `link_send(triggerTurn: false)`
+
+---
+
+## The Golden Rule
+
+> After `link_send(triggerTurn: true)` to terminal X, do not `link_prompt` X until X sends a completion callback.
+
+Pick one mode per terminal per task. Mixing sync and async on the same terminal is the most common coordination failure.
+
+---
+
+## The Tools
+
+### `link_list`
+
+Returns connected terminals with names, live status (`idle`, `thinking`, `tool:<name>`), and working directory (cwd). Use before delegating when availability or path context is uncertain.
+
+### `link_prompt`
+
+Synchronous RPC. Send a prompt, wait for the response.
+
+- Fails immediately if target is missing, self, disconnects, or busy (local work or another remote prompt)
+- 90s inactivity timeout, 30min hard ceiling
+- Remote agent doesn't share your context — prompts must be self-contained
+- Include: goal, scope, constraints, output format, done condition
+
+### `link_send`
+
+Fire-and-forget. Send to one terminal or `to: "*"` to broadcast (excludes sender).
+
+Set `triggerTurn: true` to activate the receiver's LLM. The sender does **not** get the response back.
+
+**Callback contract for `triggerTurn: true`:** ask the receiver to reply via `link_send` with:
+
+- `DONE` signal
+- Output paths / artifacts created
+- Blockers or open questions
+
+---
+
+## Operating Constraints
+
+- **One remote prompt at a time per target.** Concurrent requests rejected as busy.
+- **No shared context.** Every remote prompt must be self-contained.
+- **Messages are ephemeral.** Offline terminals lose messages.
+- **Localhost only.** Same machine.
+- **Cwd is a hint, not proof.** Same cwd ≠ same workspace/branch/access. Use explicit paths; absolute when cwds differ or shared-root assumptions are unclear.
+- **Naming:** `role@domain` (e.g., `builder@pi-link`). Only talk to your own domain unless told otherwise.
+
+---
+
+## Coordination Modes
+
+### Sync ask — `link_prompt`
+
+For answers, review, analysis you need back now. One terminal at a time. Keep scope focused to avoid timeout.
+
+### Async delegate — `link_send(triggerTurn: true)`
+
+For autonomous work. Require the callback contract (DONE + paths + blockers). Do your own work in parallel. Don't `link_prompt` the target until the callback arrives.
+
+### Parallel batch — async to multiple terminals
+
+Distribute independent tasks. Use explicit paths (absolute if cwds differ). Wait for all callbacks, then synthesize. Don't prompt any dispatched terminal until its callback arrives.
+
+---
+
+## Anti-Patterns
+
+**❌ Mixing async and sync on the same terminal**
+Dispatched with `link_send(triggerTurn: true)` then sent a `link_prompt` → rejected as busy. See Golden Rule.
+
+**❌ Using `link_send` when you need the response**
+Result disappears. Use `link_prompt`.
+
+**❌ Vague prompts**
+"Fix the bug" is useless. Include file, line, root cause, expected fix.
+
+**❌ No completion callback on async work**
+Always require DONE + artifact paths + blockers.
+
+**❌ Circular delegation**
+A → B → C → A = deadlock. Maintain clear hierarchy.
+
+**❌ Skipping `link_list` before retrying a busy target**
+Check status before re-sending.
+
+---
+
+## Quick Reference
+
+| I need to...                     | Tool                            | Mode            |
+| -------------------------------- | ------------------------------- | --------------- |
+| See who's available              | `link_list`                     | —               |
+| Get an answer from another agent | `link_prompt`                   | Synchronous     |
+| Delegate autonomous work         | `link_send(triggerTurn: true)`  | Asynchronous    |
+| Notify without activating        | `link_send(triggerTurn: false)` | Fire-and-forget |
+| Broadcast to all                 | `link_send(to: "*")`            | Broadcast       |