pi-link 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,7 +2,35 @@
 
 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.9 — 2026-04-22
+
+### Added
+
+- **`--link-name <name>` flag.** Connect to link with a chosen terminal name on startup. Implies `--link` (no need for both). Persists the name and sets the Pi session name if currently unnamed. Name precedence: `--link-name` > saved `/link-name` > session name > random `t-xxxx`.
+
+- **`pi-link start` CLI.** New bin script (`bin/pi-link.mjs`) for session-by-name resume. `pi-link start worker-1` scans `~/.pi/agent/sessions/` for a matching session name — one match resumes it, no match creates a new session, multiple matches prints candidates and exits. Extra Pi flags pass through: `pi-link start worker-1 --model sonnet --thinking high`. Local-cwd sessions prioritized.
+
+---
+
+## 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`.
 
 ---
 

package/README.md

@@ -1,8 +1,8 @@
 # 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.
+> Self-contained TypeScript in a single `index.ts` file. Start Pi with `--link` or `--link-name <name>` 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.
 
 ---
 
@@ -57,16 +57,23 @@ pi uninstall npm:pi-link
 
 ### Usage
 
-Link is **off by default**. Start Pi with the `--link` flag to auto-connect on startup:
+Link is **off by default**. Start Pi with `--link-name` to connect with a meaningful name:
 
 ```
 Terminal 1                            Terminal 2
 ----------                            ----------
-$ pi --link                           $ pi --link
-✓ Link hub on :9900 as "t-a1b2"      ✓ Joined link as "t-c3d4" (2 online)
+$ pi --link-name builder              $ pi --link-name reviewer
+✓ Link hub started on :9900 as "builder"  ✓ Joined link as "reviewer" (2 online)
 ```
 
-Already in a session without `--link`? You can connect mid-session with `/link-connect`.
+Or use `pi-link start` to resume an existing session by name (or create one):
+
+```bash
+pi-link start worker-1                # resume or create session "worker-1"
+pi-link start worker-1 --model sonnet # with extra Pi flags
+```
+
+`pi --link` also works (connects with an auto-generated name). Already in a session without either flag? Connect mid-session with `/link-connect`.
 
 Use `/link` in any terminal to check status, or let the LLM tools handle cross-terminal coordination.
 
@@ -76,7 +83,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 +97,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,23 +131,46 @@ 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` or `--link-name`, the extension is completely silent — no status bar, no connections, no warnings.
+
+| Method                  | When                                | Auto-reconnect?                  |
+| ----------------------- | ----------------------------------- | -------------------------------- |
+| `pi --link-name <name>` | Connect on startup with a name      | Yes                              |
+| `pi --link`             | Connect on startup (random name)    | Yes                              |
+| `pi-link start <name>`  | Resume/create session, connect      | Yes                              |
+| `/link-connect`         | Opt-in mid-session (no flag needed) | Yes                              |
+| `/link-disconnect`      | Opt-out mid-session                 | Suppressed until `/link-connect` |
+
+`--link-name` implies `--link` — no need for both. It also persists the name and sets the Pi session name if the session is currently unnamed.
 
-| Method             | When                                | Auto-reconnect?                  |
-| ------------------ | ----------------------------------- | -------------------------------- |
-| `pi --link`        | Auto-connect on startup             | Yes                              |
-| `/link-connect`    | Opt-in mid-session (no flag needed) | Yes                              |
-| `/link-disconnect` | Opt-out mid-session                 | Suppressed until `/link-connect` |
+**Name precedence:** `--link-name` flag > saved `/link-name` > Pi session name > random `t-xxxx`.
 
-`/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` and `/link-disconnect` save their intent to the session — resume 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.
 
+### `pi-link start`
+
+The `pi-link` CLI resolves sessions by display name:
+
+```bash
+pi-link start <name> [pi-flags...]
+```
+
+- Scans `~/.pi/agent/sessions/` for sessions with a matching name
+- **One match** → resumes that session with `--link-name <name>`
+- **No match** → starts a new session with `--link-name <name>`
+- **Multiple matches** → prints candidates (cwd, modified date, path) and exits
+- Extra Pi flags pass through: `pi-link start worker-1 --model sonnet --thinking high`
+- `--session` and `--link-name` cannot be passed as extra flags (managed by `pi-link start`)
+
+Sessions in the current working directory are prioritized when sorting candidates.
+
 ---
 
 ## 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 +192,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.
+
+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.
+> **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 +209,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 +225,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 +233,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 +277,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,25 +317,25 @@ 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.
 
 ### Auto-Discovery Protocol
 
-The discovery sequence runs on startup (with `--link`) or when `/link-connect` is used. See [Configuration](#configuration) for details.
+The discovery sequence runs on startup (with `--link` or `--link-name`) or when `/link-connect` is used. See [Configuration](#configuration) for details.
 
 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 +343,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 +361,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 +372,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 +407,9 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
 ```json
 {
   "name": "pi-link",
-  "private": true,
+  "bin": {
+    "pi-link": "./bin/pi-link.mjs"
+  },
   "dependencies": {
     "ws": "^8.20.0"
   },
@@ -382,12 +417,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.
+`pi.extensions` tells Pi which files to load as extensions. `pi.skills` registers bundled skill directories. `bin` exposes the `pi-link` CLI (see [Configuration](#configuration)).
 
 ---
 
@@ -463,7 +499,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 +518,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 +528,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/bin/pi-link.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+// pi-link CLI — resolve session by name and launch Pi with --link-name
+//
+// Usage:
+//   pi-link start <name> [pi-flags...]
+//
+// If a session named <name> exists, resumes it.
+// If not, creates a new session.
+// Always connects to the link as <name>.
+
+import { readdir, stat } from "fs/promises";
+import { createReadStream } from "fs";
+import { createInterface } from "readline";
+import { join } from "path";
+import { homedir } from "os";
+import { spawn } from "child_process";
+
+const SESSIONS_DIR = join(homedir(), ".pi", "agent", "sessions");
+
+// ── Session scanning ───────────────────────────────────────────────────────
+
+async function getSessionName(filePath) {
+  let name;
+  let cwd;
+  const rl = createInterface({ input: createReadStream(filePath, "utf-8"), crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line) continue;
+    try {
+      const entry = JSON.parse(line);
+      if (entry.type === "session" && entry.cwd) cwd = entry.cwd;
+      if (entry.type === "session_info" && entry.name !== undefined) {
+        name = entry.name?.trim() || undefined;
+      }
+    } catch {
+      // skip malformed lines
+    }
+  }
+  return { name, cwd };
+}
+
+async function findSessionsByName(targetName) {
+  let cwdDirs;
+  try {
+    cwdDirs = await readdir(SESSIONS_DIR, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const matches = [];
+
+  for (const dir of cwdDirs) {
+    if (!dir.isDirectory()) continue;
+    const dirPath = join(SESSIONS_DIR, dir.name);
+
+    let files;
+    try {
+      files = await readdir(dirPath);
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      if (!file.endsWith(".jsonl")) continue;
+      const filePath = join(dirPath, file);
+      try {
+        const { name, cwd } = await getSessionName(filePath);
+        if (name === targetName) {
+          const stats = await stat(filePath);
+          matches.push({ path: filePath, cwd: cwd || "?", modified: stats.mtime });
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  // Local-first: current cwd matches before others, then by modified time
+  const localCwd = process.cwd();
+  matches.sort((a, b) => {
+    const aLocal = a.cwd === localCwd ? 1 : 0;
+    const bLocal = b.cwd === localCwd ? 1 : 0;
+    if (aLocal !== bLocal) return bLocal - aLocal;
+    return b.modified.getTime() - a.modified.getTime();
+  });
+  return matches;
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command !== "start" || args.length < 2) {
+  console.log(`Usage: pi-link start <name> [pi-flags...]
+
+Start Pi connected to the link as <name>.
+Resumes a session named <name> if one exists, otherwise creates a new session.
+
+Examples:
+  pi-link start worker-1
+  pi-link start worker-1 --model sonnet
+  pi-link start worker-1 --model sonnet --thinking high`);
+  process.exit(command === "start" ? 1 : 0);
+}
+
+const name = args[1].trim().replace(/\s+/g, " ");
+if (!name) {
+  console.error("Error: name cannot be empty.");
+  process.exit(1);
+}
+
+const extraFlags = args.slice(2);
+for (const flag of ["--session", "--link-name"]) {
+  if (extraFlags.includes(flag)) {
+    console.error(`Error: ${flag} is managed by pi-link start. Remove it.`);
+    process.exit(1);
+  }
+}
+
+console.log(`Searching for session "${name}"...`);
+const matches = await findSessionsByName(name);
+
+const piArgs = [];
+
+if (matches.length === 1) {
+  console.log(`Resuming session: ${matches[0].path}`);
+  piArgs.push("--session", matches[0].path);
+} else if (matches.length > 1) {
+  console.error(`\nMultiple sessions named "${name}":\n`);
+  for (const m of matches) {
+    console.error(`  ${m.modified.toISOString().slice(0, 19)}  cwd: ${m.cwd}`);
+    console.error(`  ${m.path}\n`);
+  }
+  console.error(`Use pi --session <path> --link-name ${name} to pick one.`);
+  process.exit(1);
+} else {
+  console.log("No existing session found. Starting new session.");
+}
+
+piArgs.push("--link-name", name, ...extraFlags);
+
+// On Windows, resolve 'pi' through the shell so .cmd/.ps1 shims work
+const isWin = process.platform === "win32";
+const cmd = isWin ? "cmd" : "pi";
+const cmdArgs = isWin ? ["/c", "pi", ...piArgs] : piArgs;
+
+const child = spawn(cmd, cmdArgs, { stdio: "inherit" });
+
+child.on("exit", (code) => process.exit(code ?? 0));
+child.on("error", (err) => {
+  console.error(`Failed to start pi: ${err.message}`);
+  process.exit(1);
+});

package/index.ts

@@ -2,7 +2,7 @@
  * Pi Link — WebSocket-based inter-terminal communication
  *
  * Connects multiple Pi terminals over a local WebSocket link.
- * Opt-in via --link flag or /link-connect command.
+ * Opt-in via --link / --link-name flag or /link-connect command.
  * First terminal to connect becomes the hub; others join as clients.
  * Hub loss triggers automatic promotion of a surviving client.
  *
@@ -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 ────────────────────────────────────────────────────────────────
 
@@ -111,6 +115,11 @@ export default function (pi: ExtensionAPI) {
     default: false,
   });
 
+  pi.registerFlag("link-name", {
+    description: "Connect to link with this terminal name",
+    type: "string",
+  });
+
   // ── State ────────────────────────────────────────────────────────────────
 
   let role: "hub" | "client" | "disconnected" = "disconnected";
@@ -159,6 +168,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 +247,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 +510,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 +833,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 ─────────────────────────────────────────────────────
@@ -780,20 +858,35 @@ export default function (pi: ExtensionAPI) {
     ctx = _ctx;
     currentCwd = _ctx.cwd;
 
-    // Restore preferred link name from session
-    const saved = _ctx.sessionManager
-      .getEntries()
-      .filter(
-        (e: { type: string; customType?: string }) =>
-          e.type === "custom" && e.customType === "link-name",
-      )
-      .pop() as { data?: { name?: string } } | undefined;
-    if (saved?.data?.name) {
-      preferredName = saved.data.name;
-      terminalName = preferredName;
+    // Resolve terminal name: --link-name flag > saved link-name > session name > random
+    const rawLinkName = pi.getFlag("link-name");
+    const flagName =
+      typeof rawLinkName === "string"
+        ? rawLinkName.trim().replace(/\s+/g, " ") || undefined
+        : undefined;
+    if (flagName) {
+      preferredName = flagName;
+      terminalName = flagName;
+      pi.appendEntry("link-name", { name: flagName });
+      if (!pi.getSessionName()) pi.setSessionName(flagName);
+    } else {
+      const saved = _ctx.sessionManager
+        .getEntries()
+        .filter(
+          (e: { type: string; customType?: string }) =>
+            e.type === "custom" && e.customType === "link-name",
+        )
+        .pop() as { data?: { name?: string } } | undefined;
+      if (saved?.data?.name) {
+        preferredName = saved.data.name;
+        terminalName = preferredName;
+      } else {
+        const sessionName = pi.getSessionName()?.trim().replace(/\s+/g, " ");
+        if (sessionName) terminalName = sessionName;
+      }
     }
 
-    if (shouldConnect(_ctx)) await initialize();
+    if (flagName || shouldConnect(_ctx)) await initialize();
   });
 
   pi.on("session_shutdown", async () => {
@@ -825,6 +918,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,12 +1,15 @@
 {
   "name": "pi-link",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",
+  "bin": {
+    "pi-link": "./bin/pi-link.mjs"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/alvivar/pi-link"
+    "url": "git+https://github.com/alvivar/pi-link.git"
   },
   "keywords": [
     "pi-package",